跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

客户端连接默认

Client Connection Defaults 分类下的 47 个 PostgreSQL 核心配置参数档案。

条目 URL 保持扁平；本分类仅用于侧栏与浏览组织。

1 - DateStyle

DateStyle 定义日期和时间值的显示格式。
说明

Fact — 官方简述译文：设置日期和时间值的显示格式。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值ISO, MDY
ISO, MDY

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 ISO, MDY — ISO, MDY

机制详解

DateStyle：设置日期和时间值的显示格式。该值包含两个相互独立的部分：输出样式与 DMY/MDY/YMD 字段顺序；后者也决定如何解释有歧义的输入。

DateStyle 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 DateStyle 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 DateStyle；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 DateStyle 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 DateStyle，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 在意外的 MDY/DMY 顺序下解析 01/02/03 等有歧义值。

关联参数

IntervalStyle · TimeZone · lc_time · timezone_abbreviations · log_timezone

参考资料

2 - IntervalStyle

IntervalStyle 定义 interval 值的显示格式。
说明

Fact — 官方简述译文：设置 interval 值的显示格式。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值postgres, postgres_verbose, sql_standard, iso_8601
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值postgres
postgres

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 postgres — postgres

机制详解

IntervalStyle：设置 interval 值的显示格式。四种模式分别面向 PostgreSQL 兼容格式、详细格式、SQL 标准字面量与 ISO 8601；它也会改变有歧义 interval 输入的解释方式。

IntervalStyle 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 IntervalStyle 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 IntervalStyle；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 IntervalStyle 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 IntervalStyle，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 IntervalStyle。

关联参数

DateStyle · TimeZone · lc_time · timezone_abbreviations · log_timezone

参考资料

3 - TimeZone

TimeZone 定义用于显示和解释时间戳的时区。
说明

Fact — 官方简述译文：设置用于显示和解释时间戳的时区。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值GMT
GMT

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 UNKNOWN — UNKNOWN
PG9.1 — — not set
PG9.2–19 Beta 3 GMT — GMT

机制详解

TimeZone：设置用于显示和解释时间戳的时区。它影响 timestamptz 的显示及未显式带时区的时间戳输入解释，但已存储的时间点本身不随显示时区改变。

TimeZone 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 TimeZone 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 TimeZone；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 TimeZone 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 TimeZone，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 比较显示后的时间戳，却未保留原始时间点与显式时区上下文。

关联参数

DateStyle · IntervalStyle · lc_time · timezone_abbreviations · log_timezone

参考资料

4 - bytea_output

bytea_output 定义 bytea 的输出格式。
说明

Fact — 官方简述译文：设置 bytea 的输出格式。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值escape, hex
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值hex
hex

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 hex — hex

机制详解

bytea_output：设置 bytea 的输出格式。该选择只影响文本输出；无论如何设置，bytea 输入都接受 hex 与 escape 两种语法。

bytea_output 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 bytea_output 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 bytea_output；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 bytea_output 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 bytea_output，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 bytea_output。

关联参数

extra_float_digits · xmlbinary · xmloption · client_encoding · DateStyle

参考资料

5 - check_function_bodies

check_function_bodies 是 PostgreSQL 中用于在 CREATE FUNCTION 和 CREATE PROCEDURE 时检查例程体的参数。
说明

Fact — 官方简述译文：在 CREATE FUNCTION 和 CREATE PROCEDURE 时检查例程体。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 on — on

机制详解

check_function_bodies：在 CREATE FUNCTION 和 CREATE PROCEDURE 时检查例程体。关闭后会跳过创建时验证，适合转储恢复与前向引用，但也会把错误推迟到实际执行时暴露。

check_function_bodies 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 普通迁移保持 check_function_bodies 为 on，让无效例程体尽早失败；只在受控转储恢复或前向引用序列中临时关闭，并立即恢复。
OLAP 分析例程同样需要创建时验证；批量部署不是隐藏语法或依赖错误的理由。
小规格 保持 on；验证成本发生在例程创建时，优于生产执行期间才发现函数损坏。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 check_function_bodies，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 check_function_bodies。

关联参数

default_table_access_method · default_tablespace · temp_tablespaces · default_toast_compression · maintenance_work_mem

参考资料

6 - client_encoding

client_encoding 定义客户端字符集编码。
说明

Fact — 官方简述译文：设置客户端字符集编码。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值SQL_ASCII
SQL_ASCII

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 SQL_ASCII — SQL_ASCII

机制详解

client_encoding：设置客户端字符集编码。若存在对应转换，PostgreSQL 会在该编码与数据库编码之间转换文本；SQL_ASCII 并不代表真实字符集，而会绕过有价值的校验。

client_encoding 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 client_encoding 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 client_encoding；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 client_encoding 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 client_encoding，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 把 SQL_ASCII 当作真实编码，允许无效字节序列穿过客户端边界。

关联参数

lc_messages · lc_monetary · lc_numeric · lc_time · default_text_search_config

参考资料

7 - client_min_messages

client_min_messages 定义发送给客户端的消息级别。
说明

Fact — 官方简述译文：设置发送给客户端的消息级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值debug5, debug4, debug3, debug2, debug1, log, notice, warning, error
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值notice
notice

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 notice — notice

机制详解

client_min_messages：设置发送给客户端的消息级别。该阈值控制返回客户端的消息，而非写入服务器日志的消息；INFO 消息不受此阈值抑制。

client_min_messages 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它影响客户端协议中的诊断消息流，而 log_min_messages 与 log_min_error_statement 独立控制服务器端记录；INFO 是始终发送的特殊级别。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按应用诊断契约设置 client_min_messages。保留可操作告警，并按角色或会话调整阈值，而不是让整个集群静音。
OLAP 分析与交互用户可能希望看到 NOTICE，但批处理管线应明确选择可解析的消息，避免把通知当作结果行。
小规格 除非实测客户端消息成为问题，否则保留默认 NOTICE；抑制消息不会显著增加服务器容量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 client_min_messages，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 照搬 log_min_messages 的严重级别理解，忽略客户端顺序对 LOG 的处理不同且始终发送 INFO。
  • 全局抑制警告，隐藏应用本应展示的弃用信息或运维指引。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 client_min_messages。

关联参数

log_min_messages · log_min_error_statement · log_min_duration_statement · log_min_duration_sample · log_statement_sample_rate · log_transaction_sample_rate

参考资料

8 - createrole_self_grant

createrole_self_grant 定义 CREATEROLE 用户是否将新建角色自动授予自身，以及使用哪些授权选项。
说明

Fact — 官方简述译文：设置 CREATEROLE 用户是否将新建角色自动授予自身，以及使用哪些授权选项。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 e5b8a4c098ad — Add new GUC createrole_self_grant.
提交日期 2023-01-10
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 "" — empty string

机制详解

createrole_self_grant：设置 CREATEROLE 用户是否将新建角色自动授予自身，以及使用哪些授权选项。可选项为 set、inherit 或二者；它自动完成创建者凭 ADMIN OPTION 本可执行的授权，对超级用户没有实际影响。

