印刻数据库

外观

KingBaseES 核心配置参数 ​

概述 ​

KingBaseES 核心配置参数是影响数据库实例基本运行的关键参数，它们决定了数据库的内存分配、连接管理、查询处理、日志管理等核心功能。正确配置这些参数对于确保数据库的稳定运行和最佳性能至关重要。

本文档将详细介绍 KingBaseES 中最重要的核心配置参数，包括参数的含义、默认值、取值范围和配置建议，重点结合生产运维场景，提供实用的配置指导和最佳实践。

内存相关参数 ​

shared_buffers ​

含义：共享缓冲区大小，用于缓存数据块和索引块，是数据库性能的关键参数。

默认值：

  • V8 R6：128MB
  • V8 R7：256MB

取值范围：

  • 最小：128kB
  • 最大：操作系统允许的最大共享内存

生产配置建议：

  • 一般建议设置为系统内存的 25%-40%
  • 对于内存大于 64GB 的系统，可以考虑设置为系统内存的 25%
  • 对于内存较小的系统（小于 8GB），可以考虑设置为系统内存的 40%
  • 配置后需要重启数据库生效
  • 生产环境示例（32GB 内存）：
    shared_buffers = 8GB
  • 生产环境示例（128GB 内存）：
    shared_buffers = 32GB

work_mem ​

含义：单个查询在执行过程中使用的工作内存，用于排序、哈希连接等操作。

默认值：

  • V8 R6：4MB
  • V8 R7：4MB

取值范围：

  • 最小：64kB
  • 最大：2GB

生产配置建议：

  • 根据查询复杂度和并发度调整
  • 对于复杂查询，可以适当增大
  • 对于高并发系统，需要保守设置，避免内存不足
  • 建议值：4MB-32MB
  • 可以在会话级别动态调整，适合临时处理复杂查询
  • 生产环境示例（OLTP 系统）：
    work_mem = 8MB
  • 生产环境示例（OLAP 系统）：
    work_mem = 32MB

maintenance_work_mem ​

含义：维护操作（如 VACUUM、CREATE INDEX 等）使用的内存。

默认值：

  • V8 R6：64MB
  • V8 R7：64MB

取值范围：

  • 最小：1MB
  • 最大：2GB

生产配置建议：

  • 一般建议设置为系统内存的 5%-10%
  • 最大值不超过 2GB
  • 可以加快维护操作的执行速度
  • 配置后需要重启数据库生效
  • 生产环境示例（32GB 内存）：
    maintenance_work_mem = 2GB

temp_buffers ​

含义：会话级别的临时表缓冲区大小。

默认值：

  • V8 R6：8MB
  • V8 R7：8MB

取值范围：

  • 最小：800kB
  • 最大：操作系统允许的最大内存

生产配置建议：

  • 根据临时表的使用情况调整
  • 对于频繁使用临时表的系统，可以适当增大
  • 建议值：8MB-128MB
  • 可以在会话级别动态调整
  • 生产环境示例：
    temp_buffers = 32MB

effective_cache_size ​

含义：优化器估计的系统可用缓存大小，包括 shared_buffers 和操作系统缓存。

默认值：

  • V8 R6：4GB
  • V8 R7：4GB

取值范围：

  • 最小：128MB
  • 最大：操作系统允许的最大内存

生产配置建议：

  • 建议设置为系统内存的 50%-75%
  • 不影响实际内存分配，仅用于优化器成本计算
  • 配置后不需要重启，通过 SIGHUP 信号生效
  • 生产环境示例（32GB 内存）：
    effective_cache_size = 20GB

连接与会话相关参数 ​

max_connections ​

含义：允许的最大并发连接数。

默认值：

  • V8 R6：100
  • V8 R7：200

取值范围：

  • 最小：10
  • 最大：10000

生产配置建议：

  • 根据系统资源和业务需求调整
  • 一般建议不超过 CPU 核心数的 2-4 倍
  • 过大的连接数会消耗大量系统资源
  • 配置后需要重启数据库生效
  • 建议使用连接池（如 PgBouncer）减少实际连接数
  • 生产环境示例（16 核 CPU）：
    max_connections = 500

superuser_reserved_connections ​

含义：为超级用户预留的连接数，用于在连接数满时进行管理操作。

默认值：

  • V8 R6：3
  • V8 R7：3

取值范围：

  • 最小：0
  • 最大：max_connections - 1

