PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

19.1. 设置参数 #

19.1.1. 参数名称与取值
19.1.2. 通过配置文件配置参数
19.1.3. 通过 SQL 接口调整参数
19.1.4. 通过命令行与环境变量设置参数
19.1.5. 管理配置文件内容与包含机制

19.1.1. 参数名称与取值 #

所有配置参数名称均不区分大小写。每个参数接受五种基本类型之一的数值:布尔值(boolean)、字符串(string)、整数(integer)、浮点数(floating point)或枚举值(enum)。参数类型决定了其设置语法规范:

  • 布尔值(Boolean): 取值可书写为 on、off、true、false、yes、no、1、0(均不区分大小写),或其中任一无歧义的前缀。

  • 字符串(String): 通常使用单引号将字符串值包裹,若值内部包含单引号需使用双单引号转义。若值为纯数字或简单标识符,引号通常可以省略。

  • 数值(整数与浮点数): 数值参数可以按照常规整数或浮点数格式指定;若参数为整数类型,小数会被四舍五入为最接近的整数。整数参数还额外支持以 0x 开头的十六进制以及以 0 开头的八进制输入。严禁在数值中使用千分位逗号分隔符。除十六进制输入外通常无需使用引号包裹。

  • 带单位的数值: 某些用于描述内存容量或时间长短的数值参数具备内置度量单位(如字节、千字节、数据块、毫秒、秒或分钟)。不带单位的纯数字将使用该参数的默认单位(可在系统视图 pg_settings.unit 中查阅)。为了书写直观,可以显式声明单位(例如 '120 ms' 表示 120 毫秒,'4 GB' 表示 4 吉字节),系统会自动将其换算为底层物理基准值。使用该特性时数值必须包裹在引号中作为字符串传入。

    • 合法的内存单位包括 B(字节)、kB(千字节)、MB(兆字节)、GB(吉字节)以及 TB(太字节)。内存单位的换算系数为 1024 而非 1000。

    • 合法的时间单位包括 us(微秒)、ms(毫秒)、s(秒)、min(分钟)、h(小时)以及 d(天)。

    如果带单位的值是小数,在存在更小单位的情况下, 它将被舍入到下一个更小单位的倍数。 例如,30.1 GB 将被转换为 30822 MB 而不是 32319628902 B。 如果参数是整数类型, 则在任何单位换算之后还会进行一次到整数的最终舍入。

  • 枚举类型: 枚举类型参数的书写方式与字符串参数相同,但被限制为只能取一组 有限值中的一个。这类参数允许的值可以从 pg_settings.enumvals 中查到。枚举参数值不区分大小写。

19.1.2. 通过配置文件配置参数 #

设置这些参数最根本的方法是编辑配置文件 postgresql.conf,该文件通常位于数据目录中。在初始化数据库集群目录时会在此处安装默认模板副本。该文件的典型内容示例如下:

# 这是一个注释
log_connections = all
log_destination = 'syslog'
search_path = '"$user", public'
shared_buffers = 128MB

