跳转到主要内容

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

返回本页常规视图.

文件位置

File Locations 分类下的 7 个 PostgreSQL 核心配置参数档案。

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

1 - config_file

config_file：设置服务器主配置文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器主配置文件。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

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

默认值变迁

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

机制详解

设置服务器主配置文件。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 config_file 与 allow_alter_system、data_directory、hba_file 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

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

场景 建议
OLTP config_file 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

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 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · data_directory · hba_file · ident_file · external_pid_file · extension_destdir

参考资料

2 - data_directory

data_directory：设置服务器数据目录。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器数据目录。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

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

默认值变迁

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

机制详解

设置服务器数据目录。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 data_directory 与 allow_alter_system、config_file、hba_file 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

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

场景 建议
OLTP data_directory 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

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 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · config_file · hba_file · ident_file · external_pid_file · extension_destdir

参考资料

3 - extension_destdir

extension_destdir 是 Debian/PGDG 下游提供的扩展暂存前缀 GUC，实测存在于打包版 PostgreSQL 9.5–17；它从未进入 PostgreSQL 上游，并从 PG18 实测包中消失。
说明

Fact — 实测 pg_settings 简述译文：设置加载扩展时要加在路径前的目录。（实测下游 pg_settings 简述。）

身份

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

生命周期

Fact 值
首次观测 PG9.5
在档版本 PG9.5–17
移除版本 PG18
引入提交 Debian/PGDG 下游补丁 — Debian-specific extension_destdir patch used for extension build-time testing
提交日期 —
Discussion 下游文档

默认值变迁

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

机制详解

版本矩阵证明，Debian/PGDG 二进制从 PG9.5 到 PG17 暴露 extension_destdir。穷尽 PostgreSQL 上游 GUC 源码的 pickaxe 也找不到引入提交，因为该名称来自 Debian 的 extension_destdir 打包补丁，而不是 PostgreSQL 上游源码树。

该补丁在服务器寻找扩展 control/SQL 文件以及函数背后的动态库时，加上类似 DESTDIR 的暂存根目录。Debian 的 pg_virtualenv 用它在文件安装到最终系统路径前测试软件包；它明确服务于打包与构建测试，并不是通用生产扩展搜索路径。

从 PG18 起，应使用上游 extension_control_path 管理 control/SQL 文件，并用 dynamic_library_path 管理共享库，或把扩展安装到标准位置。启动新版本前，要从配置文件、ALTER SYSTEM、角色/数据库设置和生成模板中彻底删除 extension_destdir。

调优建议

提示

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

场景 建议
OLTP 把它视为下游迁移债务，而不是调优项。应以受支持路径打包扩展，用数据库服务账号测试 extension_control_path 与 dynamic_library_path，并在升级 PG18 前删除旧键。
OLAP ETL 与分析扩展栈同样要迁移，包括 worker 和备用库；应按最终文件布局演练 CREATE EXTENSION、ALTER EXTENSION UPDATE、恢复与故障转移。
小规格 优先使用标准软件包位置。单节点几乎不会从重建 Debian 构建暂存机制中获益，而未知 GUC 足以阻止现代服务器启动。

Pigsty 取值

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

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

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

常见坑

  • 把 extension_destdir 写成 PostgreSQL 上游参数，或为它伪造上游引入提交。
  • 在 PG18+ 继续下发该下游名称，而实测包已经不再识别它。
  • 只迁移扩展 control 文件，却忘记路径设计中的共享库部分。
  • 只用构建用户测试，数据库服务账号却无法读取最终目录、文件或父路径。

关联参数

extension_control_path · dynamic_library_path · shared_preload_libraries · session_preload_libraries · config_file

参考资料

4 - external_pid_file

external_pid_file：将 postmaster PID 写入指定文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：将 postmaster PID 写入指定文件。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

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

默认值变迁

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

机制详解

将 postmaster PID 写入指定文件。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 external_pid_file 与 allow_alter_system、config_file、data_directory 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

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

场景 建议
OLTP external_pid_file 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

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 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · config_file · data_directory · hba_file · ident_file · extension_destdir

参考资料

5 - hba_file

hba_file：设置服务器的 HBA 配置文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器的 HBA 配置文件。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

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

默认值变迁

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

机制详解

设置服务器的 HBA 配置文件。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 hba_file 与 allow_alter_system、config_file、data_directory 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

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

场景 建议
OLTP hba_file 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

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 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · config_file · data_directory · ident_file · external_pid_file · extension_destdir

参考资料

