GBase8c数据库登录操作指北

环境准备说明

数据库版本：GBase8cV5_S5.0.0B28
客户端操作系统：openEuler-22.03-LTS-SP4-x86_64（远程客户端）、Windows 10/11（DBeaver客户端）
核心工具：gsql客户端、DBeaver Community 25.3.3、Python 3.x（含psycopg2库）

关键配置：数据库浮动IP（172.31.100.230 ）、端口15400，需提前完成主备集群部署及VIP配置

本地登录数据库

注意事项

初始用户远程登录时会提示Forbid remote connection with initial user，出于安全限制，需手动创建远程连接用户并授予对应权限。
新创建的testuser默认仅具备登录和查看数据库权限，需手动配置管理员权限方可执行写入、建表等操作。
主备集群中，主节点支持gbase用户本地登录并执行写入操作，备节点仅开放只读权限，无法执行写入指令。

本地登录命令

-r参数,可tab键补全命令，可方向键上下查看历史命令

gsql -d postgres -p 15400 -r

用户权限属性说明

创建用户时可配置的权限属性如下（按需选择组合）：

postgres=# create user testuser with
ADMIN               IN GROUP            NOINHERIT           PASSWORD            SYSADMIN
AUDITADMIN          INHERIT             NOLOGIN             PERM SPACE          SYSID
CONNECTION LIMIT    IN ROLE             NOMONADMIN          PERSISTENCE         TEMP SPACE
CREATEDB            LOGIN               NOOPRADMIN          PGUSER              UNENCRYPTED
CREATEROLE          MONADMIN            NOPERSISTENCE       POLADMIN            USEFT
CREATEUSER          NOAUDITADMIN        NOPOLADMIN          PROFILE             USER
DEFAULT TABLESPACE  NOCREATEDB          NOREPLICATION       PROFILE DEFAULT     USER GROUP
ENCRYPTED           NOCREATEROLE        NOSYSADMIN          REPLICATION         VALID
IDENTIFIED BY       NOCREATEUSER        NOUSEFT             RESOURCE POOL       VCADMIN
IN                  NODE GROUP          NOVCADMIN           ROLE
INDEPENDENT         NOINDEPENDENT       OPRADMIN            SPILL SPACE

创建远程连接测试用户（授予系统管理员权限）

# 本地登录数据库
gsql -d postgres -p 15400 -r
# 创建用户并授予系统管理员权限
create user testuser with sysadmin identified by 'testuser-password';
# 退出数据库连接
\q

远程登录数据库（gsql和DBeaver）

服务端配置（主节点）

原理：与授权数据库通过浮动IP访问的逻辑一致，通过配置白名单限定可远程访问数据库的客户端IP，确保访问安全。

核心配置文件路径：/opt/database/install/data/dn/pg_hba.conf

配置允许客户端IP连接

# 配置指定IP访问权限，集群所有节点同步生效
gs_guc reload -N all -I all -h "host all all 172.31.100.235/32 sha256"

撤销客户端IP连接权限（扩展操作）

# 撤销指定IP段的连接权限，集群所有节点同步
# 注：gs_guc set仅将规则认证方式置空并注释该行，需重启数据库才生效
gs_guc set -N all -I all -h "host all all 172.31.100.x/32" 
# 重启数据库集群使配置生效
gs_om -t restart

gsql客户端连接

前置准备（可选）

可创建普通用户gbase用于日常操作，本文直接使用root用户演示，操作逻辑一致。

安装并配置gsql客户端

mkdir -p /opt/tools

从数据库主节点上传文件至客户端：需上传的文件/目录如下

安装包：GBase8cV5_S5.0.0B28_CentOS_x86_64.tar.bz2
依赖库：lib目录

# 数据库主节点执行：切换至软件包目录并上传
cd /opt/software/gbase8c/
sudo scp -r lib GBase8cV5_S5.0.0B28_CentOS_x86_64.tar.bz2 root@172.31.100.235:/opt/tools/

客户端解压文件：

cd /opt/tools/
tar -jxvf GBase8cV5_S5.0.0B28_CentOS_x86_64.tar.bz2

验证文件完整性：