createrole_self_grant 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 createrole_self_grant 当作正确性或安全控制，而非吞吐旋钮。严格限制 SET 权限，并由可信的角色或应用策略建立取值。
OLAP 若 createrole_self_grant 必须不同，使用专用分析角色，并验证导出、触发器、策略与名称解析仍保持数据正确性。
小规格 除非有文档化的修复或兼容流程，否则保持 createrole_self_grant 的安全默认值；临时变化应留痕并自动恢复。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 createrole_self_grant，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 createrole_self_grant。

关联参数

search_path · row_security · session_replication_role · event_triggers · restrict_nonsystem_relation_kind

参考资料

9 - default_table_access_method

default_table_access_method 定义新建表默认使用的表访问方法。
说明

Fact — 官方简述译文：设置新建表默认使用的表访问方法。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值heap
heap

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 8586bf7ed888 — tableam: introduce table AM infrastructure.
提交日期 2019-03-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 heap — heap

机制详解

default_table_access_method：设置新建表默认使用的表访问方法。仅当 CREATE TABLE、CREATE MATERIALIZED VIEW 或 SELECT INTO 未指定访问方法时才会读取它；既有关系不会改变。

default_table_access_method 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 除非替代表访问方法已通过并发、WAL、备份、复制、升级与工具链测试，否则保持 heap；关键 DDL 应显式写明选择。
OLAP 以代表性扫描、装载、更新和维护压测替代方案，再限定到专用对象，不要过早改变默认值。
小规格 使用 heap；替代访问方法会增加运维依赖，并不是有限硬件的通用补救。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_table_access_method，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_table_access_method。

关联参数

default_tablespace · temp_tablespaces · default_toast_compression · check_function_bodies · maintenance_work_mem

参考资料

10 - default_tablespace

default_tablespace 定义创建表和索引时使用的默认表空间。
说明

Fact — 官方简述译文：设置创建表和索引时使用的默认表空间。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

default_tablespace：设置创建表和索引时使用的默认表空间。它选择新建持久表和索引的位置，不用于临时对象或 CREATE DATABASE；某些配置上下文中的无效名称会回退到数据库默认表空间。

default_tablespace 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 default_tablespace 与模式管理策略一致，并在迁移中显式写出重要存储选择；任何物理布局变化都应用接近生产的写负载压测。
OLAP 为批量对象与高溢写作业有意识地使用 default_tablespace，采用前核对 I/O 放置、压缩支持与运维工具。
小规格 除非节点有经验证的替代存储路径或恢复需求，否则保留 default_tablespace 上游默认值；简单配置更少带来恢复意外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_tablespace，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_tablespace。

关联参数

default_table_access_method · temp_tablespaces · default_toast_compression · check_function_bodies · maintenance_work_mem

参考资料

11 - default_text_search_config

default_text_search_config 定义默认的文本搜索配置。
说明

Fact — 官方简述译文：设置默认的文本搜索配置。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值pg_catalog.simple
pg_catalog.simple

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 pg_catalog.simple — pg_catalog.simple

机制详解

default_text_search_config：设置默认的文本搜索配置。只有调用方未显式指定配置时，文本搜索函数才使用它；initdb 可能选择与区域设置匹配的配置，而非内置 simple。

default_text_search_config 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按语言域与应用角色设置 default_text_search_config，或在长期查询中显式传入配置；在每个副本核对词典与软件包。
OLAP 在可复现索引与报表作业中固定配置，避免区域变化静默改变分词或排名。
小规格 除非需要语言感知搜索，否则使用 pg_catalog.simple 或 initdb 选择的区域配置；额外词典增加维护而非免费提升质量。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_text_search_config，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_text_search_config。

关联参数

client_encoding · lc_messages · lc_monetary · lc_numeric · lc_time

参考资料

12 - default_toast_compression

default_toast_compression 定义可压缩值默认使用的压缩方法。
说明

Fact — 官方简述译文：设置可压缩值默认使用的压缩方法。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值pglz, lz4
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值lz4
lz4

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 bbe0a81db69b — Allow configurable LZ4 TOAST compression.
提交日期 2021-03-19
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–18 pglz — pglz
PG19 Beta 3 lz4 — lz4

机制详解

default_toast_compression：设置可压缩值默认使用的压缩方法。它为新写入的可压缩值选择 pglz，或在编译支持时选择 lz4；列级 COMPRESSION 子句优先于会话默认值。

default_toast_compression 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 用代表性宽值、更新率、CPU、WAL 与存储压测 pglz 和 lz4；重要模式应优先显式指定列 COMPRESSION，而非依赖意外的会话默认值。
OLAP 构建支持时 LZ4 可能更偏向快速压缩与解压，但改变新写入策略前必须测量真实可压缩性与扫描行为。
小规格 除非 CPU 与空间测量及软件包支持证明 lz4 合适，否则保留 pglz；改变默认值不会重压缩既有值。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_toast_compression，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_toast_compression。

关联参数

default_table_access_method · default_tablespace · temp_tablespaces · check_function_bodies · maintenance_work_mem

参考资料

13 - default_transaction_deferrable

default_transaction_deferrable 定义新事务默认是否可延迟。
说明

Fact — 官方简述译文：设置新事务默认是否可延迟。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 dafaa3efb75c — Implement genuine serializable isolation level.
提交日期 2011-02-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 off — off

机制详解

default_transaction_deferrable：设置新事务默认是否可延迟。该默认值只对只读可串行化事务有意义：事务可等待安全快照，随后避免序列化失败。

default_transaction_deferrable 属于 USER 上下文，可按角色、数据库或会话设置；新事务开始时才复制该值，因此不会重写已经进行中的事务。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 default_transaction_deferrable。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 default_transaction_deferrable 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_transaction_deferrable，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_transaction_deferrable。

关联参数

default_transaction_isolation · transaction_isolation · default_transaction_read_only · transaction_read_only · transaction_deferrable

参考资料

14 - default_transaction_isolation

default_transaction_isolation 定义每个新事务的默认隔离级别。
说明

Fact — 官方简述译文：设置每个新事务的默认隔离级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值serializable, repeatable read, read committed, read uncommitted
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值read committed
read committed

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 read committed — read committed

机制详解

default_transaction_isolation：设置每个新事务的默认隔离级别。每个事务开始时，PostgreSQL 会把该值复制到 transaction_isolation；它改变一致性语义，而不仅是性能。

default_transaction_isolation 属于 USER 上下文，可按角色、数据库或会话设置；新事务开始时才复制该值，因此不会重写已经进行中的事务。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 default_transaction_isolation。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 default_transaction_isolation 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_transaction_isolation，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_transaction_isolation。

关联参数

transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable · transaction_deferrable

参考资料

15 - default_transaction_read_only

default_transaction_read_only 定义新事务默认是否只读。
说明

Fact — 官方简述译文：设置新事务默认是否只读。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

default_transaction_read_only：设置新事务默认是否只读。每个事务继承该默认值，但只读模式仍允许修改临时表，也不能替代备用库或权限层面的强制控制。

