所有参数名称均不区分大小写。每个参数接受五种类型之一的值:布尔值、字符串、整数、浮点数或枚举值(enum)。类型决定了设置参数的语法。
布尔值: 值可以写成 on
、off
、true
、false
、yes
、no
、1
、0
(均不区分大小写)或其中任何一个的不歧义前缀。
字符串: 通常,将值放在单引号中,并将值内的任何单引号加倍。如果值是简单的数字或标识符,则通常可以省略引号。(在某些上下文中,匹配 SQL 关键字的值需要加引号。)
数字(整数和浮点数): 数字参数可以用常规的整数和浮点数格式指定;如果参数是整数类型,则小数部分会四舍五入到最接近的整数。整数参数还接受十六进制输入(以 0x
开头)和八进制输入(以 0
开头),但这些格式不能包含小数。不要使用千位分隔符。除非是十六进制输入,否则不需要加引号。
带单位的数字: 某些数字参数具有隐式单位,因为它们描述的是内存或时间量。单位可能是字节、千字节、块(通常是八千字节)、毫秒、秒或分钟。这些设置的无单位数值将使用该设置的默认单位,该单位可从 pg_settings
.unit
中获悉。为了方便起见,可以为设置指定显式单位,例如时间值的 '120 ms'
,它们将被转换为参数的实际单位。请注意,要使用此功能,该值必须以字符串形式(带引号)写入。单位名称区分大小写,数字值和单位之间可以有空格。
有效的内存单位是 B
(字节)、kB
(千字节)、MB
(兆字节)、GB
(吉字节)和 TB
(太字节)。内存单位的乘数是 1024,而不是 1000。
有效的 time 单位是 us
(微秒)、ms
(毫秒)、s
(秒)、min
(分钟)、h
(小时)和 d
(天)。
如果指定了带单位的小数值,它将被四舍五入到下一个更小单位的倍数(如果存在)。例如,30.1 GB
将被转换为 30822 MB
,而不是 32319628902 B
。如果参数是整数类型,则在任何单位转换后会进行最终的整数四舍五入。
枚举值: 枚举类型参数的写法与字符串参数相同,但仅限于一组有限的值。此类参数允许的值可从 pg_settings
.enumvals
中查找。枚举参数值不区分大小写。
设置这些参数最根本的方法是编辑 postgresql.conf
文件,该文件通常保存在数据目录中。在初始化数据库集群目录时,会安装一个默认副本。该文件可能看起来像这样:
# This is a comment 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 数据目录还包含一个 postgresql.auto.conf
文件,该文件的格式与 postgresql.conf
相同,但旨在自动编辑,而非手动编辑。此文件保存通过 ALTER SYSTEM
命令提供的设置。此文件在 postgresql.conf
重新读取时也会被读取,并且其设置会以相同方式生效。 postgresql.auto.conf
中的设置会覆盖 postgresql.conf
中的设置。
外部工具也可以修改 postgresql.auto.conf
。不建议在服务器运行时这样做,除非 allow_alter_system 设置为 off
,因为并发的 ALTER SYSTEM
命令可能会覆盖此类更改。这些工具可能只是在末尾追加新设置,或者它们可能选择删除重复设置和/或注释(正如 ALTER SYSTEM
会做的那样)。
系统视图 pg_file_settings
有助于预先测试对配置文件所做的更改,或者在 SIGHUP 信号未达到预期效果时诊断问题。
PostgreSQL 提供了三个 SQL 命令来建立配置默认值。已经提到的 ALTER SYSTEM
命令提供了可通过 SQL 访问的修改全局默认值的方法;它在功能上等同于编辑 postgresql.conf
。此外,还有两个命令允许按数据库或按角色设置默认值。
ALTER DATABASE
命令允许按数据库覆盖全局设置。
ALTER ROLE
命令允许使用用户特定值覆盖全局设置和按数据库的设置。
使用 ALTER DATABASE
和 ALTER ROLE
设置的值仅在启动新的数据库会话时应用。它们会覆盖从配置文件或服务器命令行获得的值,并构成该会话其余部分Defaults。请注意,某些设置在服务器启动后无法更改,因此无法使用这些命令(或下面的命令)进行设置。
一旦客户端连接到数据库,PostgreSQL 就提供了另外两个 SQL 命令(以及等效函数)来与会话本地的配置设置进行交互。
SHOW
命令允许检查任何参数的当前值。对应的 SQL 函数是 current_setting(setting_name text)
(参见 第 9.28.1 节)。
SET
命令允许修改那些可以设置为会话本地的参数的当前值;它对其他会话没有影响。许多参数可以由任何用户以这种方式设置,但某些参数只能由超级用户和已授予该参数 SET
权限的用户设置。对应的 SQL 函数是 set_config(setting_name, new_value, is_local)
(参见 第 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';
除了设置全局默认值或在数据库或角色级别附加覆盖项之外,您还可以通过 shell 工具将设置传递给 PostgreSQL。服务器和 libpq 客户端库都接受通过 shell 传递的参数值。
在服务器启动期间,可以通过 postgres
命令的 -c name=value
命令行参数,或其等效的 --name=value
变体来传递参数设置。例如:
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 命令的情况下修改会话设置。
PostgreSQL 提供了多项功能,用于将复杂的 postgresql.conf
文件分解为子文件。当管理具有相关但又不完全相同的配置的多个服务器时,这些功能尤其有用。
除了单个参数设置外,postgresql.conf
文件还可以包含include 指令,这些指令指定要读取并处理的另一个文件,就好像它在此处插入到配置文件中一样。此功能允许将配置文件物理上分成多个部分。Include 指令看起来很简单:
include 'filename'
如果文件名不是绝对路径,则它相对于包含引用配置文件的目录。包含可以嵌套。
还有一个 include_if_exists
指令,其作用与 include
指令相同,只是在引用的文件不存在或无法读取时除外。常规的 include
会将其视为错误条件,但 include_if_exists
仅记录一条消息并继续处理引用配置文件。
postgresql.conf
文件还可以包含 include_dir
指令,这些指令指定要包含的整个配置文件目录。它们看起来像:
include_dir 'directory'
非绝对目录名称相对于包含引用配置文件的目录。在指定目录中,只有以 .conf
后缀结尾的非目录文件才会被包含。以 .
字符开头的文件名也会被忽略,以防出错(因为在某些平台上这些文件是隐藏的)。包含目录中的多个文件按文件名顺序处理(根据 C 语言 locale 规则,即数字在前,字母在后;大写字母在前,小写字母在后)。
包含文件或目录可用于逻辑上分隔数据库配置的一部分,而不是使用单个大型 postgresql.conf
文件。考虑一个公司有两个数据库服务器,它们的内存量不同。配置中很可能有一些元素是它们共享的,例如用于日志记录。但服务器上的内存相关参数在这两者之间会有所不同。还可能存在服务器特定的自定义设置。管理这种情况的一种方法是将您站点的自定义配置更改分解为三个文件。您可以将以下内容添加到 postgresql.conf
文件的末尾以包含它们:
include 'shared.conf' include 'memory.conf' include 'server.conf'
所有系统都将拥有相同的 shared.conf
。每个具有特定内存量的服务器可以共享相同的 memory.conf
;您可能有一个用于所有具有 8GB RAM 的服务器,另一个用于 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
这种安排为每个配置文件变体提供了一个唯一的名称。这可以帮助消除当多个服务器的配置全部存储在一个位置(例如版本控制存储库)时的歧义。(将数据库配置文件存储在版本控制下是另一个值得考虑的良好实践。)
如果您在文档中发现任何不正确之处、与您对特定功能的实际体验不符或需要进一步澄清的内容,请使用此表格报告文档问题。