27.6 模板参数与集群变更

Pigsty 把 PostgreSQL 参数放进：

hardware/workload template
  + cluster inventory
      + instance override
          + Patroni dynamic configuration
              + database/role defaults

这解决的是：

如何从同一份 desired state 可重复生成、分发、验证集群配置？

它不自动回答：

这个值是否适合我的 workload？

模板负责起点，实验负责偏离模板的理由。

27.6.1 从模板生成实例配置

四类起点

当前 Pigsty 官方模板：

`pg_conf`	目标
`tiny.yml`	小节点、开发/演示、受限资源
`oltp.yml`	延迟敏感交易
`olap.yml`	扫描、分析、较低并发与较高并行
`crit.yml`	更保守的关键业务策略

示例：

pg-test:
  hosts:
    10.10.10.11: { pg_seq: 1, pg_role: primary }
    10.10.10.12: { pg_seq: 2, pg_role: replica }
  vars:
    pg_cluster: pg-test
    pg_conf: oltp.yml
    node_tune: oltp

模板会根据 CPU、memory、disk/workload profile 计算多项参数。Pigsty optimization policy 当前以 25% memory 作为 shared buffer 默认起点，并按 profile 处理 connection、 parallel、vacuum、WAL 与 timeout。

profile 不是标签

选择 olap 不只是：

work_mem larger

还可能改变：

connections
parallel workers
maintenance
vacuum
timeout
I/O settings
logging

因此把 existing production cluster 从 oltp.yml 换到 olap.yml 是 multi-factor change。不要用一次切换来“测试 OLAP 参数”；先生成 diff，拆成可归因变更。

hardware 与 profile 必须匹配

Pigsty 官方把 tiny 用于小型/受限节点；oltp/olap 文档面向更大的常规实例。如果 1C2G 节点使用 aggressive profile：

template 仍可能生成 syntactically valid 配置；
server 仍可能启动；
但 worst-concurrency memory/worker budget 可能不安全。

参考沙箱就是一个值得审阅的事实：

server RAM       ~1.91 GiB
max_connections  500
work_mem          64 MiB
shared_buffers   ~489 MiB

这不代表当前 idle/8-client workload 已 OOM；它表示 platform limit 不能被应用当作 “500 条复杂 query 的安全并发”。

先预览 recommendation

当前 pig CLI 提供 tuning output：

pig pg tune
pig pg tune -p tiny
pig pg tune -p olap
pig pg tune -c 8 -m 32768 -d 500 -o yaml

这些命令用于生成/查看 recommendation；先确认本机安装版本的 pig pg tune --help。输出不是自动批准的生产变更。保存：

Pigsty version
PostgreSQL major
detected/overridden CPU memory disk
profile
generated output hash

同一 profile 在不同 Pigsty release 可能演进，升级后要 diff。

`pg_parameters` 显式覆盖

pg-test:
  hosts:
    10.10.10.11:
      pg_seq: 1
      pg_role: primary
    10.10.10.12:
      pg_seq: 2
      pg_role: replica
      pg_parameters:
        recovery_min_apply_delay: '5min'
  vars:
    pg_cluster: pg-test
    pg_conf: oltp.yml
    pg_parameters:
      log_min_duration_statement: 250
      track_io_timing: on

用途：

template baseline
  + reviewed cluster exception
      + reviewed instance exception

不是把所有 template 输出再复制一遍。重复复制会失去 template upgrade 能力。

inventory precedence

Pigsty 的 inventory 可以在 global、cluster、host 定义 pg_parameters，越具体的 inventory 变量覆盖越通用。还要叠加 PostgreSQL 自己的 file/DCS/catalog/session precedence。

因此两层问题：

Ansible variable resolution
  -> rendered configuration
      -> PostgreSQL/Patroni precedence
          -> effective session value

只看 YAML 不能证明最后生效。

list 参数的 YAML quoting

pg_parameters:
  shared_preload_libraries: 'timescaledb, pg_stat_statements, auto_explain'
  search_path: '"$user", public, app'

