openGauss 实战指南：gsql 命令、认证配置与运维工具详解

openGauss 实战指南：gsql 命令、认证配置与运维工具详解

openGauss 是一款高性能开源数据库，掌握其命令行工具是学习与运维的基础。我们从 gsql 常用命令入手，逐步深入到集群管理与备份恢复，带你快速上手实际操作。

一、gsql 常用命令与操作

1. gsql 简介

gsql 是 openGauss 自带的命令行交互式客户端工具。它允许用户连接到数据库，以交互方式执行 SQL 语句，查看查询结果，并执行各类数据库管理任务。

2. gsql 连接数据库命令格式

语法结构

gsql [OPTION]... [DBNAME [USERNAME]]

常用参数

-d, --dbname=DBNAME: 指定要连接的数据库名称。 -p, --port=PORT: 指定数据库服务监听的 TCP 端口。 -U, --username=USERNAME: 指定连接数据库的用户名。 -W, --password: 强制 gsql 在连接前提示输入密码。 -h, --host=HOSTNAME: 指定数据库服务器的主机名或 IP 地址。 -f, --file=FILENAME: 从文件而不是标准输入中读取并执行命令。

示例 这里我们连接到一个具体的实例，记得 -W 会触发密码输入提示：

# 连接到 IP 为 192.168.1.10 的服务器上，端口为 15400 的 postgres 数据库，使用 omm 用户，并提示输入密码
gsql -d postgres -p 15400 -U omm -W -h 192.168.1.10 

3. gsql 内部命令 (元命令) 详解

这些命令在 gsql 提示符下直接使用，以反斜杠 \ 开头，不以分号结尾。它们比标准 SQL 更灵活，适合快速检查状态。

\q: 退出 gsql 作用：立即终止 gsql 会话并退出客户端。

postgres=# \q

\l: 查看数据库列表 作用：列出当前 openGauss 实例中的所有数据库及其所有者、编码等信息。 ![图：数据库列表输出]

\c: 连接数据库 语法：\c[onnect] [DBNAME|- USER|- HOST|- PORT|-] 作用：在不退出 gsql 的情况下，切换到另一个数据库连接。

-- 从当前数据库切换到名为 'testdb' 的数据库
postgres=# \c testdb
You are now connected to database "testdb" as user "omm".
testdb=#

![图：切换数据库输出]

\d, \dt, \di, \dv: 查看对象信息 作用：

• \d [NAME]: 显示表、视图、索引或序列的详细结构。
• \dt [PATTERN]: 仅列出匹配模式的表 (Tables)。
• \di [PATTERN]: 仅列出匹配模式的索引 (Indexes)。
• \dv [PATTERN]: 仅列出匹配模式的视图 (Views)。

示例：

-- 查看所有表
testdb=# \dt
-- 查看名为 'employees' 的表的详细定义
testdb=# \d employees

![图：查看表结构] ![图：查看索引] ![图：查看视图]

\du: 查看用户 作用：列出数据库中所有的用户和角色及其属性（如超级用户、创建数据库等权限）。

testdb=# \du

![图：查看用户列表]

\dn: 查看 schema 作用：列出当前数据库中所有的模式 (Schema) 及其所有者。

testdb=# \dn

![图：查看 Schema]

\df: 查看函数 作用：列出可用的函数、它们的参数类型和返回类型。

testdb=# \df

![图：查看函数]

\h, ?: 帮助命令 作用：

• \h [COMMAND]: 提供指定 SQL 命令（如 SELECT, UPDATE）的语法帮助。
• \?: 显示所有 gsql 元命令的列表和简介。

-- 获取 CREATE TABLE 命令的帮助
testdb=# \h CREATE TABLE
-- 查看所有元命令
testdb=# \?

![图：SQL 帮助] ![图：元命令列表]

\password: 修改密码 作用：为当前登录的用户设置新的密码。

testdb=# \password
Enter new password:
Enter it again:

\conninfo: 显示连接信息 作用：显示当前连接的详细信息，包括数据库名、用户名、服务器地址和端口。

testdb=# \conninfo
You are connected to database "testdb" as user "omm" on host "192.168.1.10" at port "15400".

![图：连接信息]