default_transaction_read_only 属于 USER 上下文，可按角色、数据库或会话设置；新事务开始时才复制该值，因此不会重写已经进行中的事务。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 default_transaction_read_only。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 default_transaction_read_only 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 default_transaction_read_only，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 default_transaction_read_only。

关联参数

default_transaction_isolation · transaction_isolation · transaction_read_only · default_transaction_deferrable · transaction_deferrable

参考资料

16 - dynamic_library_path

dynamic_library_path 定义动态可加载模块的搜索路径。
说明

Fact — 官方简述译文：设置动态可加载模块的搜索路径。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Other Defaults
上游分类
最后 boot 值 值$libdir
$libdir

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 $libdir — $libdir

机制详解

dynamic_library_path：设置动态可加载模块的搜索路径。只有模块名不含目录部分时才使用该搜索路径；$libdir 指向 PostgreSQL 版本对应的库目录。

dynamic_library_path 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 dynamic_library_path 限制在管理员控制且版本匹配的目录，并保留 $libdir；只有部署与回滚显式管理时才使用绝对模块路径。
OLAP 只有经过评审的分析扩展软件包在所有故障转移目标完全一致时才新增搜索目录。
小规格 保持 $libdir；扩大本地代码搜索路径没有容量收益，只会增加打包与信任风险。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 dynamic_library_path，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 dynamic_library_path。

关联参数

shared_preload_libraries · session_preload_libraries · local_preload_libraries · jit_provider · extension_control_path

参考资料

17 - event_triggers

event_triggers 是控制是否启用事件触发器的 PostgreSQL 开关。
说明

Fact — 官方简述译文：启用事件触发器。

身份

类型 值bool
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 7750fefdb2b8 — Add GUC for temporarily disabling event triggers
提交日期 2023-09-25
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 on — on

机制详解

event_triggers：启用事件触发器。该开关会整体禁用所有事件触发器，用于紧急修复；它不是选择性触发策略，并要求较高的 SET 权限。

event_triggers 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应调优 event_triggers，也不应把关闭作为常态。只能在受控修复会话中临时关闭，定位故障触发器后立即恢复。
OLAP 保持事件触发器启用；只有文档化批量装载流程评审过所有丢失的审计或 DDL 副作用后才可例外。
小规格 保持默认 on；禁用事件触发器不会节省有意义的资源，却可能静默绕过控制。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 event_triggers，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 event_triggers。

关联参数

search_path · row_security · session_replication_role · restrict_nonsystem_relation_kind · createrole_self_grant

参考资料

18 - extension_control_path

extension_control_path 定义扩展控制文件的搜索路径。
说明

Fact — 官方简述译文：设置扩展控制文件的搜索路径。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Other Defaults
上游分类
最后 boot 值 值$system
$system

生命周期

Fact 值
首次观测 PG18
在档版本 PG18–19 Beta 3
移除版本 否
引入提交 4f7f7b037585 — extension_control_path
提交日期 2025-03-19
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG18–19 Beta 3 $system — $system

机制详解

extension_control_path：设置扩展控制文件的搜索路径。PostgreSQL 用该路径查找扩展的主控制文件，随后从找到主文件的同一目录加载脚本与次级控制文件。

extension_control_path 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持 $system 优先，只加入管理员控制且控制文件、脚本、本地库、升级与回滚共同版本化的扩展仓库。
OLAP 只有为主库与备用库软件包一致分发经评审扩展目录时才使用独立路径，并测试 CREATE EXTENSION 与每条升级边。
小规格 保持 $system；额外控制文件根目录不会提升容量，却让扩展来源与灾难恢复更难审计。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG18–19 Beta 3 未修改；OLAP: PG18–19 Beta 3 未修改；CRIT: PG18–19 Beta 3 未修改；TINY: PG18–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 extension_control_path，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 extension_control_path。

关联参数

shared_preload_libraries · session_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider

参考资料

19 - extra_float_digits

extra_float_digits 定义浮点值文本输出所使用的数字位数。
说明

Fact — 官方简述译文：设置浮点值文本输出所使用的数字位数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值-15 – 3
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值1
1

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–11 0 — 0
PG12–19 Beta 3 1 — 1

机制详解

extra_float_digits：设置浮点值文本输出所使用的数字位数。自 PostgreSQL 12 起，正值选择最短精确输出；零或负值选择旧式舍入输出，可能失去往返精度。

extra_float_digits 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 extra_float_digits 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 extra_float_digits；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 extra_float_digits 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 extra_float_digits，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 沿用 PostgreSQL 12 之前的理解，忽略正值现已选择最短精确输出。

关联参数

bytea_output · xmlbinary · xmloption · client_encoding · DateStyle

参考资料

20 - gin_fuzzy_search_limit

gin_fuzzy_search_limit 定义 GIN 精确搜索允许返回的最大结果数。
说明

Fact — 官方简述译文：设置 GIN 精确搜索允许返回的最大结果数。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Other Defaults
上游分类
最后 boot 值 值0
0

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 — 0

机制详解

gin_fuzzy_search_limit：设置 GIN 精确搜索允许返回的最大结果数。正值会让宽泛的 GIN 搜索随机返回匹配子集，以结果完整性换取工作量上限；零保留精确结果。

gin_fuzzy_search_limit 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

GIN 行为还取决于索引级存储参数、工作或维护内存、autovacuum，以及被索引值与谓词的形态。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在测量到相关 GIN 维护或搜索路径后才调整 gin_fuzzy_search_limit。若只是单个索引特殊，优先使用索引级覆盖而非全局修改。
OLAP 对批量装载或宽泛搜索，应联合测试 gin_fuzzy_search_limit 对摄取延迟、清理尖峰、结果完整性与维护窗口的影响。
小规格 不要仅因达到默认值就调高 gin_fuzzy_search_limit；应约束内存与 I/O 突发，且除非明确接受近似结果，否则保持精确查询语义。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 gin_fuzzy_search_limit，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 为修复单个特殊索引而修改集群级 GIN 参数，而非使用其存储参数。
  • 调优时忽略清理延迟、I/O 突发、autovacuum 联动或结果完整性。
  • 设置正值却未告知调用方，精确搜索可能只返回不完整的随机子集。

关联参数

gin_pending_list_limit · maintenance_work_mem · work_mem · vacuum_cleanup_index_scale_factor · autovacuum_work_mem

参考资料

21 - gin_pending_list_limit

gin_pending_list_limit 定义 GIN 索引待处理列表的最大大小。
说明

Fact — 官方简述译文：设置 GIN 索引待处理列表的最大大小。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值kB
原始单位
范围 值64 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值4096
4 MiB

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 c291503b1c82 — Rename pending_list_cleanup_size to gin_pending_list_limit.
提交日期 2014-11-13
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 4096 kB 4 MiB

机制详解

gin_pending_list_limit：设置 GIN 索引待处理列表的最大大小。当 GIN 索引启用 fastupdate 时，超过该上限会触发待处理列表批量并入主索引；可用索引级存储参数覆盖。