6 - hosts_file

hosts_file：设置服务器的 hosts 配置文件路径。实测在档范围为 PG19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器的 hosts 配置文件路径。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

Fact 值
首次观测 PG19 Beta 3
在档版本 PG19 Beta 3
移除版本 否
引入提交 4f433025f666 — ssl: Serverside SNI support for libpq
提交日期 2026-03-18
Discussion 讨论 1

默认值变迁

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

机制详解

hosts_file：设置服务器的 hosts 配置文件路径。该值在服务器启动时固定，修改后必须安排受控重启。 本站在 PG19 Beta 3 实测到它；boot_val 是编译或初始化基线，并不能证明某个运行集群的当前有效值。

该路径指向 PG19 新增的服务器端 SNI 映射文件 pg_hosts.conf。启用 ssl_sni 后，hostname、/no_sni/ 与通配条目可选择证书、私钥、可选 CA 和口令命令；文件为空或不存在时回退到 postgresql.conf 中的普通 TLS 文件。

应与 ssl_sni、ssl_cert_file、ssl_key_file、ssl_ca_file 一起理解。请在目标服务器检查 SHOW 与 pg_settings，确认 source 和 pending_restart，并在修改前后对比真实负载、日志和资源指标。

调优建议

提示

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

场景 建议
OLTP 通过分批客户端上线，验证证书选择与到期告警，并监控认证失败。保留测试过的回退方案，把文件权限和密钥轮换作为同一变更的一部分。
OLAP 批处理驱动与长连接 ETL 也应采用同一安全策略；测试不发送 SNI 的客户端、凭据到期自动化、reload 行为和证书链兼容性。
小规格 优先保持简单且有文档的 TLS 与凭据策略。没有覆盖每个主机名和回退路径的测试就不要启用多证书路由，更不能降低验证强度来掩盖配置错误。

Pigsty 取值

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

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

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

常见坑

  • 把 hosts_file 的实测 boot_val 当成初始化后或托管集群当前有效值的证明。
  • 忽略 pg_settings 报告的 postmaster context，误以为修改会立即生效。
  • 孤立修改该参数，没有检查关联上限、可观测性和回滚路径。
  • 在生产中依赖测试版行为，却没有在 PostgreSQL 19 正式版发布后重新验证。

关联参数

ssl_sni · ssl_cert_file · ssl_key_file · ssl_ca_file · hba_file

参考资料

7 - ident_file

ident_file：设置服务器的 ident 配置文件。实测在档范围为 PG9.0–19 Beta 3；最后在档的 PG19 Beta 3 启动默认值为 not set，context 为 postmaster。这是测试版快照事实，PostgreSQL 19 正式发布前仍可能变化。
说明

Fact — 官方简述译文：设置服务器的 ident 配置文件。

身份

类型 值string
上游 pg_settings 类型
Context 值postmaster
修改后需要重启数据库
单位 值—
原始单位
范围 值—
最后在档版本的原始上下限
枚举值 值—
非枚举类型记为 —
分类 值File Locations
上游分类
最后 boot 值 值—
not set

生命周期

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

默认值变迁

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

机制详解

设置服务器的 ident 配置文件。该值在服务器启动时固定，修改后必须重启。

该路径在服务器启动早期解析，服务账号必须具备正确的目录遍历与文件权限。路径参数是否需要重启，与目标文件内容是否可 reload 是两个不同问题。

应把 ident_file 与 allow_alter_system、config_file、data_directory 一起监控和变更。先在对应角色与真实负载上验证，再按其 postmaster context 选择会话修改、reload 或 restart；历史默认值并不等于当前有效值。

调优建议

提示

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

场景 建议
OLTP ident_file 是部署拓扑而非负载调优项。使用绝对路径、最小权限和原子化配置发布，并在重启/重载前由 postgres 服务账号验证可读写性。
OLAP 规则与 OLTP 相同；若数据或配置位于独立挂载点，额外验证启动顺序、备份覆盖和故障切换节点上的路径一致性。
小规格 保持默认同目录布局最简单；只有备份、包管理或权限隔离有明确收益时才拆分路径。

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 专属理由。

常见坑

  • 服务账号缺少目录遍历、读取或写入权限。
  • 混淆路径参数的重启要求与目标文件内容的 reload 行为。
  • 故障切换节点或备份清单未包含相同路径。
  • 使用相对路径并依赖不稳定的工作目录。

关联参数

allow_alter_system · config_file · data_directory · hba_file · external_pid_file · extension_destdir

参考资料