\timing: 开启/关闭执行计时 作用：切换一个开关，用于显示每条 SQL 语句执行所花费的时间。这对性能调优很有用。

testdb=# \timing
Timing is on.
testdb=# SELECT count(*) FROM employees;
-- ...Time: 1.234 ms

![图：计时功能]

二、openGauss 体系结构概览

1. 系统总体结构

openGauss 采用 Shared-Nothing 架构，每个节点都拥有自己独立的 CPU、内存和存储，节点之间通过网络进行通信，具备良好的扩展性。 ![图：系统架构图]

2. 进程线程结构

gaussdb: 数据库的主进程，负责启动和管理所有后端工作线程。 gs_clean: 用于清理不再需要的临时文件和进程。 gs_roach: 负责数据库的高可用管理、故障检测和主备切换。

后台工作线程: 如 PageWriter (页写入)、Checkpointer (检查点)、WalWriter (日志写入) 等。

3. 内存结构

openGauss 的内存主要分为两大区域：

3.1. 共享内存区 (Shared Memory): 被所有进程共享，用于缓存和协调。

Shared Buffer: 缓存从磁盘读出的数据页，是最核心的内存区域。 CLog Buffer: 缓存事务的提交状态。 Wal Buffer: 缓存预写日志 (WAL) 记录。

3.2. 本地区域 (Local Memory): 每个后端进程独享。

• work_mem: 用于排序、哈希连接等操作。
• maintenance_work_mem: 用于 VACUUM, CREATE INDEX 等维护操作。

![图：内存结构图]

4. 存储结构

逻辑结构: Tablespace -> Database -> Schema -> Table/Index 物理结构:

数据文件: 存储表和索引的实际数据。 WAL 日志文件: 记录所有数据的变更，用于数据恢复和主备同步。 控制文件 (pg_control): 记录数据库集群的元数据和状态信息。

![图：存储结构图]

5. 关键配置文件

postgresql.conf: 数据库的主配置文件，控制内存、连接数、日志等核心参数。 pg_hba.conf: 客户端主机认证配置文件 (Host-Based Authentication)，控制哪些主机可以用什么方式连接。

三、客户端认证策略 (pg_hba.conf)

1. 客户端认证机制简介

pg_hba.conf 是 openGauss 的门卫。当一个客户端尝试连接时，数据库会从上到下依次读取此文件中的规则。第一条匹配连接请求的规则将被采用。

2. gs_guc 命令修改策略格式与参数说明

规则的基本格式如下： HOSTTYPE DATABASE USER ADDRESS METHOD

HOSTTYPE: 连接类型。

local: 本地 Unix 域套接字连接。 host: 普通的 TCP/IP 连接（不区分 SSL）。 hostssl: 强制使用 SSL 的 TCP/IP 连接。 hostnossl: 强制不使用 SSL 的 TCP/IP 连接。

DATABASE: 目标数据库，all 表示所有。 USER: 连接用户，all 表示所有。 ADDRESS: 客户端 IP 地址范围，使用 CIDR 表示法 (如 192.168.1.0/24)。 METHOD: 认证方法。

trust: 无条件信任，不需密码（极不安全）。 md5 / sha256: 密码认证，推荐使用 sha256。 cert: 客户端 SSL 证书认证。 gss: GSSAPI 认证。

3. 示例：添加允许远程访问的规则

要允许 IP 为 192.168.1.100 的主机使用 jack 用户通过密码访问所有数据库，可以添加如下规则：

host all jack 192.168.1.100/32 sha256 

4. 认证规则顺序与安全建议

顺序至上: 更严格、更具体的规则应该放在前面。 最小权限原则: 避免使用 all，精确指定数据库和用户。 禁用 trust: 除非在绝对安全的内部网络，否则不要使用 trust。

四、客户端连接数据库

1. 查看数据库实例信息：gs_om -t status --detail

作用: gs_om 是集群管理工具。使用 status --detail 子命令可以获取集群中每个数据库实例的详细运行状态，其中最关键的信息是实例的 IP 地址 (DataNodeIP) 和端口号 (Port)。 语法: gs_om -t status --detail 示例 (以 omm 用户执行)

[omm@host ~]$ gs_om -t status --detail
[Cluster Status]
cluster_state : Normal
redistributing : No
current_az : AZ_ALL
[Datanode Status]...
1192.168.1.10 15400 P Normal ...