gin_pending_list_limit 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

GIN 行为还取决于索引级存储参数、工作或维护内存、autovacuum，以及被索引值与谓词的形态。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 只有在测量到相关 GIN 维护或搜索路径后才调整 gin_pending_list_limit。若只是单个索引特殊，优先使用索引级覆盖而非全局修改。
OLAP 对批量装载或宽泛搜索，应联合测试 gin_pending_list_limit 对摄取延迟、清理尖峰、结果完整性与维护窗口的影响。
小规格 不要仅因达到默认值就调高 gin_pending_list_limit；应约束内存与 I/O 突发，且除非明确接受近似结果，否则保持精确查询语义。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 未修改；OLAP: PG9.5–19 Beta 3 未修改；CRIT: PG9.5–19 Beta 3 未修改；TINY: PG9.5–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 gin_pending_list_limit，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 为修复单个特殊索引而修改集群级 GIN 参数，而非使用其存储参数。
  • 调优时忽略清理延迟、I/O 突发、autovacuum 联动或结果完整性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 gin_pending_list_limit。

关联参数

gin_fuzzy_search_limit · maintenance_work_mem · work_mem · vacuum_cleanup_index_scale_factor · autovacuum_work_mem

参考资料

22 - icu_validation_level

icu_validation_level 定义报告无效 ICU 区域设置字符串所用的消息级别。
说明

Fact — 官方简述译文：设置报告无效 ICU 区域设置字符串所用的消息级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值disabled, debug5, debug4, debug3, debug2, debug1, log, notice, warning, error
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值warning
warning

生命周期

Fact 值
首次观测 PG16
在档版本 PG16–19 Beta 3
移除版本 否
引入提交 1671f990dd66 — Validate ICU locales.
提交日期 2023-03-28
Discussion 讨论 1 · 讨论 2

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG16–19 Beta 3 warning — warning

机制详解

icu_validation_level：设置报告无效 ICU 区域设置字符串所用的消息级别。该参数改变无效 ICU 区域标识符的报告方式，既可关闭报告，也可提升为错误。

icu_validation_level 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 保持 icu_validation_level 为 WARNING，让无效区域标识可见；只有迁移门禁已清理既有输入时才提升为 ERROR。
OLAP 分析对象创建采用同一验证策略；降低级别可能让不一致区域元数据扩散到可复现作业。
小规格 不要为容量而调节；除非受控兼容问题需要临时降低报告级别，否则保持 WARNING。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG16–19 Beta 3 未修改；OLAP: PG16–19 Beta 3 未修改；CRIT: PG16–19 Beta 3 未修改；TINY: PG16–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 icu_validation_level，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 icu_validation_level。

关联参数

client_encoding · lc_messages · lc_monetary · lc_numeric · lc_time · default_text_search_config

参考资料

23 - idle_in_transaction_session_timeout

idle_in_transaction_session_timeout 定义事务内两次查询之间允许空闲的最长时间。
说明

Fact — 官方简述译文：设置事务内两次查询之间允许空闲的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG9.6
在档版本 PG9.6–19 Beta 3
移除版本 否
引入提交 c6dda1f48e57 — Add idle_in_transaction_session_timeout.
提交日期 2016-03-16
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.6–19 Beta 3 0 ms 0 ms

机制详解

idle_in_transaction_session_timeout：设置事务内两次查询之间允许空闲的最长时间。它终止在打开事务中空闲的会话，释放可能阻碍 vacuum 清理并导致膨胀的锁与旧快照。

idle_in_transaction_session_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 idle_in_transaction_session_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 idle_in_transaction_session_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 idle_in_transaction_session_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 10min 不同于 boot 值 10min
OLAP 0 等于 boot 值 0
CRIT 1min 不同于 boot 值 1min
TINY 10min 不同于 boot 值 10min
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.6–19 Beta 3 = 10min (dcs)；OLAP: PG9.6–19 Beta 3 = 0 (dcs)；CRIT: PG9.6–19 Beta 3 = 1min (dcs)；TINY: PG9.6–19 Beta 3 = 10min (dcs)。 建议（待人工复核）——编辑推断：模板限制被遗弃的打开事务，对 CRIT 使用更严格上限，并为刻意较长的 OLAP 分析事务保留无限；各负载仍需复核连接池与重试行为。

常见坑

  • 只在一个会话中修改 idle_in_transaction_session_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 idle_in_transaction_session_timeout。

关联参数

statement_timeout · lock_timeout · transaction_timeout · idle_session_timeout · deadlock_timeout

参考资料

24 - idle_session_timeout

idle_session_timeout 定义不在事务中时两次查询之间允许空闲的最长时间。
说明

Fact — 官方简述译文：设置不在事务中时两次查询之间允许空闲的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG14
在档版本 PG14–19 Beta 3
移除版本 否
引入提交 9877374bef76 — Add idle_session_timeout.
提交日期 2021-01-06
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG14–19 Beta 3 0 ms 0 ms

机制详解

idle_session_timeout：设置不在事务中时两次查询之间允许空闲的最长时间。它关闭事务外空闲的会话；这类会话通常成本不高，而连接池可能无法妥善处理服务器端意外断连。

idle_session_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 idle_session_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 idle_session_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 idle_session_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG14–19 Beta 3 未修改；OLAP: PG14–19 Beta 3 未修改；CRIT: PG14–19 Beta 3 未修改；TINY: PG14–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 idle_session_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 idle_session_timeout。

关联参数

statement_timeout · lock_timeout · transaction_timeout · idle_in_transaction_session_timeout · deadlock_timeout

参考资料

25 - jit_provider

jit_provider 定义要使用的 JIT 提供程序。
说明

Fact — 官方简述译文：设置要使用的 JIT 提供程序。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Shared Library Preloading
上游分类
最后 boot 值 值llvmjit
llvmjit

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–19 Beta 3
移除版本 否
引入提交 432bb9e04da4 — Basic JIT provider and error handling infrastructure.
提交日期 2018-03-21
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–19 Beta 3 llvmjit — llvmjit

机制详解

jit_provider：设置要使用的 JIT 提供程序。指定的提供程序实现 PostgreSQL JIT，且必须二进制兼容；更换提供程序需要重启服务器。

jit_provider 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不要把更换 jit_provider 当作常规调优；软件包支持时保持 llvmjit，并通过 jit 及成本阈值控制是否执行 JIT。
OLAP 只有在代表性编译时间、执行速度、内存、软件包兼容与重启测试后才评估提供程序；提供程序选择次于 JIT 阈值。
小规格 保持软件包提供的实现，通常应控制是否使用 JIT 而非替换实现；提供程序缺失可能破坏启动或 JIT 执行。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–19 Beta 3 未修改；OLAP: PG11–19 Beta 3 未修改；CRIT: PG11–19 Beta 3 未修改；TINY: PG11–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 期待重新加载或 SET 激活 jit_provider，而它实际需要受控重启服务器。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 jit_provider。

关联参数

shared_preload_libraries · session_preload_libraries · local_preload_libraries · dynamic_library_path · extension_control_path

