2024年9月26日: PostgreSQL 17 发布!
支持的版本:当前 (17) / 16 / 15 / 14 / 13 / 12
开发版本:开发版
不支持的版本:11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2

19.1. 设置参数 #

19.1.1. 参数名称和值 #

所有参数名称不区分大小写。每个参数都采用五种类型之一的值:布尔型、字符串型、整型、浮点型或枚举型 (enum)。类型决定了设置参数的语法。

  • 布尔型: 值可以写成 onofftruefalseyesno10(所有不区分大小写)或这些值中任何不含歧义的前缀。

  • 字符串型: 通常,将值用单引号括起来,在值中将任何单引号加倍。如果值是简单的数字或标识符,则通常可以省略引号。(与 SQL 关键字匹配的值在某些上下文中需要加引号。)

  • 数值型(整型和浮点型): 数值参数可以用通常的整型和浮点型格式指定;如果参数为整型,则小数值将四舍五入到最接近的整数。整型参数还接受十六进制输入(以 0x 开头)和八进制输入(以 0 开头),但这些格式不能有小数部分。不要使用千位分隔符。除了十六进制输入之外,不需要使用引号。

  • 带单位的数值型: 一些数值参数具有隐式单位,因为它们描述的是内存或时间的数量。单位可能是字节、千字节、块(通常为 8 千字节)、毫秒、秒或分钟。这些设置中的一个未加修饰的数值将使用该设置的默认单位,这可以通过 pg_settings.unit 了解。为了方便起见,设置可以明确指定单位,例如时间值 '120 ms',它们将转换为参数的实际单位。请注意,要使用此功能,必须将值写成字符串(带引号)。单位名称区分大小写,数值和单位之间可以有空格。

    • 有效的内存单位是 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,该文件通常保存在数据目录中。在初始化数据库集群目录时,会安装一个默认副本。此文件可能的样子示例如下:

# This is a comment
log_connections = yes
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 信号未产生预期效果时诊断问题。

19.1.3. 通过 SQL 交互参数 #

PostgreSQL 提供三个 SQL 命令来建立配置默认值。前面提到的 ALTER SYSTEM 命令提供了一种可通过 SQL 访问的更改全局默认值的方法;它在功能上等同于编辑 postgresql.conf。此外,还有两个命令允许在每个数据库或每个角色的基础上设置默认值。

  • ALTER DATABASE 命令允许在每个数据库的基础上覆盖全局设置。

  • ALTER ROLE 命令允许使用用户特定的值覆盖全局和每个数据库的设置。

使用 ALTER DATABASEALTER ROLE 设置的值仅在启动新的数据库会话时应用。它们会覆盖从配置文件或服务器命令行获得的值,并构成会话其余部分的默认值。请注意,某些设置在服务器启动后无法更改,因此无法使用这些命令(或下面列出的命令)进行设置。

客户端连接到数据库后,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';
    

19.1.4. 通过 Shell 进行参数交互 #

除了设置全局默认值或在数据库或角色级别附加覆盖之外,您还可以通过 Shell 工具将设置传递给 PostgreSQL。服务器和 libpq 客户端库都通过 Shell 接受参数值。

  • 在服务器启动期间,可以通过 postgres 命令的 -c name=value 命令行参数或其等效的 --name=value 变体将参数设置传递给该命令。例如,

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

    以这种方式提供的设置会覆盖通过 postgresql.confALTER 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 '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 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

这种安排为每个配置文件变体提供了唯一的名称。当多台服务器的配置都存储在一个位置(例如版本控制存储库)中时,这有助于消除歧义。(将数据库配置文件存储在版本控制下是另一个需要考虑的良好实践。)

提交更正

如果您在文档中看到任何不正确的内容,与您对特定功能的体验不符,或者需要进一步澄清,请使用 此表单 报告文档问题。