从上面的输出可以得知，主实例的 IP 是 192.168.1.10，端口是 15400。

2. 连接数据库命令 (gsql -d -p -U -W 格式)

作用: 基于上一步获取的信息，使用 gsql 客户端发起实际的数据库连接。 语法: gsql -d <database> -p <port> -U <user> -W [-h <host>] 示例

# 使用从 gs_om 获取到的信息连接数据库
gsql -d postgres -p 15400 -U omm -W -h 192.168.1.10 

常见连接错误与排查

Connection refused: 通常是网络问题 (防火墙) 或数据库服务未启动。 FATAL: no pg_hba.conf entry for host ...: 服务器的 pg_hba.conf 文件中没有匹配该客户端 IP、用户、数据库的规则。 FATAL: password authentication failed for user ...: 密码错误。

五、使用 gs_guc 配置远程连接白名单

操作流程

直接编辑 pg_hba.conf 文件后需要手动重载配置。推荐的方式是使用 gs_guc 工具，它会自动修改文件并使配置生效。

示例命令

为 jack 用户添加一个远程访问白名单规则：

# -N all 表示所有节点，-I all 表示所有实例
# -h 参数后跟完整的 pg_hba.conf 规则字符串
gs_guc set -N all -I all -h "host all jack 192.168.1.100/32 sha256"

![图：gs_guc 执行结果] 执行后，gs_guc 会自动将这行规则追加到 pg_hba.conf 文件末尾，并触发配置重载。

建议与注意事项

精确匹配: 尽量使用 /32 指定单个 IP，避免开放过大的网段。 备份: 在进行重要修改前，备份 pg_hba.conf 文件。 检查: 修改后，尝试从白名单中的主机进行连接测试。

六、openGauss 常用工具详解

1. gsql

   • 作用: 数据库的命令行交互接口，用于执行 SQL 和管理任务。
   • 语法: gsql [OPTIONS...]
   • 示例: gsql -d testdb -p 15400 -U omm ![图：gsql 界面]

2. gs_check

   • 作用: 对数据库集群的环境、配置和状态进行全面的健康检查。
   • 语法: gs_check [OPTIONS...]
   • 示例: gs_checkos -i A ![图：gs_check 输出]

3. gs_checkos

   • 作用: 专项用于检测操作系统的各项配置是否满足 openGauss 的最佳实践要求。
   • 语法: gs_checkos [OPTIONS...]
   • 示例: gs_checkos -i A -o /tmp/os_check_report.txt (检查所有项并输出到文件) ![图：gs_checkos 报告]

4. gs_checkperf

   • 作用: 执行数据库性能基准测试，评估系统在不同负载下的表现。
   • 语法: gs_checkperf -U <omm 用户名>
   • 示例: gs_checkperf -U omm -i A ![图：性能测试结果]

5. gs_collector

   • 作用: 一键收集用于故障诊断的各类信息，包括日志、配置、系统信息等。
   • 语法: gs_collector [OPTIONS...]
   • 示例: gs_collector -o /tmp/collect_info --begin-time="20251112 10:00" --end-time="20251112 11:00" (收集指定时间点后的信息) ![图：信息收集]

6. gs_dump

   • 作用: 将单个数据库的内容以逻辑方式导出为 SQL 脚本文件。
   • 语法: gs_dump [DBNAME] [OPTIONS...]
   • 示例: gs_dump testdb -f /backup/testdb.sql -p 15400 -U omm ![图：gs_dump 执行]

7. gs_dumpall

   • 作用: 逻辑导出整个数据库集群，包括所有数据库和全局对象（如用户、角色）。
   • 语法: gs_dumpall [OPTIONS...]
   • 示例: gs_dumpall -f /backup/all_dbs.sql -p 15400 -U omm ![图：全库导出]

8. gs_restore

   • 作用: 从 gs_dump 或 gs_dumpall 创建的备份文件中恢复数据库。
   • 语法: gs_restore [DBNAME] [OPTIONS...] FILENAME
   • 示例: gs_restore -d new_db -p 15400 /backup/testdb.sql ![图：数据恢复]