参考资料

26 - lc_messages

lc_messages 定义显示消息所使用的语言。
说明

Fact — 官方简述译文：设置显示消息所使用的语言。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

lc_messages：设置显示消息所使用的语言。可接受的区域名称与可用翻译取决于操作系统和构建；空值继承服务器运行环境。

lc_messages 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 lc_messages 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 lc_messages；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 lc_messages 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lc_messages，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lc_messages。

关联参数

client_encoding · lc_monetary · lc_numeric · lc_time · default_text_search_config

参考资料

27 - lc_monetary

lc_monetary 定义格式化货币金额所使用的区域设置。
说明

Fact — 官方简述译文：设置格式化货币金额所使用的区域设置。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值C
C

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 C — C

机制详解

lc_monetary：设置格式化货币金额所使用的区域设置。它影响 to_char 等货币格式化函数，而不会改变 money 或 numeric 列中存储的数值。

lc_monetary 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 lc_monetary 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 lc_monetary；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 lc_monetary 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lc_monetary，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lc_monetary。

关联参数

client_encoding · lc_messages · lc_numeric · lc_time · default_text_search_config

参考资料

28 - lc_numeric

lc_numeric 定义格式化数字所使用的区域设置。
说明

Fact — 官方简述译文：设置格式化数字所使用的区域设置。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值C
C

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 C — C

机制详解

lc_numeric：设置格式化数字所使用的区域设置。它影响小数符号与分组符号等区域敏感数字格式，而普通 SQL 数字字面量仍遵循 SQL 语法。

lc_numeric 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 lc_numeric 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 lc_numeric；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 lc_numeric 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lc_numeric，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lc_numeric。

关联参数

client_encoding · lc_messages · lc_monetary · lc_time · default_text_search_config

参考资料

29 - lc_time

lc_time 定义格式化日期和时间所使用的区域设置。
说明

Fact — 官方简述译文：设置格式化日期和时间所使用的区域设置。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值C
C

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 C — C

机制详解

lc_time：设置格式化日期和时间所使用的区域设置。它控制格式化函数所用的区域敏感名称与布局；DateStyle 与 TimeZone 仍是独立控制项。

lc_time 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 lc_time 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 lc_time；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 lc_time 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lc_time，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lc_time。

关联参数

DateStyle · IntervalStyle · TimeZone · timezone_abbreviations · log_timezone

参考资料

30 - local_preload_libraries

local_preload_libraries 声明每个后端可由非特权用户预加载的共享库。
说明

Fact — 官方简述译文：列出每个后端可由非特权用户预加载的共享库。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Shared Library Preloading
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

local_preload_libraries：列出每个后端可由非特权用户预加载的共享库。非特权用户只能指定安装在 PostgreSQL plugins 子目录中的库，因此软件包放置本身构成安全边界。

虽然 local_preload_libraries 无需重启服务器即可配置，但只有新后端启动时才处理库列表；在既有连接中修改不会卸载或追溯加载模块。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应通用调优 local_preload_libraries。只加载或暴露经过评审的功能所需模块，验证二进制兼容性，并在上线前演练故障恢复。
OLAP 只有扩展或 JIT 需求经过测量后才使用 local_preload_libraries，并计入后端启动、常驻内存与连接池下的行为。
小规格 尽量精简 local_preload_libraries。模块缺失或不兼容可能拒绝连接或阻止启动，每个预加载库也会占用稀缺地址空间或内存。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 local_preload_libraries，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 local_preload_libraries。

关联参数

shared_preload_libraries · session_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

参考资料

31 - lock_timeout

lock_timeout 定义每次等待锁所允许的最长时间。
说明

Fact — 官方简述译文：设置每次等待锁所允许的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG9.3
在档版本 PG9.3–19 Beta 3
移除版本 否
引入提交 d43837d03067 — Add lock_timeout configuration parameter.
提交日期 2013-03-16
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.3–19 Beta 3 0 ms 0 ms

机制详解

lock_timeout：设置每次等待锁所允许的最长时间。计时对每次锁获取分别生效，而非限制语句总时长；相同或更短的 statement_timeout 会先触发。

lock_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 lock_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 lock_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 lock_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.3–19 Beta 3 未修改；OLAP: PG9.3–19 Beta 3 未修改；CRIT: PG9.3–19 Beta 3 未修改；TINY: PG9.3–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 lock_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 lock_timeout。

关联参数

statement_timeout · transaction_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

参考资料

32 - restrict_nonsystem_relation_kind

restrict_nonsystem_relation_kind 是 PostgreSQL 中用于禁止访问指定类别的非系统关系的参数。
说明

Fact — 官方简述译文：禁止访问指定类别的非系统关系。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG12
在档版本 PG12–19 Beta 3
移除版本 否
引入提交 79c7a7e29695 — Restrict accesses to non-system views and foreign tables during pg_dump.
提交日期 2024-08-05
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG12–19 Beta 3 "" — empty string

机制详解

restrict_nonsystem_relation_kind：禁止访问指定类别的非系统关系。目前支持 view 与 foreign-table；PostgreSQL 将其用作特殊会话的安全边界，而不是通用 SQL 授权机制。

restrict_nonsystem_relation_kind 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应把 restrict_nonsystem_relation_kind 当作通用安全策略调优。除非 PostgreSQL 子系统或严格限定的维护流程明确需要，否则保持空值。
OLAP 不要用它沙箱化任意分析用户；应通过权限、模式与行级策略实施访问控制。
小规格 保持默认空值；启用关系类别禁令没有容量收益，却可能意外破坏普通查询。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG12–19 Beta 3 未修改；OLAP: PG12–19 Beta 3 未修改；CRIT: PG12–19 Beta 3 未修改；TINY: PG12–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 restrict_nonsystem_relation_kind，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 restrict_nonsystem_relation_kind。

关联参数

search_path · row_security · session_replication_role · event_triggers · createrole_self_grant

参考资料

33 - row_security

row_security 是控制是否启用行级安全的 PostgreSQL 开关。
说明

Fact — 官方简述译文：启用行级安全。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值on
on

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–19 Beta 3
移除版本 否
引入提交 491c029dbc42 — Row-Level Security Policies (RLS)
提交日期 2014-09-19
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.5–19 Beta 3 on — on

机制详解

row_security：启用行级安全。对普通角色而言，off 不会绕过策略，而会在本应应用策略时抛错，使 pg_dump 等工具避免悄然得到不完整结果。

row_security 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 row_security 当作正确性或安全控制，而非吞吐旋钮。严格限制 SET 权限，并由可信的角色或应用策略建立取值。
OLAP 若 row_security 必须不同，使用专用分析角色，并验证导出、触发器、策略与名称解析仍保持数据正确性。
小规格 除非有文档化的修复或兼容流程，否则保持 row_security 的安全默认值；临时变化应留痕并自动恢复。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.5–19 Beta 3 未修改；OLAP: PG9.5–19 Beta 3 未修改；CRIT: PG9.5–19 Beta 3 未修改；TINY: PG9.5–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 row_security，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 把 off 当作绕过策略，而普通角色在本应应用策略时会收到错误。