list-like GUC 必须作为一个 string 正确引用，避免 YAML 误解析或引号层级错误。render 后还要用 pg_file_settings 检查。

database 与 role 参数

某个 workload 特有的：

statement_timeout
work_mem
max_parallel_workers_per_gather
search_path
default_transaction_read_only

优先落到 Pigsty business object 的 database/user parameter，而不是 cluster global。它们最终进入 pg_db_role_setting，新 session 生效。

scope 要匹配：

all workload on cluster     cluster/instance
one database                database
one application identity    role-in-database
one job                     transaction/session

参数 exception 的元数据

YAML 本身不保存“为什么”。在 ADR/注释/变更系统记录：

parameter: work_mem
scope: role dbuser_report in database analytics
value: 256MB
reason: report-v4 spill experiment
evidence_run: ...
owner: data-platform
expires/review: 2026-10-01
rollback: 32MB

没有 expiry 的 exception 会永久累积。

27.6.2 区分 reload、restart 与滚动执行

先从 context 生成动作

SELECT
    name,
    context,
    setting,
    pending_restart
FROM pg_settings
WHERE name = ANY (ARRAY[
    'work_mem',
    'checkpoint_timeout',
    'shared_buffers',
    'max_connections',
    'shared_preload_libraries'
])
ORDER BY name;

动作矩阵：

context/scope	持久层	应用
role/database	catalog/IaC	新 session
`user`/`superuser` global default	config	reload + session lifecycle
`sighup`	config/DCS	reload
`backend`	config	reload + reconnect
`postmaster`	config/DCS	restart
init/build	cluster/binary	migration/rebuild

应用 `pg_parameters`

Pigsty 官方当前给出的 instance 参数应用入口：

./pgsql.yml -l pg-test -t pg_param

它会把 pg_parameters 渲染到受管配置。执行前：

确认 inventory 与 limit
查看 playbook version/help
做 diff/preview
确认 target 是 cluster 而非全环境
确认 secrets 不进命令行/log

执行后仍需 reload/restart 语义验证；“Ansible changed=1”不是 effective。

Patroni dynamic configuration

Patroni 的 cluster dynamic config 存在 DCS，由所有 member 消费；local config 又可能覆盖 DCS。改变 Patroni 管理的 PostgreSQL 参数时要识别 owner。

Pigsty/Patroni 文档说明：

dynamic config 会传播到成员； -非 restart 参数随后 reload；
postmaster 参数会标 pending_restart/restart_pending；
local Patroni config 可能优先于 dynamic；
bootstrap DCS config 只用于初始建群，之后应改 dynamic config。

不要只编辑最初 inventory 里的 bootstrap fragment，期待现有 DCS 自动变化。

reload

集群：

pg reload pg-test

本机 PostgreSQL：

pig pg reload

命令面与版本有关，执行前看 --help。两者 scope 不同：一个通过 Patroni 面向 cluster/member，一个是本机 service 操作。

reload 后：

SELECT pg_reload_conf();

返回 true 只表示 signal 发出，不等于每项应用成功。查：

SELECT * FROM pg_file_settings WHERE error IS NOT NULL;
SELECT name, setting, source, pending_restart
FROM pg_settings
WHERE name IN (...);

restart

restart 会断开本 member 的 session；HA cluster 中可能由 replica 承载重启，但：

primary restart 仍需 switchover/connection behavior；
replica 重启时丧失一份冗余；
catch-up 产生 I/O/WAL load；
sync quorum 可能变化；
pool/client 会 reconnect；
session state/prepared statement 消失。

执行前必须有：

healthy replica count
lag within gate
backup/archive healthy
N+1 capacity
restart duration/RTO
client retry budget
rollback restart time

immediate restart 会触发 crash recovery，不是普通快速捷径。

rolling 顺序

典型而非万能：

1. one replica
2. wait streaming/caught-up + effective validation
3. next replica
4. controlled switchover if primary must change
5. former primary
6. end-to-end service validation

每一步 gate：