# 验证bin目录下存在gsql可执行文件
ls bin/gsql 
# 验证lib目录下存在.so格式依赖库
ls lib/

配置全局环境变量：编辑/etc/profile文件，在末尾追加以下内容：

echo "export PATH=/opt/tools/bin:$PATH" >> /etc/profile
echo "export LD_LIBRARY_PATH=/opt/tools/lib:$LD_LIBRARY_PATH" >> /etc/profile

环境变量立即生效：

source /etc/profile

验证gsql安装：

gsql --version
# 预期输出示例：
# gsql (single_node GBase8cV5 S5.0.0B28 build 51dce1ce) compiled at 2024-06-21 17:06:17 commit 0 last mr 587

gsql登录数据库

gsql -d postgres -h 172.31.100.230 -p 15400 -U testuser -r

登录成功后验证用户权限：

[root@gbase8c ~]# gsql -d postgres -h 172.31.100.230 -p 15400 -U testuser
Password for user testuser:
gsql ((single_node GBase8cV5 S5.0.0B28 build 51dce1ce) compiled at 2024-06-21 17:06:17 commit 0 last mr 587 )
SSL connection (cipher: ECDHE-RSA-AES128-GCM-SHA256, bits: 128)
Type "help" for help.

postgres=> \du testuser
   List of roles
 Role name | Attributes | Member of
-----------+------------+-----------
 testuser  | Sysadmin   | {}

postgres=>

DBeaver客户端连接

安装DBeaver Community 25.3.3

支持安装版或压缩包版，本文使用压缩包版dbeaver-ce-25.3.3-win32.win32.x86_64.zip，无需安装，解压即可使用。

官方下载地址：https://dbeaver.io/download/
GitHub下载地址：https://github.com/dbeaver/dbeaver/releases
国内镜像地址：https://mirrors.cernet.edu.cn/app/DBeaverCE

运行方式：下载后解压至本地目录，双击dbeaver.exe启动客户端。

下载GBase8c JDBC驱动

下载文件：GBase8c_JDBC.zip

官方下载地址：https://www.gbase.cn/download/gbase-8c?category=DRIVER_PACKAGE

驱动下载页面：

配置JDBC驱动至DBeaver

解压GBase8c_JDBC.zip文件，提取内部的JDBC驱动jar包；
打开DBeaver客户端，点击菜单栏Database–>Driver Manager；
在弹出的对话框中点击New，输入驱动名称：8c（自定义，便于识别）；
点击Libraries–>Add File，选择解压后的JDBC驱动jar文件；
点击Find Class，系统自动识别驱动类com.gbase8c.Driver，选中并确认；
返回Setting选项卡，输入URL模板：jdbc:gbase8c://{host}:{port}/{database}，默认端口填写15400，默认数据库填写postgres，点击OK保存配置。

DBeaver登录数据库

点击菜单栏Database–>New Database Connection；
在弹出的对话框中找到并选择已配置的GBase8c驱动，点击Next；
输入连接信息：数据库浮动IP（172.31.100.230 ）、端口15400、用户名testuser及对应密码；
点击Test Connection测试连接，测试通过后点击OK关闭测试窗口；
点击Finish完成连接配置，双击左侧导航栏的数据库连接，即可成功接入GBase8c数据库。

权限问题处理

若创建表时提示权限不足，需在数据库本地使用gbase用户登录执行命令提升testuser权限：

alter user testuser sysadmin;

Python使用psycopg2库连接

前置准备（可选）

可创建普通用户gbase用于Python脚本操作，避免使用root用户执行脚本，本文直接使用root用户演示，操作步骤一致。

下载并配置驱动

驱动下载：选择对应版本（openGauss 6.0.0 (LTS)）、架构（x86_64）、操作系统（openEuler 22.03 LTS），确保驱动与系统及Python版本兼容。
下载地址：https://opengauss.org/zh/download/)
上传并解压驱动包：

# 创建存放目录
mkdir -p /opt/psycopg2
# 上传文件（示例文件名）：openGauss-Python-6.0.0-openEuler22.03-x86_64.tar.gz
# 解压文件
cd /opt/psycopg2
tar -zxvf openGauss-Python-6.0.0-openEuler22.03-x86_64.tar.gz