关联参数

search_path · session_replication_role · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

参考资料

34 - search_path

search_path 定义解析未限定名称时的模式搜索顺序。
说明

Fact — 官方简述译文：设置解析未限定名称时的模式搜索顺序。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值"$user", public
“$user”, public

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–9.4 "$user",public — “$user”,public
PG9.5–19 Beta 3 "$user", public — “$user”, public

机制详解

search_path：设置解析未限定名称时的模式搜索顺序。它既控制名称查找，也决定未限定 CREATE 的目标模式；pg_catalog 与临时模式具有特殊的隐式搜索规则。

search_path 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 search_path 当作正确性或安全控制，而非吞吐旋钮。严格限制 SET 权限，并由可信的角色或应用策略建立取值。
OLAP 若 search_path 必须不同，使用专用分析角色，并验证导出、触发器、策略与名称解析仍保持数据正确性。
小规格 除非有文档化的修复或兼容流程，否则保持 search_path 的安全默认值；临时变化应留痕并自动恢复。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 search_path，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 把不受信角色可写的模式放在可信模式前，形成对象遮蔽攻击面。

关联参数

row_security · session_replication_role · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

参考资料

35 - session_preload_libraries

session_preload_libraries 声明每个后端在会话开始时预加载的共享库。
说明

Fact — 官方简述译文：列出每个后端在会话开始时预加载的共享库。

身份

类型 值string
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Shared Library Preloading
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.4
在档版本 PG9.4–19 Beta 3
移除版本 否
引入提交 070518ddab2c — Add session_preload_libraries configuration parameter
提交日期 2013-06-12
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.4–19 Beta 3 "" — empty string

机制详解

session_preload_libraries：列出每个后端在会话开始时预加载的共享库。列表会加载到每个新的匹配后端中，且只能由超级用户或适当授权角色设置；库缺失会拒绝连接。

虽然 session_preload_libraries 无需重启服务器即可配置，但只有新后端启动时才处理库列表；在既有连接中修改不会卸载或追溯加载模块。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应通用调优 session_preload_libraries。只加载或暴露经过评审的功能所需模块，验证二进制兼容性，并在上线前演练故障恢复。
OLAP 只有扩展或 JIT 需求经过测量后才使用 session_preload_libraries，并计入后端启动、常驻内存与连接池下的行为。
小规格 尽量精简 session_preload_libraries。模块缺失或不兼容可能拒绝连接或阻止启动，每个预加载库也会占用稀缺地址空间或内存。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.4–19 Beta 3 未修改；OLAP: PG9.4–19 Beta 3 未修改；CRIT: PG9.4–19 Beta 3 未修改；TINY: PG9.4–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 session_preload_libraries，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 session_preload_libraries。

关联参数

shared_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

参考资料

36 - session_replication_role

session_replication_role 定义当前会话对触发器和重写规则的处理方式。
说明

Fact — 官方简述译文：设置当前会话对触发器和重写规则的处理方式。

身份

类型 值enum
上游 pg_settings 类型
Context 值superuser
超级用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值origin, replica, local
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值origin
origin

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 origin — origin

机制详解

session_replication_role：设置当前会话对触发器和重写规则的处理方式。replica 会抑制普通触发器和规则，包括外键检查；更改该值还会丢弃已缓存计划。

session_replication_role 属于 SUPERUSER 上下文。超级用户或获授相应 SET 权限的角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

由于会话状态可能在连接池中残留，角色默认值、SET 权限、RESET 行为与应用取连接钩子都是有效控制边界的一部分。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应调优 session_replication_role。只有受控复制或修复流程才可设为 replica，且必须独立保证约束并恢复 origin。
OLAP 分析会话保持 origin；抑制触发器不会加速读取，却会在会话写入时造成严重风险。
小规格 保持 origin；它不是小节点优化，并可能绕过外键。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 session_replication_role，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 对可改变正确性、策略执行或名称解析的控制项授予过宽 SET 权限。
  • 池化连接交给另一个请求前，没有重置安全敏感的会话值。
  • 忘记 replica 模式既抑制应用触发器，也抑制外键触发器。

关联参数

search_path · row_security · event_triggers · restrict_nonsystem_relation_kind · createrole_self_grant

参考资料

37 - shared_preload_libraries

shared_preload_libraries 声明服务器启动时预加载的共享库。
说明

Fact — 官方简述译文：列出服务器启动时预加载的共享库。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Shared Library Preloading
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

shared_preload_libraries：列出服务器启动时预加载的共享库。库在共享内存定型前由 postmaster 一次性加载，可提供后续 LOAD 无法获得的钩子与共享状态；任一库缺失都会阻止服务器启动。

shared_preload_libraries 属于 POSTMASTER 上下文：PostgreSQL 在服务器启动时读取它，重新加载配置或会话 SET 都不能使新值生效。

库发现与预加载会和已安装二进制版本、扩展控制文件、服务器或后端启动，以及模块自身 GUC 相互作用。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 不应通用调优 shared_preload_libraries。只加载或暴露经过评审的功能所需模块，验证二进制兼容性，并在上线前演练故障恢复。
OLAP 只有扩展或 JIT 需求经过测量后才使用 shared_preload_libraries，并计入后端启动、常驻内存与连接池下的行为。
小规格 尽量精简 shared_preload_libraries。模块缺失或不兼容可能拒绝连接或阻止启动，每个预加载库也会占用稀缺地址空间或内存。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP pg_stat_statements, auto_explain 不同于 boot 值 '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
OLAP pg_stat_statements, auto_explain 不同于 boot 值 '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
CRIT pg_stat_statements, auto_explain 不同于 boot 值 '{{ pg_libs | default("$libdir/passwordcheck, pg_stat_statements, auto_explain") }}'
TINY pg_stat_statements, auto_explain 不同于 boot 值 '{{ pg_libs | default("pg_stat_statements, auto_explain") }}'
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs)；OLAP: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs)；CRIT: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs)；TINY: PG9.0–19 Beta 3 = pg_stat_statements, auto_explain (dcs)。 建议（待人工复核）——编辑推断：pg_stat_statements 与 auto_explain 提供全局查询统计和定向慢计划证据，并接受启动加载及共享开销。

常见坑

  • 期待重新加载或 SET 激活 shared_preload_libraries，而它实际需要受控重启服务器。
  • 指定缺失或 ABI 不兼容模块，导致连接失败或服务器无法启动。
  • 把搜索或预加载路径当作无害配置，忽略它决定服务器信任哪些本地代码。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 shared_preload_libraries。

关联参数

session_preload_libraries · local_preload_libraries · dynamic_library_path · jit_provider · extension_control_path

参考资料

38 - statement_timeout

statement_timeout 定义单条语句允许执行的最长时间。
说明

Fact — 官方简述译文：设置单条语句允许执行的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 0 ms 0 ms

机制详解

statement_timeout：设置单条语句允许执行的最长时间。计时从命令到达开始；现代版本会分别计算简单查询字符串中的各条语句，扩展协议则按 Parse/Bind/Execute 到 Sync 的消息周期计时。