Patroni role/state
timeline/LSN
replication slots
archive
service route
pending_restart
SLO/resource

若 candidate 导致 member 起不来，不应继续下一个。

mixed-config window

滚动期间：

member A candidate
member B baseline

要回答：

replication compatible？
failover 到 A/B 各如何？
read route 结果/性能不同？
logical worker/preload plugin compatible？
monitoring/alert 能区分？
rollback 是否仍可启动？

若不能容忍 mixed state，就不能称为 rolling change，需要 maintenance/migration design。

canary member 的局限

在 replica 测 work_mem/planner 参数：

read-only workload 可以；
primary write/WAL/commit 行为不能；
cache、data freshness、route 不同；
replica conflict/recovery 干扰；
promote 后 workload 变化。

canary 必须代表目标 mechanism。

27.6.3 用 SQL 和文件事实验证最终生效值

desired inventory

保存：

git commit
inventory path
cluster/member limit
profile and explicit overrides
render/playbook version
review/approval

不要在 public artifact 中发布 secret inventory。

configured file

SELECT
    sourcefile,
    sourceline,
    seqno,
    name,
    setting,
    applied,
    error
FROM pg_file_settings
WHERE name IN (...) OR error IS NOT NULL
ORDER BY seqno;

它能发现：

syntax error
unknown parameter
invalid value
duplicate overridden entry
restart-required entry not applied to runtime

但 view 反映 file 当前内容，不是 last applied。

effective server/session

SELECT
    inet_server_addr() AS server,
    current_setting('cluster_name') AS cluster,
    pg_is_in_recovery() AS in_recovery,
    name,
    setting,
    unit,
    context,
    source,
    pending_restart
FROM pg_settings
WHERE name = ANY (ARRAY[
    'shared_buffers',
    'work_mem',
    'max_connections',
    'checkpoint_timeout',
    'max_wal_size',
    'plan_cache_mode'
])
ORDER BY name;

每个 member、每种 service path、新旧 session 都要取样。

normalized units

比较时用 canonical bytes/ms：

SELECT
    name,
    current_setting(name) AS display,
    setting,
    unit
FROM pg_settings
WHERE name IN ('shared_buffers', 'work_mem', 'checkpoint_timeout');

setting=62592, unit=8kB 与 489MB 可能同值。字符串 diff 会制造假 drift。

Patroni/HA fact

cluster config in DCS
member pending_restart
member role/state/timeline/lag
PostgreSQL effective setting

四层要对齐。DCS 有 candidate 但 member 仍 pending restart，不算完成；PostgreSQL effective candidate 但 inventory 仍 baseline，也不算完成。

workload fact

变更生效不等于 hypothesis 成立。继续验证：

objective
non-regression
resource
failure/recovery
observation window

第 27 章实验同时保存：

global settings before/after；
session requested/effective plan_cache_mode；
prepared custom/generic count；
representative plan-shape hash；
raw transaction latency；
cleanup。

所以能证明：

candidate was actually tested
global config was not changed
auto already selected generic after early custom plans
material gain rule did not pass

验收矩阵

层	证据	pass
desired	inventory commit/diff	exact candidate
rendered	file/DCS	no unexpected entries
syntax	`pg_file_settings`	no error
effective	`pg_settings` every member	value/source/context
lifecycle	pending restart/new session	complete
HA	Patroni/replication	healthy
behavior	plans/SLO/resources	gates pass
rollback	restored desired/effective	tested

少任意一层，都只能标记 partially applied 或 pending。

配置变更的最终原则

Pigsty template gives a reviewed starting point
IaC gives repeatability
Patroni gives HA-aware distribution
PostgreSQL views give runtime truth
experiment gives causal confidence
ADR gives memory and accountability

任何单层都不能替代其余层。

上一节：参数作用域与变更方式 · 返回本章目录 · 下一节：实战：只调一个已证实的瓶颈 · 查看全书目录 · 查看索引中心

最后更新于 2026-07-30

27.5 参数作用域与变更方式 27.7 实战：只调一个已证实的瓶颈