生产配置建议：

  • 建议保持默认值或适当增大
  • 确保在连接数满时能够进行管理操作
  • 配置后需要重启数据库生效
  • 生产环境示例：
    superuser_reserved_connections = 5

unix_socket_directories ​

含义：Unix 套接字文件的存储目录。

默认值：

  • V8 R6：/tmp
  • V8 R7：/tmp

取值范围：

  • 任意有效的目录路径

生产配置建议：

  • 建议设置为安全的目录，限制访问权限
  • 可以设置多个目录，用逗号分隔
  • 配置后需要重启数据库生效
  • 生产环境示例：

unix_socket_directories = '/var/run/kingbase,/tmp'


### listen_addresses

**含义**：数据库监听的 IP 地址，用于接受 TCP/IP 连接。

**默认值**：
- V8 R6：localhost
- V8 R7：localhost

**取值范围**：
- '*'：监听所有 IP 地址
- 具体 IP 地址列表，用逗号分隔

**生产配置建议**：
- 生产环境建议只监听特定的 IP 地址
- 不要使用 '*'，避免安全风险
- 配置后需要重启数据库生效
- 生产环境示例：

listen_addresses = '192.168.1.100,127.0.0.1'


### port

**含义**：数据库监听的 TCP/IP 端口。

**默认值**：
- V8 R6：54321
- V8 R7：54321

**取值范围**：
- 最小：1
- 最大：65535

**生产配置建议**：
- 建议使用默认端口或自定义端口
- 避免使用知名端口，减少安全风险
- 配置后需要重启数据库生效
- 生产环境示例（使用默认端口）：

port = 54321


## 查询处理相关参数

### max_parallel_workers

**含义**：系统允许的最大并行工作进程数。

**默认值**：
- V8 R6：8
- V8 R7：16

**取值范围**：
- 最小：0
- 最大：操作系统允许的最大进程数

**生产配置建议**：
- 一般建议设置为 CPU 核心数
- 对于多核系统，可以适当增大
- 配置后需要重启数据库生效
- 生产环境示例（24 核 CPU）：

max_parallel_workers = 24


### max_parallel_workers_per_gather

**含义**：单个 Gather 节点允许的最大并行工作进程数。

**默认值**：
- V8 R6：2
- V8 R7：4

**取值范围**：
- 最小：0
- 最大：max_parallel_workers

**生产配置建议**：
- 建议设置为 CPU 核心数的 1/4 到 1/2
- 对于 OLTP 系统，可以适当减小
- 对于 OLAP 系统，可以适当增大
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例（OLTP 系统）：

max_parallel_workers_per_gather = 4

- 生产环境示例（OLAP 系统）：

max_parallel_workers_per_gather = 8


### max_parallel_maintenance_workers

**含义**：维护操作（如 CREATE INDEX）允许的最大并行工作进程数。

**默认值**：
- V8 R6：2
- V8 R7：4

**取值范围**：
- 最小：0
- 最大：max_parallel_workers

**生产配置建议**：
- 建议设置为 CPU 核心数的 1/4 到 1/2
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

max_parallel_maintenance_workers = 4


### random_page_cost

**含义**：随机读取页面的成本估计，用于查询优化器选择执行计划。

**默认值**：
- V8 R6：4.0
- V8 R7：4.0

**取值范围**：
- 最小：0.1
- 最大：100.0

**生产配置建议**：
- 对于 SSD 存储，可以设置为 1.1-2.0
- 对于 HDD 存储，保持默认值
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例（SSD 存储）：

random_page_cost = 1.1


### seq_page_cost

**含义**：顺序读取页面的成本估计，用于查询优化器选择执行计划。

**默认值**：
- V8 R6：1.0
- V8 R7：1.0

**取值范围**：
- 最小：0.1
- 最大：100.0

**生产配置建议**：
- 一般保持默认值
- 可以根据存储性能适当调整
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

seq_page_cost = 1.0


## 日志相关参数

### logging_collector

**含义**：是否启用日志收集器，用于将日志写入文件。

**默认值**：
- V8 R6：off
- V8 R7：on

**取值范围**：
- on | off

**生产配置建议**：
- 生产环境建议启用
- 便于日志管理和分析
- 配置后需要重启数据库生效
- 生产环境示例：

logging_collector = on


### log_directory

**含义**：日志文件的存储目录。

**默认值**：
- V8 R6：log
- V8 R7：log

**取值范围**：
- 任意有效的目录路径

**生产配置建议**：
- 建议设置为专门的日志目录
- 确保有足够的磁盘空间
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

