openGauss 实战手册：gsql 常用命令、认证配置与运维工具全解

Ne0inhk

— 18 min read
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 todatabase"testdb"asuser"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 todatabase"testdb"asuser"omm"on host "192.168.1.10" at port "15400".
在这里插入图片描述

\timing: 开启/关闭执行计时
作用:切换一个开关，用于显示每条SQL 语句执行所花费的时间。
示例:

testdb=# \timing Timing ison. 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会自动将这行规则追加到 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 的连接请求。
  1. 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。

日期：2025年11月12日
专栏：openGauss

Read more

从0到1打造RISC-V智能家居中控：硬件+固件+通信全链路实战

从0到1打造RISC-V智能家居中控：硬件+固件+通信全链路实战

👋 大家好，欢迎来到我的技术博客！ 📚 在这里，我会分享学习笔记、实战经验与技术思考，力求用简单的方式讲清楚复杂的问题。 🌱 无论你是刚入门的新手，还是正在进阶的开发者，希望你都能有所收获！ 文章目录 * 从0到1打造RISC-V智能家居中控：硬件+固件+通信全链路实战 🏠💡 * 为什么选择RISC-V？🤔 * 系统整体架构概览 🧩 * 第一步：硬件选型与电路搭建 🔌 * 主控芯片选择 * 外设连接 * 第二步：开发环境搭建 🛠️ * 安装步骤（以Ubuntu为例） * 第三步：裸机驱动开发（Bare Metal）⚡ * 示例1：DHT11温湿度读取（Bit-banging） * 示例2：BH1750光照传感器（I2C） * 第四步：引入FreeRTOS实现多任务调度 🔄 * 第五步：Wi-Fi连接与MQTT通信 ☁️📡 * 连接Wi-Fi * MQTT客户端（使用esp-mqtt库） * 第六步：BLE本地控制（无需Wi-Fi）📱

By Ne0inhk
机器人远程监控与OTA升级

机器人远程监控与OTA升级

7.4.1 远程监控的理论框架 远程监控是物联网和工业4.0时代的核心技术，其理论任务是通过网络通信手段，实现对分布式机器人设备的实时状态感知、故障预警和远程干预 。对于机器人系统而言，远程监控不仅是数据可视化的问题，更是一个涉及数据采集、传输、处理、分析和决策的闭环系统工程。 远程监控系统的三层理论架构： 感知层解决“数据从哪里来”的问题。包括机器人本体上的各类传感器（温度、振动、电流、位置）、控制器状态（CPU负载、内存使用、存储寿命）以及运行日志的采集 。感知层的理论基础是传感器技术和信号处理，其核心挑战是在不影响机器人实时控制的前提下，高效、可靠地获取状态数据。 传输层解决“数据怎么传”的问题。根据应用场景的不同，可采用Wi-Fi（室内短距）、4G/5G（广域移动）、工业以太网（固定工位）等不同通信方式 。传输层的理论基础是网络通信协议栈，其核心挑战是保证数据在复杂工业环境下的实时性、可靠性和安全性。 应用层解决“数据怎么用”

By Ne0inhk

neo4j desktop2 安装与使用

1. Neo4j Desktop 2 简介 1.1 Neo4j Desktop 2 的核心功能与优势 Neo4j Desktop 2 是 Neo4j 官方推出的图形化数据库管理工具，专为开发者和数据科学家设计。 其主要优势包括： 一体化开发环境：集成了数据库实例管理、查询编辑、数据可视化和扩展管理 本地开发友好：支持在本地机器上快速创建和测试图数据库实例 多版本管理：可同时管理多个 Neo4j 数据库版本 插件生态系统：内置插件市场，轻松安装常用扩展  项目管理：以项目为单位组织数据库、查询和配置   1.2 适用场景 图数据库开发：为应用程序开发提供本地图数据库环境 本地测试：在部署到生产环境前进行数据模型测试和查询验证 项目管理：管理多个图数据库项目，保持环境隔离 教育与学习：学习 Cypher 查询语言和图数据库概念 2.

By Ne0inhk
手把手教你配置飞书 OpenClaw 机器人，打造企业级 AI 智能助手

手把手教你配置飞书 OpenClaw 机器人，打造企业级 AI 智能助手

目标：在飞书（Feishu/Lark）中添加 OpenClaw 机器人，实现 7×24 小时 AI 智能对话与自动化办公。 OpenClaw GitHub | feishu-openclaw 桥接项目 想让你的机器人具备语音交互能力？试试 Seeed Studio 的 ReSpeaker 系列吧！ 我会后续出reSpeaker XVF3800与Openclaw联动实现语音输入的教程，完全开放源码。 reSpeaker XVF3800 是一款基于 XMOS XVF3800 芯片的专业级 4 麦克风圆形阵列麦克风，即使在嘈杂的环境中也能清晰地拾取目标语音。它具备双模式、360° 远场语音拾取（最远 5 米）、自动回声消除 (AEC)、自动增益控制 (AGC)、声源定位 (DoA)、去混响、波束成形和噪声抑制等功能。

By Ne0inhk