statement_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 statement_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 statement_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 statement_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 statement_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 使用单一全局值，在终止失控请求的同时误杀合理维护与分析任务。

关联参数

lock_timeout · transaction_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

参考资料

39 - temp_tablespaces

temp_tablespaces 定义临时表和排序临时文件使用的表空间。
说明

Fact — 官方简述译文：设置临时表和排序临时文件使用的表空间。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值""
empty string

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 "" — empty string

机制详解

temp_tablespaces：设置临时表和排序临时文件使用的表空间。PostgreSQL 将该列表用于临时关系与执行器溢写文件，并在多个条目间分配工作；存在性和权限按设置上下文检查。

temp_tablespaces 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

只有 SQL 未显式选择时它才提供默认值，因此模式迁移、对象级选项、权限与后续 ALTER 都可能覆盖它或比它更长久。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 让 temp_tablespaces 与模式管理策略一致，并在迁移中显式写出重要存储选择；任何物理布局变化都应用接近生产的写负载压测。
OLAP 为批量对象与高溢写作业有意识地使用 temp_tablespaces，采用前核对 I/O 放置、压缩支持与运维工具。
小规格 除非节点有经验证的替代存储路径或恢复需求，否则保留 temp_tablespaces 上游默认值；简单配置更少带来恢复意外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 temp_tablespaces，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 期待修改默认值会重写既有对象或覆盖显式 DDL 子句。
  • 忽略表空间权限、已安装访问方法或压缩支持，以及恢复可移植性。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 temp_tablespaces。

关联参数

default_table_access_method · default_tablespace · default_toast_compression · check_function_bodies · maintenance_work_mem

参考资料

40 - timezone_abbreviations

timezone_abbreviations 是 PostgreSQL 中用于选择时区缩写定义文件的参数。
说明

Fact — 官方简述译文：选择时区缩写定义文件。

身份

类型 值string
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Locale and Formatting
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 UNKNOWN — UNKNOWN
PG9.1–19 Beta 3 — — not set

机制详解

timezone_abbreviations：选择时区缩写定义文件。所选集合会改变可接受的日期时间输入记号，同一缩写在不同区域集合中可能解析为不同含义。

timezone_abbreviations 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 timezone_abbreviations 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 timezone_abbreviations；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 timezone_abbreviations 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 timezone_abbreviations，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 接受区域特定缩写集合，使熟悉记号解析到不同 UTC 偏移。

关联参数

DateStyle · IntervalStyle · TimeZone · lc_time · log_timezone

参考资料

41 - transaction_deferrable

transaction_deferrable 定义当前事务是否可延迟，供只读可串行化事务安全启动。
说明

Fact — 官方简述译文：设置当前事务是否可延迟，供只读可串行化事务安全启动。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.1
在档版本 PG9.1–19 Beta 3
移除版本 否
引入提交 dafaa3efb75c — Implement genuine serializable isolation level.
提交日期 2011-02-07
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.1–19 Beta 3 off — off

机制详解

transaction_deferrable：设置当前事务是否可延迟，供只读可串行化事务安全启动。它反映当前事务状态，且只有只读可串行化事务在取得快照前才有实际意义。

transaction_deferrable 可在会话中设置，但代表当前事务；事务取得快照或执行冲突操作后，PostgreSQL 会限制更改。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 transaction_deferrable。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 transaction_deferrable 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.1–19 Beta 3 未修改；OLAP: PG9.1–19 Beta 3 未修改；CRIT: PG9.1–19 Beta 3 未修改；TINY: PG9.1–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 transaction_deferrable，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 transaction_deferrable。

关联参数

default_transaction_isolation · transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable

参考资料

42 - transaction_isolation

transaction_isolation 定义当前事务的隔离级别。
说明

Fact — 官方简述译文：设置当前事务的隔离级别。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值serializable, repeatable read, read committed, read uncommitted
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值read committed
read committed

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0 — — not set
PG9.1–11 default — default
PG12–19 Beta 3 read committed — read committed

机制详解

transaction_isolation：设置当前事务的隔离级别。它反映当前事务，初值来自 default_transaction_isolation；事务已经执行工作后不能任意提高隔离级别。

transaction_isolation 可在会话中设置，但代表当前事务；事务取得快照或执行冲突操作后，PostgreSQL 会限制更改。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 transaction_isolation。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 transaction_isolation 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 transaction_isolation，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 transaction_isolation。

关联参数

default_transaction_isolation · default_transaction_read_only · transaction_read_only · default_transaction_deferrable · transaction_deferrable

参考资料

43 - transaction_read_only

transaction_read_only 定义当前事务是否只读。
说明

Fact — 官方简述译文：设置当前事务是否只读。

身份

类型 值bool
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值off
off

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 off — off

机制详解

transaction_read_only：设置当前事务是否只读。它反映当前事务，初值来自 default_transaction_read_only；必须在执行与只读模式冲突的操作前设置。

transaction_read_only 可在会话中设置，但代表当前事务；事务取得快照或执行冲突操作后，PostgreSQL 会限制更改。

default_* 变量为对应 transaction_* 状态提供初值；隔离级别、只读状态、可延迟性、重试与快照寿命必须整体设计。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 首先按正确性语义选择 transaction_read_only。明确常见 OLTP 路径，只对一致性契约确有需要的事务覆盖其阻塞或重试行为。
OLAP 报表任务可结合只读事务，并按快照需求选择隔离级别；只有只读可串行化工作才考虑可延迟。
小规格 不要把 transaction_read_only 当作通用提速参数。更高隔离级别或长快照会在小节点上放大争用与 vacuum 压力。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 transaction_read_only，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 把事务语义当作性能实验修改，悄然削弱应用一致性契约。
  • 连接池签出或回滚重置不完整，导致会话残留事务相关状态。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 transaction_read_only。

关联参数

default_transaction_isolation · transaction_isolation · default_transaction_read_only · default_transaction_deferrable · transaction_deferrable

参考资料

44 - transaction_timeout

transaction_timeout 定义会话中任一非预备事务允许持续的最长时间。
说明

Fact — 官方简述译文：设置会话中任一非预备事务允许持续的最长时间。

身份

类型 值integer
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值ms
原始单位
范围 值0 – 2147483647
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0
0 ms

生命周期

Fact 值
首次观测 PG17
在档版本 PG17–19 Beta 3
移除版本 否
引入提交 51efe38cb92f — Introduce transaction_timeout
提交日期 2024-02-15
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG17–19 Beta 3 0 ms 0 ms

机制详解

transaction_timeout：设置会话中任一非预备事务允许持续的最长时间。它会终止会话而不仅取消一条语句，不适用于预备事务；当其更短时，更长的事务内空闲或语句超时将失去作用。

transaction_timeout 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