log_directory = 'pg_log'


### log_filename

**含义**：日志文件的命名格式。

**默认值**：
- V8 R6：postgresql-%Y-%m-%d_%H%M%S.log
- V8 R7：kingbase-%Y-%m-%d_%H%M%S.log

**取值范围**：
- 包含时间占位符的字符串

**生产配置建议**：
- 建议包含日期和时间信息
- 便于日志归档和查找
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例（按天轮转）：

log_filename = 'kingbase-%Y-%m-%d.log'


### log_rotation_age

**含义**：日志文件的轮转时间间隔。

**默认值**：
- V8 R6：1d
- V8 R7：1d

**取值范围**：
- 最小：1min
- 最大：1y

**生产配置建议**：
- 建议根据日志量调整
- 一般设置为 1d 或 1h
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例（高并发系统）：

log_rotation_age = 1h


### log_rotation_size

**含义**：日志文件的最大大小，超过后进行轮转。

**默认值**：
- V8 R6：10MB
- V8 R7：100MB

**取值范围**：
- 最小：0（不根据大小轮转）
- 最大：1GB

**生产配置建议**：
- 建议根据磁盘空间调整
- 一般设置为 100MB-500MB
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

log_rotation_size = 500MB


## 检查点相关参数

### checkpoint_timeout

**含义**：检查点的时间间隔。

**默认值**：
- V8 R6：5min
- V8 R7：15min

**取值范围**：
- 最小：30s
- 最大：1h

**生产配置建议**：
- 建议设置为 15min-30min
- 增大该值可以减少检查点频率，降低 I/O 负载
- 但会增加恢复时间
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

checkpoint_timeout = 30min


### max_wal_size

**含义**：检查点之间允许生成的最大 WAL 日志大小。

**默认值**：
- V8 R6：1GB
- V8 R7：4GB

**取值范围**：
- 最小：2MB
- 最大：操作系统允许的最大值

**生产配置建议**：
- 建议设置为 shared_buffers 的 8-16 倍
- 增大该值可以减少检查点频率，降低 I/O 负载
- 但会增加磁盘空间使用
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例（shared_buffers=8GB）：

max_wal_size = 64GB


### min_wal_size

**含义**：检查点后保留的最小 WAL 日志大小。

**默认值**：
- V8 R6：80MB
- V8 R7：2GB

**取值范围**：
- 最小：2MB
- 最大：max_wal_size

**生产配置建议**：
- 建议设置为 max_wal_size 的 1/4 到 1/2
- 确保有足够的 WAL 日志用于恢复
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例（max_wal_size=64GB）：

min_wal_size = 16GB


### checkpoint_completion_target

**含义**：检查点完成目标，控制检查点的执行速度。

**默认值**：
- V8 R6：0.5
- V8 R7：0.9

**取值范围**：
- 最小：0.0
- 最大：1.0

**生产配置建议**：
- 建议设置为 0.8-0.9
- 增大该值可以使检查点更平滑地执行，降低 I/O 峰值
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

checkpoint_completion_target = 0.9


## 并发控制参数

### max_standby_archive_delay

**含义**：备库在恢复归档 WAL 时，允许的最大延迟时间。

**默认值**：
- V8 R6：30s
- V8 R7：30s

**取值范围**：
- 最小：0
- 最大：3600s

**生产配置建议**：
- 建议根据业务需求调整
- 对于要求低延迟的系统，可以适当减小
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

max_standby_archive_delay = 60s


### max_standby_streaming_delay

**含义**：备库在恢复流式 WAL 时，允许的最大延迟时间。

**默认值**：
- V8 R6：30s
- V8 R7：30s

**取值范围**：
- 最小：0
- 最大：3600s

**生产配置建议**：
- 建议根据业务需求调整
- 对于要求低延迟的系统，可以适当减小
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

max_standby_streaming_delay = 60s


### deadlock_timeout

**含义**：检测死锁的超时时间。

**默认值**：
- V8 R6：1s
- V8 R7：1s

**取值范围**：
- 最小：1ms
- 最大：1h

**生产配置建议**：
- 建议保持默认值或适当调整
- 过小会导致频繁的死锁检测，增加 CPU 负载
- 过大则会延迟死锁的发现
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例（高并发系统）：

deadlock_timeout = 500ms


### lock_timeout

**含义**：语句等待锁的超时时间。

**默认值**：
- V8 R6：0（无限制）
- V8 R7：0（无限制）