每行指定一个配置参数。参数名与参数值之间的等号是可选的。空白字符在行中无特殊语义(引号内的参数值除外),空行将被忽略。井号(#)将其所在行的后续内容标记为注释。对于非简单标识符或非纯数字的参数值,必须使用单引号括起来。若要在参数值内部嵌入单引号,可使用双写单引号(推荐)或反斜杠转义单引号。如果文件中包含同一参数的多个条目,除了最后一个条目外,其余条目均会被忽略。

以此种方式设置的参数为整个数据库集群提供全局默认值。活跃会话所看到的配置值将以这些设置为准,除非它们在后续被覆盖。以下各小节将介绍管理员或普通用户覆盖这些默认值的各种途径。

每当服务端主进程接收到 SIGHUP 信号时,都会重新读取该配置文件;发送此信号最便捷的方式是在命令行执行 pg_ctl reload 或在 SQL 中调用函数 pg_reload_conf()。服务端主进程还会将该信号透传给所有当前正在运行的工作子进程,使现有连接会话也能感知到最新配置值(这将在它们完成当前正在执行的客户端命令之后发生)。或者,也可以直接向单个后端进程发送该信号。某些参数只能在服务器启动时设置;在配置文件中对这些参数所做的修改将被忽略,直到服务器重启后才生效。在处理 SIGHUP 重新加载期间,配置文件中的非法参数设置同样会被忽略(但会记录到日志中)。

除 postgresql.conf 外,数据目录下还包含名为 postgresql.auto.conf 的自动配置文件。该文件的格式与主配置文件完全一致,但专用于系统自动写入,严禁人工手动编辑。该文件保存通过 ALTER SYSTEM 命令设置的全局参数。系统每次读取主配置文件时都会自动读取该文件,且该文件中的配置具有更高优先级,会自动覆盖 postgresql.conf 中的同名参数。

外部运维工具也可以直接修改 postgresql.auto.conf。除非将 allow_alter_system 设置为 off,否则不建议在服务器运行期间进行外部修改,因为并发执行的 ALTER SYSTEM 命令可能会覆盖外部写入的修改。此类工具可以直接将新设置追加到文件末尾,或者选择去除重复配置项及注释(这与 ALTER SYSTEM 的处理逻辑一致)。

系统视图 pg_file_settings 可用于在生效前预测试对配置文件的修改,或者在发送 SIGHUP 信号后未达到预期生效效果时排查诊断故障。

19.1.3. 通过 SQL 接口调整参数 #

PostgreSQL 提供了三条专用的 SQL 命令用于设置配置默认值。前述的 ALTER SYSTEM 命令提供了一种直接在 SQL 会话中修改全局系统配置的途径,其功能等价于手动编辑主配置文件。此外,还提供了两条分别作用于数据库级与角色级的配置定制命令:

  • ALTER DATABASE 命令允许在特定数据库层级覆盖全局默认配置。

  • ALTER ROLE 命令允许为特定登录用户/角色定制专属的配置参数。

通过 ALTER DATABASE 与 ALTER ROLE 设置的参数值仅在启动全新的数据库客户端会话时生效。它们会覆盖从配置文件或命令行中读取的默认值,成为该会话后续运行的基础默认环境。请注意:某些仅限服务启动时确定的参数无法通过此类命令修改。

一旦客户端成功连接到数据库,PostgreSQL 还提供了两条额外的 SQL 命令(以及对应的底层函数)来交互式管理会话局部的配置参数:

  • 使用 SHOW 命令可以检视任何配置参数的当前实际生效值。对应的底层 SQL 函数为 current_setting(setting_name text)(参见 Section 9.28.1)。

  • 使用 SET 命令可以修改当前客户端会话内部的局部参数值,该修改对其他并发会话完全透明隔离。普通用户有权修改大部分会话级参数,部分特权参数则要求超级用户权限。对应的底层 SQL 函数为 set_config(setting_name, new_value, is_local)(参见 Section 9.28.1)。

此外,系统视图 pg_settings 可用于查看并动态修改当前会话的局部配置值:

  • 查询此视图类似于执行 SHOW ALL,但能提供远比后者更详尽的底层元数据。它也更具灵活性,因为支持指定复杂的过滤条件或与其他关系表进行关联查询。

  • 对该视图执行 UPDATE 命令(具体指更新其 setting 列),等价于执行 SET 命令。例如,如下操作:

    SET configuration_parameter TO DEFAULT;
    

    完全等价于:

    UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
    

19.1.4. 通过命令行与环境变量设置参数 #

除了设置全局默认值或在数据库/角色级别附加配置覆盖外,还可以通过 Shell 命令行与环境变量向 PostgreSQL 传递配置。服务端内核与 libpq 客户端库均支持通过 Shell 环境接收参数值。

  • 在服务器启动期间,可以通过 -c name=value 命令行选项或其等价的 --name=value 形式向 postgres 命令传递参数设置。例如:

    postgres -c log_connections=all --log-destination='syslog'
    

    以此种方式指定的配置会直接覆盖通过 postgresql.conf 或 ALTER SYSTEM 设置的参数值,因此若不重启服务器,它们无法被全局动态修改。

  • 当通过 libpq 启动客户端会话时,可以使用环境变量 PGOPTIONS 指定参数设置。通过此方式建立的配置仅在当前会话的生命周期内作为默认值生效,绝不影响其他并发会话。出于历史原因,PGOPTIONS 的格式类似于启动 postgres 命令时使用的格式;具体而言,在参数名前必须指定 -c 或前缀 --。例如:

    env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql
    

    其他客户端和编程语言库可能提供其自身的机制(通过 Shell 环境变量或连接属性),允许用户在不直接编写 SQL 命令的情况下调整会话设置。

19.1.5. 管理配置文件内容与包含机制 #

PostgreSQL 提供了多种机制,用于将复杂的 postgresql.conf 配置文件拆分为多个子文件。在管理多台具有相似但不完全相同配置的数据库服务器时,这些拆分与包含特性尤为有用。

除单个参数设置外,postgresql.conf 文件还可以包含包含指令(include directives),用于指定另一个需要读取并解析的文件,就如同直接将其内容插入到该指令所在位置一样。此特性允许将配置文件物理划分为独立的模块化片段。包含指令的书写格式十分简单:

include 'filename'

若文件名不是绝对路径,系统会将其视为相对于包含该指令的配置文件所在目录的相对路径。包含指令支持任意深度的嵌套。

此外还存在 include_if_exists 指令,其行为与 include 指令完全一致,唯一的区别在于当被引用的文件不存在或无法读取时:常规 include 会视其为致命错误,但 include_if_exists 仅向日志中记录一条信息并继续正常解析主配置文件。

postgresql.conf 文件还可以包含 include_dir 指令,用于指定包含一整个目录下的配置文件。书写格式如下:

include_dir 'directory'

非绝对目录名同样被视为相对于包含该指令的配置文件所在目录的相对路径。在指定的目录内部,仅有以 .conf 结尾的非目录常规文件会被加载解析。以点号(.)开头的隐式文件会被自动忽略,以避免在特定操作系统平台因隐藏文件引发意外故障。包含目录内的多个配置文件按照文件名升序排序规则(根据 C 区域设置规则,即数字先于字母,大写先于小写)依次进行加载解析。

包含文件或目录可用于对数据库配置进行逻辑模块化拆分,从而避免维护单个臃肿的 postgresql.conf 文件。以拥有两台内存容量不同数据库服务器的公司为例,两台服务器通常具有诸多相同的共享配置(例如日志参数),但内存相关参数在这两台服务器之间会有所不同,此外还可能存在特定于某台服务器的专属定制。管理这种情况的一种高效方法是将您环境的自定义配置拆分为三个文件。您可以将以下内容添加到 postgresql.conf 文件的末尾来包含它们:

include 'shared.conf'
include 'memory.conf'
include 'server.conf'

所有系统都共享完全相同的 shared.conf。具有特定内存容量的服务器可以共享相同的 memory.conf(例如所有 8GB 内存服务器共享一个文件,所有 16GB 内存服务器共享另一个文件)。最后,server.conf 中包含真正特定于单台主机的专属配置。

另一种优雅的架构是创建一个专用配置目录并将拆分的配置放置其中。例如,在 postgresql.conf 文件末尾引用一个 conf.d 目录:

include_dir 'conf.d'

然后您可以将 conf.d 目录中的文件命名如下:

00shared.conf
01memory.conf
02server.conf

这种命名规范建立了明确的文件加载顺序。这至关重要,因为服务器在读取配置文件时,针对特定参数仅采用最后遇到的设置值。在此示例中,conf.d/02server.conf 中设置的值将直接覆盖 conf.d/01memory.conf 中的同名配置。

或者,您可以使用语义更加明确的文件命名方式:

00shared.conf
01memory-8GB.conf
02server-foo.conf

这种编排方式为每种配置变体提供了唯一的名称。当多台服务器的配置统一集中存储在某处(例如版本控制仓库)时,这有助于彻底消除歧义(将数据库配置文件纳入版本控制仓库管理是另一个值得践行的良好运维习惯)。