多个超时会重叠，最先到期的适用期限获胜；客户端、连接池、TCP 与服务器取消行为决定工作被重试、取消还是关闭会话。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 按服务延迟与故障预算设置 transaction_timeout，最好落在角色或应用层。实施集群级值前先验证重试与取消路径。
OLAP 分析任务通常需要更大或作业专属的 transaction_timeout；既要为遗弃工作保留有限护栏，也不要误杀合理的长扫描。
小规格 只有客户端或操作系统能正确处理终止时，才设置保守的有限 transaction_timeout；并验证维护任务有专用例外。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG17–19 Beta 3 未修改；OLAP: PG17–19 Beta 3 未修改；CRIT: PG17–19 Beta 3 未修改；TINY: PG17–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 transaction_timeout，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 忘记零通常表示禁用超时或把行为交给操作系统。
  • 设置重叠期限，却未明确哪个层负责重试、取消与连接丢弃。
  • 期待它处理预备事务，而预备事务被明确排除。

关联参数

statement_timeout · lock_timeout · idle_in_transaction_session_timeout · idle_session_timeout · deadlock_timeout

参考资料

45 - vacuum_cleanup_index_scale_factor

vacuum_cleanup_index_scale_factor 定义触发索引清理前允许新增元组数占 reltuples 的比例。
说明

Fact — 官方简述译文：设置触发索引清理前允许新增元组数占 reltuples 的比例。

身份

类型 值real
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值0 – 1e+10
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值0.1
0.1

生命周期

Fact 值
首次观测 PG11
在档版本 PG11–13
移除版本 PG14
引入提交 857f9c36cda5 — Skip full index scan during cleanup of B-tree indexes when possible
提交日期 2018-04-04
Discussion 讨论 1

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG11–13 0.1 — 0.1

机制详解

vacuum_cleanup_index_scale_factor：设置触发索引清理前允许新增元组数占 reltuples 的比例。这一 PostgreSQL 11–13 参数按插入量延后索引清理；PostgreSQL 14 调整索引清理决策模型后将其移除。

vacuum_cleanup_index_scale_factor 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

这一遗留决策作用于 B-tree 清理扫描，并与 VACUUM 统计、新增元组、可复用索引页及 autovacuum 调度联动；它不是 GIN 控制项。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 当前服务器不应调优 vacuum_cleanup_index_scale_factor：PostgreSQL 14 已移除它。在 11–13 上也只应针对实测索引清理问题修改，并规划升级行为。
OLAP 遗留批量装载系统应测量真实索引维护，而不是把已移除参数作为配置传说继续携带。
小规格 保留遗留默认值并升级；已移除参数不是管理小节点 vacuum 成本的长期办法。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG13 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG11–13 未修改；OLAP: PG11–13 未修改；CRIT: PG11–13 未修改；TINY: PG11–13 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 vacuum_cleanup_index_scale_factor，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 未在对应版本测量索引扫描、可复用页与 VACUUM 行为，就采用旧式 B-tree 清理启发式。
  • 把已移除的会话默认参数与当前 autovacuum 阈值或表级存储参数混淆。
  • 升级到 PostgreSQL 14+ 时仍保留这一未知参数配置行。

关联参数

autovacuum · autovacuum_vacuum_scale_factor · vacuum_cost_limit · vacuum_cost_delay · maintenance_work_mem · autovacuum_work_mem

参考资料

46 - xmlbinary

xmlbinary 定义二进制值在 XML 中的编码方式。
说明

Fact — 官方简述译文：设置二进制值在 XML 中的编码方式。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值base64, hex
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值base64
base64

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 base64 — base64

机制详解

xmlbinary：设置二进制值在 XML 中的编码方式。它影响 XML 构造函数中的 bytea 到 XML 转换；base64 与 hex 都能保留全部字节，但 hex 输出更大。

xmlbinary 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 xmlbinary 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 xmlbinary；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 xmlbinary 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 xmlbinary，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 xmlbinary。

关联参数

bytea_output · extra_float_digits · xmloption · client_encoding · DateStyle

参考资料

47 - xmloption

xmloption 定义隐式解析和序列化 XML 数据时将其视为文档还是内容片段。
说明

Fact — 官方简述译文：设置隐式解析和序列化 XML 数据时将其视为文档还是内容片段。

身份

类型 值enum
上游 pg_settings 类型
Context 值user
普通用户可在运行时修改
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值content, document
非枚举类型记为 —
分类 值Client Connection Defaults / Statement Behavior
上游分类
最后 boot 值 值content
content

生命周期

Fact 值
首次观测 PG9.0（研究下界）
在档版本 PG9.0–19 Beta 3
移除版本 否
引入提交 不作断言：早于 PG9.0 研究边界
提交日期 —
Discussion —

默认值变迁

PG9.0–19 Beta 3 实测 boot 默认值
版本 原始 boot_val 单位 人类可读值
PG9.0–19 Beta 3 content — content

机制详解

xmloption：设置隐式解析和序列化 XML 数据时将其视为文档还是内容片段。CONTENT 允许 XML 片段，而 DOCUMENT 要求单个格式良好的 XML 文档，因此会改变隐式转换与序列化行为。

xmloption 属于 USER 上下文。获授权角色可在会话内修改，ALTER ROLE 或 ALTER DATABASE 可为未来会话建立默认值。

它改变客户端边界上的表示、解析或区域行为，而不是物理存储。应与其他区域和格式参数，以及驱动的二进制或类型化协议协同考虑。

调优建议

提示

Advice。 以下建议是工作负载起点，必须用真实测量验证。

场景 建议
OLTP 把 xmloption 视为应用协议，而不是性能旋钮。按角色或连接池统一，并在客户端解析文本时明确固定线格式。
OLAP 为导出、报表与可复现分析任务固定 xmloption；若文件或 API 具有长期模式，优先在 SQL 中显式格式化。
小规格 除非客户端明确需要其他取值，否则保留上游或区域派生值；小规格服务器不会因调整 xmloption 获得容量收益。

Pigsty 取值

以下值来自固定 8 核、32 GiB、100 GiB SSD 夹具，并按 PG19 Beta 3 渲染当前 Pigsty 模板；这不表示 Pigsty 当前支持该历史或测试版本。

模板 有效值 与上游 boot 比较 源表达式
OLTP 未修改 — —
OLAP 未修改 — —
CRIT 未修改 — —
TINY 未修改 — —
注意

Advice — 待人工复核。 当前 Pigsty 模板投影事实：OLTP: PG9.0–19 Beta 3 未修改；OLAP: PG9.0–19 Beta 3 未修改；CRIT: PG9.0–19 Beta 3 未修改；TINY: PG9.0–19 Beta 3 未修改。 未发现覆盖值，因此不推断 Pigsty 专属理由。

常见坑

  • 只在一个会话中修改 xmloption，却认为角色默认值、数据库默认值或其他池化会话也已随之改变。
  • 误以为显示参数会改变已存储值或服务器端类型语义。
  • 未测试文本解析客户端、导出与池化会话就修改角色或数据库默认值。
  • 没有回滚计划及客户端或运维兼容测试，就全局修改 xmloption。

关联参数

bytea_output · extra_float_digits · xmlbinary · client_encoding · DateStyle

参考资料