# GaussDB 集群参数管理(GUC)

## 1. 参数分类与设置级别

&emsp;&emsp;`GaussDB` 的物理参数均保存在 `gaussdb.conf` 和 `pg_hba.conf` 配置文件中。根据内核控制范围，参数分为以下六种级别：

| 参数类型 | 作用域与控制级别 | 标准修改方式 | 生效时机 |
| :--- | :--- | :--- | :--- |
| **INTERNAL** | 静态固定参数，建库时确定。 | 无法修改，仅供 `SHOW` 查看。 | 永久固定 |
| **POSTMASTER** | 服务端核心参数（如内存、连接数）。 | gs_guc set  | **必须重启集群** |
| **SIGHUP** | 数据库全局参数。 | gs_guc reload  | **即时生效 (免重启)** |
| **BACKEND** | 内部会话连接参数，不推荐用户设置。 | gs_guc reload  | 下次新建立会话时生效 |
| **SUSET** | 数据库管理员（SYSADMIN）参数。 | gs_guc reload 或 管理员 SQL SET | 依修改方式确定 |
| **USERSET** | 普通用户参数。 | gs_guc reload 或 任意用户 SQL SET | 立即生效 |

### 1.1 INTERNAL（固定参数）

- 定义：这是数据库内嵌的、静态的固定参数。通常在编译源码或执行 `gs_initdb` 初始化数据库时就已经彻底定死。
- 修改权限：创建数据库后无法修改。
- 查看方式：只能通过 `SHOW` 语法或 `pg_settings` 视图进行人肉查看，常用于检查版本和核心块大小。
- 典型示例：
  - `blocksize`：数据库标准的逻辑数据块大小（默认是 8192 字节）
  - `server_version`：当前高斯数据库的内核核心大版本号。

```sql
gaussdb=> SELECT current_setting('block_size')::int;
 current_setting 
-----------------
            8192
(1 row)

gaussdb=> SELECT current_setting('server_version');
 current_setting 
-----------------
 9.2.4
(1 row)

gaussdb=> show server_version;
 server_version 
----------------
 9.2.4
(1 row)
```

### 1.2 POSTMASTER（服务端核心参数）

- 定义：这是数据库的基本参数。通常涉及到操作系统的进程初始化、共享内存大页的预分配或网络端口的绑定。
- 修改权限：可以使用 `gs_guc` set 命令修改配置文件。
- 生效时机：必须重启整个数据库集群（`gs_om -t restart`）才会生效。在线执行 `reload` 会直接被内核拒绝。
- 典型示例：
  - `max_process_memory`：单节点物理能够使用的最大总内存。
  - `shared_buffers`：数据库用来缓存数据页面的共享内存缓冲区大小
  - `max_connections`：允许客户端最大并发连入的连接数。
  - `port`：数据库监听的 TCP 业务端口。

### 1.3 SIGHUP（全局即时参数）

- 定义：这是最受 DBA 欢迎的数据库全局配置参数。
- 修改权限：超级管理员有权更改。
- 生效时机：即时生效，免重启。 修改时只需使用 `gs_guc reload` 命令，内核会向主进程发送 SIGHUP 信号量，秒级通知全网所有节点重新加载参数。
- 典型示例：
  - `synchronous_commit`：主备流复制的事务提交安全级别（如 on、local）。
  - `synchronous_standby_names`：强同步备机的选择策略（如 ANY 1(dn_6002)）。
  - `log_destination`：数据库日志的输出目的地（如 stderr、csvlog）。

### 1.4 BACKEND（会话连接参数）

- 定义：初始化会话环境的参数。
- 修改权限：属于内部机制或管理员参数。
- 生效时机：对已经连进来的活动会话无效，只对“下一次”新建立的连接生效。 修改时使用 `gs_guc reload`，当旧连接断开、新连接进来时，新连接会读取到新值。
- 典型示例：
  - `log_connections`：每次有新连接成功连入数据库时，是否在服务器日志里打印一条登录痕迹（通常在线开启用来抓取恶意扫描）。
  - `log_disconnections`：当客户端断开连接时，是否在日志中记录其在线时长。

### 1.5 SUSET（超级用户/管理员参数）