**取值范围**：
- 最小：0（无限制）
- 最大：1h

**生产配置建议**：
- 建议根据业务需求设置
- 可以避免长事务持有锁导致其他事务长时间等待
- 配置后不需要重启，通过 `SIGHUP` 信号生效
- 生产环境示例：

lock_timeout = 30s


## 版本差异

### V8 R6 与 V8 R7 的核心参数差异

| 参数名称 | V8 R6 默认值 | V8 R7 默认值 | 变化说明 | 生产影响 |
|---------|------------|------------|---------|---------|
| shared_buffers | 128MB | 256MB | 增大默认值，提高性能 | V8 R7 默认性能更好 |
| max_connections | 100 | 200 | 增大默认值，支持更多连接 | V8 R7 更适合高并发场景 |
| logging_collector | off | on | 默认启用日志收集器 | V8 R7 日志管理更便捷 |
| log_filename | postgresql-%Y-%m-%d_%H%M%S.log | kingbase-%Y-%m-%d_%H%M%S.log | 修改日志文件名前缀 | 便于区分 KingBaseES 日志 |
| max_wal_size | 1GB | 4GB | 增大默认值，减少检查点频率 | V8 R7 I/O 性能更优 |
| min_wal_size | 80MB | 2GB | 增大默认值，确保足够的 WAL 日志 | V8 R7 恢复更可靠 |
| checkpoint_timeout | 5min | 15min | 增大默认值，减少检查点频率 | V8 R7 I/O 负载更低 |
| checkpoint_completion_target | 0.5 | 0.9 | 增大默认值，使检查点更平滑 | V8 R7 I/O 峰值更平缓 |
| max_parallel_workers | 8 | 16 | 增大默认值，支持更多并行查询 | V8 R7 并行查询性能更好 |
| max_parallel_workers_per_gather | 2 | 4 | 增大默认值，提高并行查询性能 | V8 R7 复杂查询更快 |

### V8 R7 新增核心参数

1. **wal_keep_size**：控制主库保留的 WAL 日志大小，用于支持备库复制
 - 生产建议：根据备库延迟情况设置，一般 10GB-50GB
 - 示例：`wal_keep_size = 20GB`

2. **jit**：控制是否启用即时编译，提高查询性能
 - 生产建议：OLAP 系统建议启用，OLTP 系统可根据实际情况调整
 - 示例：`jit = on`

3. **jit_inline_above_cost**：控制 JIT 内联的成本阈值
 - 生产建议：根据查询复杂度调整
 - 示例：`jit_inline_above_cost = 500000`

4. **jit_optimize_above_cost**：控制 JIT 优化的成本阈值
 - 生产建议：根据查询复杂度调整
 - 示例：`jit_optimize_above_cost = 500000`

## 生产环境配置最佳实践

### 参数调整原则

- **循序渐进**：一次只调整少量参数，避免大范围变更
- **基于数据**：根据监控数据和性能测试结果调整
- **考虑业务**：结合业务特点和负载类型调整
- **测试验证**：在测试环境验证后再应用到生产环境
- **记录变更**：详细记录参数变更，便于回滚和分析

### 不同负载类型的配置建议

#### OLTP 负载

- **内存参数**：
- shared_buffers：系统内存的 25%-30%
- work_mem：4MB-8MB（保守设置，避免内存不足）
- effective_cache_size：系统内存的 50%-60%

- **连接参数**：
- max_connections：根据并发需求调整，一般不超过 CPU 核心数的 2-3 倍
- 必须使用连接池减少实际连接数

- **查询参数**：
- 适当降低并行查询参数，减少 CPU 竞争
- random_page_cost：根据存储类型调整

- **检查点参数**：
- checkpoint_timeout：15min-30min
- max_wal_size：shared_buffers 的 8-12 倍
- checkpoint_completion_target：0.8-0.9

#### OLAP 负载

- **内存参数**：
- shared_buffers：系统内存的 30%-40%
- work_mem：16MB-64MB（增大工作内存，提高复杂查询性能）
- effective_cache_size：系统内存的 60%-75%

- **连接参数**：
- max_connections：可以适当减小，OLAP 系统并发度一般较低

- **查询参数**：
- 适当增大并行查询参数，提高查询性能
- max_parallel_workers_per_gather：CPU 核心数的 1/2 左右
- enable_parallel_append：on
- enable_parallel_hash：on

