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: 从文件而不是标准输入中读取并执行命令。

示例

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

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

这些命令在 gsql 提示符下直接使用，以反斜杠 \ 开头，不以分号结尾。

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

postgres=# \q

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

postgres=# \l

\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

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

testdb=# \df

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

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

\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、内存和存储，节点之间通过网络进行通信，具备良好的扩展性。

[在这里可以插入一张 openGauss 的总体架构图，展示 Master/Standby/Node 的关系]

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]
...1       192.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 会自动将这行规则追加到 pg_hba.conf 文件末尾，并触发配置重载。

建议与注意事项

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

六、openGauss 常用工具详解

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

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

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

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

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。