- 定义：这是只有数据库超级管理员（Superuser）才有资格把控的调优参数。
- 修改权限：普通业务账号无权触碰。
- 生效时机：极度灵活。DBA 可以通过 gs_guc reload 让其全局在线生效；也可以登录 gsql 后执行 SET parameter = value; 仅让其在当前会话窗口内临时生效（退出窗口自动失效）。
- 典型示例：
  - `maintenance_work_mem`：执行 CREATE INDEX、VACUUM（清理碎片）等大型维护操作时，单条 SQL 可以使用的最大内存。
  - `work_mem`：单条查询在进行高级 ORDER BY 或 Hash Join 时，允许在内存中消耗的容量。
  - `enable_nestloop`：优化器强制关闭或开启“嵌套循环连接”路径。
  - log_min_messages：控制写进服务器日志的最低日志级别。调得太低会疯狂刷屏导致磁盘 I/O 爆满。
  - `enable_nestloop`/`enable_hashjoin`：执行计划执行路径的选择开关。

### 1.6 USERSET（普通用户参数）

- 定义：这是权限最松、限制最少的普通参数。
- 修改权限：任何普通用户都能自由修改，只影响自己。
- 生效时机：在当前 SQL 执行窗口输入 SET 参数 = 值; 立即生效，常用于临时改变显示格式。
- 典型示例：
  - `DateStyle`：控制当前窗口查出来的日期时间显示格式。
  - `search_path`：控制默认的模式检索优先顺序。
  - `explain_perf_mode`：控制执行 `EXPLAIN` 查看执行计划时的输出样式。

在实际运维中，我们不需要去记录每个参数的类型，查询字典视图 `pg_settings`的 `context` 字段即可。

```sql
-- 示例：查询 max_process_memory 的参数分类
SELECT name, setting, context, short_desc 
FROM pg_settings 
WHERE name = 'max_process_memory';
        name        | setting  |  context   |                       short_desc                       
--------------------+----------+------------+--------------------------------------------------------
 max_process_memory | 10485760 | postmaster | Sets the maximum number of memory used by the process.
(1 row)
```

## 二、 gs_guc 命令

```bash
gs_guc {set | reload | check} -Z NODE-TYPE [-N NODE-NAME] [-I INSTANCE-NAME | -D DATADIR] -c "parameter='value'"
```

参数说明：

1. **`-Z` 节点类型**：最常用的是 `coordinator` (CN) 和 `datanode` (DN)。
2. **多节点限制**：单条命令**暂不支持指定多个 `-Z`、多个 `-N` 或多个 `-I`**。如需同时修改 CN 和 DN，必须拆分为两条命令分别下发！
3. **集群级（全局）**：如果指定 -N all，则会对集群中所有节点或同类型的所有组件统一修改，相当于全局生效。
4. **单节点级**：如果指定具体的节点名称或 IP（例如 -N 192.168.182.138），则只修改该台主机上的配置。
5. **动作区别**：
   * `set`：仅修改配置文件，通常用于需要重启的 `POSTMASTER` 参数。
   * `reload`：修改配置文件并向内核发送信号量，用于 `SIGHUP` 参数的在线即时重载。

## 3. `gs_guc` 全局修改

### 3.1 `gs_guc check` 检查参数

&emsp;&emsp;在变更参数前，查看当前参数值：

```bash
# 检查所有 DN 节点的共享内存与 ustore 引擎状态
[omm@gauss1 ~]$ gs_guc check -Z datanode -N all -I all -c "shared_buffers"
The gs_guc run with the following arguments: [gs_guc -Z datanode -N all -I all -c shared_buffers check ].

Total GUC values: 3. Failed GUC values: 0.
The value of parameter shared_buffers is same on all instances.
    shared_buffers='5GB'

[omm@gauss1 ~]$ gs_guc check -Z datanode -N all -I all -c "enable_default_ustore_table"
The gs_guc run with the following arguments: [gs_guc -Z datanode -N all -I all -c enable_default_ustore_table check ].

Total GUC values: 3. Failed GUC values: 0.
The details for enable_default_ustore_table:
[192.168.182.138]  enable_default_ustore_table=NULL  [/data/cluster/data/dn/dn_6001/gaussdb.conf]
[192.168.182.139]  enable_default_ustore_table=NULL  [/data/cluster/data/dn/dn_6002/gaussdb.conf]
[192.168.182.140]  enable_default_ustore_table=NULL  [/data/cluster/data/dn/dn_6003/gaussdb.conf]
```

### 3.2 重启生效类

&emsp;&emsp;针对最大内存、共享缓冲区等 `POSTMASTER` 参数，必须执行 `set` 并物理重启集群：