9. gs_guc

   • 作用: 以命令行方式安全地查看和修改数据库配置参数 (postgresql.conf) 和认证策略 (pg_hba.conf)。
   • 语法: gs_guc [set|reload|check] [OPTIONS...]
   • 示例: gs_guc set -N all -I all -c "max_connections=500" ![图：配置修改]

10. gs_om

    • 作用: openGauss 的核心运维管理工具，负责集群生命周期管理。
    • 语法: gs_om -t [COMMAND] [OPTIONS...]
    • 示例:
      • gs_om -t start (启动集群)
      • gs_om -t stop (停止集群)
      • gs_om -t status --detail (查看详细状态) ![图：集群状态] ![图：集群操作] ![图：主备状态]

11. gs_ssh

    • 作用: 在集群中的所有节点或指定节点上批量执行操作系统命令。
    • 语法: gs_ssh [-h HOST] -c "COMMAND"
    • 示例: gs_ssh -c "df -h" ![图：批量命令]

openGauss 常用工具总结

工具名称	核心功能分类	主要用途
gsql	数据库交互	连接数据库，执行 SQL 语句和元命令。
gs_om	集群运维	数据库集群的启动、停止、状态查询、主备切换等。
gs_guc	参数配置	安全地修改 postgresql.conf 和 pg_hba.conf 文件。
gs_dump	逻辑备份	导出单个数据库为 SQL 脚本。
gs_dumpall	逻辑备份	导出整个集群的所有数据库及全局对象。
gs_restore	逻辑恢复	从 gs_dump 或 gs_dumpall 的备份文件恢复数据。
gs_check	健康检查	对集群环境、配置、状态进行全面的健康巡检。
gs_checkos	健康检查	专项检查操作系统层面的配置是否合规。
gs_checkperf	性能测试	对数据库进行基准性能测试。
gs_collector	故障诊断	一键收集用于故障分析的日志、配置和系统信息。
gs_ssh	批量操作	在集群各节点上批量执行 Shell 命令。

---

练习题

为了巩固知识点，这里整理了一些常见问题，建议在实际环境中验证一下。

1. 在 gsql 中，哪个命令用于列出当前实例的所有数据库？
A. \d
B. \dt
C. \l
D. \c

2. openGauss 的内存结构中，用于排序和哈希连接的内存属于哪个区域？
A. Shared Buffer
B. Wal Buffer
C. work_mem
D. maintenance_work_mem

3. 哪个配置文件负责控制客户端的连接认证策略？
A. postgresql.conf
B. pg_control
C. pg_hba.conf
D. gaussdb.conf

4. 在 pg_hba.conf 文件中，哪种认证方式表示无条件信任连接，存在极大的安全风险？
A. md5
B. sha256
C. cert
D. trust

5. 当你尝试远程连接数据库，收到 FATAL: no pg_hba.conf entry for host... 错误时，最可能的原因是什么？
A. 密码输入错误。
B. 数据库服务未启动。
C. 防火墙拦截了端口。
D. pg_hba.conf 文件中缺少匹配该客户端 IP 的规则。

6. 推荐使用哪个命令来修改 postgresql.conf 中的参数并使其生效？
A. gs_om
B. gs_guc
C. gs_ssh
D. gsql

7. gs_dump 和 gs_dumpall 的主要区别是什么？
A. gs_dump 速度更快。
B. gs_dumpall 可以备份单个表。
C. gs_dump 备份单个数据库，gs_dumpall 备份整个集群的所有数据库和全局对象。
D. gs_dump 是物理备份，gs_dumpall 是逻辑备份。

8. 哪个工具专门用于检测操作系统层面的配置项，如透明大页 (THP)？
A. gs_check
B. gs_checkperf
C. gs_collector
D. gs_checkos

9. gs_om -t status --detail 命令的主要作用是什么？
A. 启动数据库集群。
B. 检查操作系统状态。
C. 显示数据库集群中每个实例的详细状态，包括 IP 和端口。
D. 收集数据库日志。

10. 在 gsql 中，执行 \timing 命令会产生什么效果？
A. 显示当前时间。
B. 开启或关闭每条 SQL 语句的执行耗时显示。
C. 设置查询超时时间。
D. 显示数据库服务器的系统时间。