解压后目录结构示例：

[gbase@gbase8c psycopg2]$ ll
total 3176
drwxr-x---. 2 gbase gbase4096 Sep 29  2024 lib
-rw-r--r--. 1 gbase gbase 3243058 Jan 21 00:38 openGauss-Python-6.0.0-openEuler22.03-x86_64.tar.gz
drwxr-x---. 3 gbase gbase4096 Jan 21 00:39 psycopg2
[gbase@gbase8c psycopg2]$

配置环境变量：

# 永久配置（写入用户环境变量文件）
echo "export LD_LIBRARY_PATH=/opt/psycopg2/lib:\$LD_LIBRARY_PATH" >> ~/.bashrc
echo "export PYTHONPATH=/opt/psycopg2:\$PYTHONPATH" >> ~/.bashrc
# 使配置立即生效
source ~/.bashrc

验证psycopg2导入：

python3 -c "import psycopg2; print('psycopg2导入成功')"
# 预期输出：psycopg2导入成功

安装环境变量依赖包：

pip install python-dotenv

编写连接脚本

创建.env环境变量文件

与Python脚本放在同一目录，用于存储数据库连接信息，避免密码硬编码泄露风险：

GB_HOST=172.31.100.230
GB_PORT=15400
GB_USER=testuser
GB_PWD=testuser-password
GB_DB=postgres

编写连接测试脚本demo_01.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
GBase数据库表创建与查询脚本
功能：连接GBase数据库，创建test_table并查询表结构和数据
"""

import psycopg2
import os
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# 数据库连接配置
DB_CONFIG = {
    'host': os.getenv('GB_HOST', '172.31.100.230'),
    'port': int(os.getenv('GB_PORT', 15400)),
    'database': os.getenv('GB_DB', 'postgres'),
    'user': os.getenv('GB_USER', 'testuser'),
    'password': os.getenv('GB_PWD', ''),
    'connect_timeout': 5,
}

def main():
    conn = None
    try:
        # 1. 连接数据库
        conn = psycopg2.connect(**DB_CONFIG)
        conn.autocommit = True
        print(f"成功连接到GBase数据库：{DB_CONFIG['host']}:{DB_CONFIG['port']}/{DB_CONFIG['database']}")

        # 2. 创建表
        create_sql = """
        CREATE TABLE IF NOT EXISTS test_table (
            insert_seq INT PRIMARY KEY,
            insert_time TIMESTAMP DEFAULT now()
        );
        """
        with conn.cursor() as cur:
            cur.execute(create_sql)
        print("表test_table创建/检查完成")

        # 3. 查询表数据
        print("\n" + "="*60)
        print("test_table 表数据内容：")
        print("="*60)
        data_sql = "select * from test_table ;"
        with conn.cursor() as cur:
            cur.execute(data_sql)
            print(f"{'insert_seq':<10} {'insert_time'}")
            print("-"*60)
            rows = cur.fetchall()
            print(rows)
    except Exception as e:
        print(f"执行出错：{str(e)[:100]}")
    finally:
        # 关闭连接
        if conn:
            conn.close()
            print("\n数据库连接已关闭")

if __name__ == "__main__":
    print("启动GBase数据库表创建与查询脚本")
    main()
    print("脚本执行完成")

执行脚本及输出示例

[gbase@gbase8c psycopg2]$ python3 demo_01.py
启动GBase数据库表创建与查询脚本
成功连接到GBase数据库：172.31.100.230:15400/postgres
表test_table创建/检查完成

============================================================
test_table 表数据内容：
============================================================
insert_seq insert_time
------------------------------------------------------------
[]

数据库连接已关闭
脚本执行完成
[gbase@gbase8c psycopg2]$

常见问题排查

gsql登录提示“connection refused”：检查数据库服务是否正常运行（gs_om -t status），客户端IP是否已添加至服务端白名单。
DBeaver连接提示“驱动类未找到”：重新配置驱动，确保jar包路径正确，驱动类选择com.gbase8c.Driver。
Python脚本提示“psycopg2导入失败”：检查环境变量配置是否生效，驱动包解压路径是否与配置一致。