```bash
-- 1. 修改 max_connections 为 200
[omm@gauss1 ~]$ gs_guc set -Z datanode -N all -I all -c "max_connections=200"
The gs_guc run with the following arguments: [gs_guc -Z datanode -N all -I all -c max_connections=200 set ].
Begin to perform the total nodes: 3.
Popen count is 3, Popen success count is 3, Popen failure count is 0.
Begin to perform gs_guc for datanodes.
Command count is 3, Command success count is 3, Command failure count is 0.

Total instances: 3. Failed instances: 0.
ALL: Success to perform gs_guc!

-- 2. 禁用 UStore
[omm@gauss1 ~]$ gs_guc set -Z datanode -N all -I all -c "enable_default_ustore_table=off"
The gs_guc run with the following arguments: [gs_guc -Z datanode -N all -I all -c enable_default_ustore_table=off set ].
NOTICE: Enable to create ustore table by default
Begin to perform the total nodes: 3.
Popen count is 3, Popen success count is 3, Popen failure count is 0.
Begin to perform gs_guc for datanodes.
Command count is 3, Command success count is 3, Command failure count is 0.

Total instances: 3. Failed instances: 0.
ALL: Success to perform gs_guc!

# 3. 重启整个集群使上述配置生效
gs_om -t stop && gs_om -t start

-- 4. 发现 max_connections 修改已生效
[omm@gauss1 ~]$ gs_guc check -Z datanode -N all -I all -c "max_connections"
The gs_guc run with the following arguments: [gs_guc -Z datanode -N all -I all -c max_connections check ].

Total GUC values: 3. Failed GUC values: 0.
The value of parameter max_connections is same on all instances.
    max_connections=200

-- 5. UStore 已关闭
[omm@gauss1 ~]$ gs_guc check -Z datanode -N all -I all -c "enable_default_ustore_table"
The gs_guc run with the following arguments: [gs_guc -Z datanode -N all -I all -c enable_default_ustore_table check ].

Total GUC values: 3. Failed GUC values: 0.
The value of parameter enable_default_ustore_table is same on all instances.
    enable_default_ustore_table=off
```

### 3.3 即时生效类

&emsp;&emsp;针对 SIGHUP 和 HBA 类参数， 使用 `reload` 即时生效：

```bash
# 在线重载 HBA 规则: 所有IP 信任登录
[omm@gauss1 ~]$ gs_guc reload -Z datanode -N all -I all -h "host all all 0.0.0.0/0 trust"
The gs_guc run with the following arguments: [gs_guc -Z datanode -N all -I all -h host all all 0.0.0.0/0 trust reload ].
Begin to perform the total nodes: 3.
Popen count is 3, Popen success count is 3, Popen failure count is 0.
Begin to perform gs_guc for datanodes.
Command count is 3, Command success count is 3, Command failure count is 0.

Total instances: 3. Failed instances: 0.
ALL: Success to perform gs_guc!
```

## 4、 SQL 命令变更机制

&emsp;&emsp;`gs_guc` 修改的整个节点或全局的参数，还可以使用 SQL 脚本修改参数，根据sql脚本的不同，生效的范围也不相同。

### 4.1 数据库/用户级

使参数在某个数据库生效可以使用 `alter database`

```sql
-- 针对特定数据库变更兼容性行为
ALTER DATABASE postgres SET b_format_behavior_compat_options = 'enable_set_variables';

-- 针对特定运维用户修正时区
ALTER USER Ruby SET timezone TO 'UTC';
```

### 4.2 会话级（临时生效，退出登录即失效）

```sql
-- 临时调整当前窗口的时区
SET timezone TO 'UTC';

-- 临时指定当前事务的分布式计划节点路由数
SET max_datanode_for_plan = 1;
```

&emsp;&emsp;至此，GaussDB 参数配置讲到这里，下一期我们讲一下 `GaussDB` 的常用 SQL 语句。

&emsp;&emsp;**这里是《实战派 K8S&DB》，更多干货敬请关注公众号。如果本文对你有所帮助，欢迎点赞、推荐和转发，也欢迎关注后续文章，一起考证、一起学习 `GaussDB` 分布式数据库。**





GaussDB 的物理参数均保存在 gaussdb.conf 和 pg_hba.conf 配置文件中。根据内核控制范围，参数分为以下六种级别：

GaussDB 集群参数管理(GUC)

数据库

运维

云计算

GaussDB集群参数管理详解：涵盖INTERNAL、POSTMASTER、SIGHUP、BACKEND、SUSET、USERSET六种参数级别，介绍gs_guc命令的set/reload/check操作及SQL级参数调整方法，助你高效配置分布式数据库核心参数。

分布式数据库

数据库管理

数据库集群

代码解释

服务器

路由

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

GaussDB 集群参数管理(GUC)-腾讯云开发者社区-腾讯云

GaussDB 集群参数管理(GUC)

GaussDB 集群参数管理(GUC)

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