11. 以下 pg_hba.conf 规则的正确格式是？
A. USER DATABASE ADDRESS HOSTTYPE METHOD
B. HOSTTYPE DATABASE USER ADDRESS METHOD
C. METHOD ADDRESS USER DATABASE HOSTTYPE
D. ADDRESS METHOD HOSTTYPE USER DATABASE

12. 当数据库出现故障，需要提供给技术支持人员全面的诊断信息时，应优先使用哪个工具？
A. gs_dump
B. gs_restore
C. gs_collector
D. gs_check

13. gs_om 是 openGauss 的核心运维工具，它不能执行以下哪个操作？
A. 启动数据库集群
B. 停止数据库集群
C. 查询数据库中某个表的行数
D. 查看主备实例状态

14. (填空) pg_hba.conf 文件中的规则是 ______ 匹配的，一旦找到第一条符合条件的规则，后续规则将被忽略。

15. (简答) 请写出一条 gs_guc 命令，作用是为 IP 地址为 10.0.0.5 的主机，开放 omm 用户通过 sha256 密码认证访问 testdb 数据库的权限。

---

答案与解析

1. C. \l

   解析: \l (list) 是 gsql 中用于列出所有数据库的元命令。\dt 列出表，\d 显示对象详情，\c 用于连接数据库。

2. C. work_mem

   解析: work_mem 是每个后端进程独享的本地内存，专门用于处理排序、哈希等计算密集型操作。Shared Buffer 是共享的数据页缓存。

3. C. pg_hba.conf

   解析: pg_hba.conf (Host-Based Authentication) 文件定义了哪些主机可以通过何种方式、以哪个用户的身份访问哪个数据库。

4. D. trust

   解析: trust 方法意味着只要连接参数（用户、数据库、客户端地址）匹配，就直接允许连接，无需密码，因此非常不安全。

5. D. pg_hba.conf 文件中缺少匹配该客户端 IP 的规则。

   解析: 这个错误信息明确指出，服务器在 pg_hba.conf 中找不到任何一条规则来允许来自该客户端 IP 的连接请求。

6. B. gs_guc

   解析: gs_guc (Grand Unified Configuration) 是官方推荐的参数配置工具，它可以安全地修改配置文件并自动重载，避免了手动编辑的风险。

7. C. gs_dump 备份单个数据库，gs_dumpall 备份整个集群的所有数据库和全局对象。

   解析: gs_dump 针对单个数据库，而 gs_dumpall 范围更广，会备份所有数据库以及用户、角色、表空间等全局信息。

8. D. gs_checkos

   解析: gs_checkos 的职责非常专一，就是深入检查操作系统的各项配置是否符合 openGauss 的运行要求。

9. C. 显示数据库集群中每个实例的详细状态，包括 IP 和端口。

   解析: --detail 选项提供了比普通 status 更丰富的信息，是获取节点 IP 和端口等关键连接信息的标准方法。

10. B. 开启或关闭每条 SQL 语句的执行耗时显示。

    解析: \timing 是一个开关命令，执行一次开启计时，再执行一次关闭，非常适合用于简单的性能分析。

11. B. HOSTTYPE DATABASE USER ADDRESS METHOD

    解析: 这是 pg_hba.conf 中一条规则的标准列顺序，理解这个顺序是正确配置访问策略的基础。

12. C. gs_collector

    解析: gs_collector 设计的目的就是为了'一键打包'所有与故障诊断相关的信息，极大地方便了问题的定位和沟通。

13. C. 查询数据库中某个表的行数

    解析: gs_om 是集群层面的管理工具，负责启停、状态等运维操作。查询表数据这类数据库内部的操作需要使用 gsql 来执行 SQL 语句。

14. 从上到下 (或 顺序)

    解析: pg_hba.conf 的匹配机制是'first match wins'，所以规则的顺序非常重要，通常将更精确、更严格的规则放在文件的前面。

15. gs_guc set -N all -I all -h "host testdb omm 10.0.0.5/32 sha256"

    解析: 该命令遵循了 gs_guc 的语法，-h 参数后紧跟一条完整的 pg_hba.conf 规则，其中 HOSTTYPE 是 host，DATABASE 是 testdb，USER 是 omm，ADDRESS 是 10.0.0.5/32，METHOD 是 sha256。