- **检查点参数**：
- 与 OLTP 负载类似，但可以考虑更大的 max_wal_size

### 配置文件管理

- **版本控制**：对配置文件进行版本控制，便于追踪变更
- **备份**：在修改前备份配置文件，使用 `cp kingbase.conf kingbase.conf.bak`
- **注释**：为非默认参数添加注释，说明配置原因和时间
- **格式规范**：保持配置文件的格式规范，便于阅读
- **集中管理**：对于集群环境，考虑使用配置管理工具（如 Ansible）集中管理配置文件

## 常见问题

### 如何查看当前参数值？

可以使用以下方法查看当前参数值：

- 使用 SQL 命令：`SHOW 参数名;` 或 `SELECT name, setting FROM sys_settings WHERE name = '参数名';`
- 使用 `ksql` 命令：`\show 参数名`
- 查看配置文件：直接查看 kingbase.conf 文件
- 生产环境建议：使用监控工具（如 Prometheus + Grafana）实时监控参数变化

### 如何使参数变更生效？

参数变更的生效方式取决于参数类型：

- **需要重启**：修改配置文件后，需要重启数据库生效（如 shared_buffers、max_connections）
- **SIGHUP 信号**：修改配置文件后，发送 SIGHUP 信号到数据库进程生效
```bash
# Linux 环境
kill -SIGHUP $(pgrep -f kingbase)

# Windows 环境
使用服务管理器重启服务
  • 立即生效：使用 SET 或 ALTER SYSTEM SET 命令立即生效
    sql
    -- 会话级别立即生效
SET work_mem = '16MB';

-- 全局级别永久生效
ALTER SYSTEM SET shared_buffers = '16GB';

如何在会话级别调整参数？ ​

可以使用 SET 命令在会话级别调整参数，仅对当前会话有效：

sql
SET work_mem = '16MB';

这在处理复杂查询时非常有用，可以临时提高工作内存，而不影响其他会话。

如何在全局级别永久调整参数？ ​

可以使用 ALTER SYSTEM SET 命令在全局级别永久调整参数：

sql
ALTER SYSTEM SET shared_buffers = '16GB';

该命令会将参数写入 postgresql.auto.conf 文件，重启后生效。生产环境建议使用这种方式，便于版本控制和管理。

如何验证参数调整的效果？ ​

可以通过以下方法验证参数调整的效果：

  • 性能测试：运行基准测试，比较调整前后的性能指标（如 TPS、QPS）
  • 监控数据：观察 CPU、内存、I/O 等资源使用率的变化
  • 查询执行计划：使用 EXPLAIN ANALYZE 检查查询执行计划的变化
  • 日志分析：分析日志中的性能相关信息，如慢查询日志
  • 生产建议：使用 A/B 测试，逐步调整参数，观察业务指标变化

如何回滚参数变更？ ​

可以通过以下方法回滚参数变更：

  • 会话级别变更：关闭会话或使用 RESET 参数名; 命令
  • 全局级别变更：使用 ALTER SYSTEM RESET 参数名; 命令
  • 配置文件变更：恢复备份的配置文件并重启数据库
  • 生产建议：每次参数变更前，详细记录当前参数值和变更原因，便于快速回滚

生产环境参数调整的最佳流程是什么？ ​

  1. 监控分析：通过监控工具分析当前性能瓶颈
  2. 制定计划：根据分析结果，制定参数调整计划
  3. 测试验证：在测试环境验证参数调整效果
  4. 备份配置：备份生产环境当前配置文件
  5. 执行变更：在业务低峰期执行参数变更
  6. 验证效果：监控生产环境，验证变更效果
  7. 记录变更：详细记录变更内容、时间和效果
  8. 准备回滚：如果出现问题，立即执行回滚计划

总结 ​

KingBaseES 核心配置参数是影响数据库性能和稳定性的关键因素。正确理解和配置这些参数对于确保数据库的最佳运行至关重要。

在生产环境中，参数配置需要结合系统硬件资源、业务需求和负载类型进行调整。遵循参数调整原则，循序渐进，基于数据进行决策，并在测试环境验证后再应用到生产环境。

同时，需要注意不同版本之间的参数差异，了解新特性和默认值变化，以便充分利用数据库的性能潜力。通过合理配置核心参数，可以充分发挥 KingBaseES 的性能优势，确保数据库的稳定运行，满足业务需求。

通过合理配置核心参数，可以充分发挥 KingBaseES 的性能潜力，确保数据库的稳定运行，满足业务需求。