19.11. 客户端连接默认参数

19.11. 客户端连接默认参数
上一页	上一级	Chapter 19. 服务器配置	首页	下一页

19.11. 客户端连接默认参数 #

19.11.1. 语句执行行为控制
19.11.2. 区域与显示格式化
19.11.3. 共享库预加载设置
19.11.4. 其他连接默认值

19.11.1. 语句执行行为控制 #

client_min_messages (enum) #

控制将哪些消息严重级别发送给客户端。合法取值包括 DEBUG5、DEBUG4、DEBUG3、DEBUG2、DEBUG1、LOG、NOTICE、WARNING 以及 ERROR。每个级别均包含其后的所有级别。排列越靠后，发送给客户端的消息越少。默认值为 NOTICE。请注意，LOG 在此处的优先级与 log_min_messages 中的排序不同。

INFO 级别的消息始终会直接发送给客户端。

search_path (string) #

当通过未指定模式限定词的简单对象名称引用某个对象（表、数据类型、函数等）时，该变量指定搜索查找模式的优先级顺序。当不同模式中存在同名对象时，优先使用在搜索路径中首先匹配到的对象。若某个对象所在模式不在搜索路径中，则必须使用带点号的限定名称（schema.object）进行显式引用。

search_path 的取值必须是由逗号分隔的模式名称列表。任何不存在的模式名，或者当前用户对其缺乏 USAGE 使用权限的模式名，都会被系统静默忽略。

如果列表中的某一项是特殊名称 $user，且存在与 CURRENT_USER 返回的用户名同名的模式且当前用户拥有该模式的 USAGE 权限，则会将其动态替换为该用户专属同名模式（若不存在，则静默忽略 $user）。

系统目录模式 pg_catalog 无论是否显式出现在搜索路径中，始终都会被搜索。如果在路径中显式提及，它会按照指定的顺序位置被搜索；若未在路径中提及，系统会在搜索任何其他模式之前最优先搜索 pg_catalog。

类似地，当前会话的临时表模式 pg_temp_nnn 只要存在就始终会被自动搜索。可以使用别名 pg_temp 将其显式写在搜索路径中。若未在路径中列出，它会最优先被搜索（甚至先于 pg_catalog）。不过，临时模式仅用于查找关系（表、视图、序列等）和数据类型名称，绝不用于查找函数或运算符名称。

在创建数据库对象且未显式指定目标模式时，该对象将被创建在 search_path 中列出的第一个有效模式中。如果搜索路径为空，系统将直接报错。

该参数的默认值为 "$user", public。这种设置既支持数据库的全局共享使用（所有用户共享使用 public 模式），也支持用户拥有独立的私有同名模式，或二者的混合形态。通过在全局或单用户级别修改默认搜索路径，可以达成预期的隔离效果。

有关模式管理的更多信息，请参阅 Section 5.10。需要特别指出的是，默认配置仅适用于单用户环境或少数互相信任的用户场景。

当前实际生效的搜索路径可以通过 SQL 函数 current_schemas 进行查看（参见 Section 9.27）。这与直接查看 search_path 变量略有不同，因为 current_schemas 展示的是变量中各模式名称最终物理匹配解析后的实际结果列表。

row_security (boolean) #

这个变量控制是否抛出错误以代替应用行安全策略。设置为 on 时，策略正常应用。设置为 off 时，否则会应用至少一个策略的查询将失败。默认值为 on。在受限的行可见性可能导致错误结果的场合改为 off；例如， pg_dump 默认就做这样的更改。这个变量对绕过所有行安全策略的角色没有效果，即超级用户和具有 BYPASSRLS 属性的角色。

有关行安全策略的更多信息，请参见 CREATE POLICY。

default_table_access_method (string) #

这个参数指定在创建表或物化视图时、当 CREATE 命令未显式指定访问方法时，或者在使用不允许指定表访问方法的 SELECT ... INTO 时，所要使用的默认表访问方法。默认值为 heap。

default_tablespace (string) #

该变量指定在执行 CREATE 命令未显式指定表空间时，创建数据库对象（表和索引）所采用的默认表空间。

取值为表空间名称，或指定为空字符串以使用当前数据库的默认表空间。若指定的值与任何现有表空间均不匹配，PostgreSQL 会自动回退使用当前数据库的默认表空间。若指定了非默认表空间，用户必须对该表空间拥有 CREATE 权限，否则对象创建将报错失败。

该变量不用于临时表；对于临时表，系统改用 temp_tablespaces。

该变量在创建数据库时同样不适用。默认情况下，新创建的数据库会继承其所克隆的模板数据库的表空间设置。

如果在创建分区表时将此参数设置为非空值，则该分区表的表空间将被设置为该值，并作为未来新增创建分区的默认表空间，即使后续 default_tablespace 的全局值发生了更改。

有关表空间的更多信息，请参见 Section 22.6。

default_toast_compression (enum) #

这个变量为可压缩列的值设置默认的 TOAST 压缩方法。（对于单个列，可以通过在 CREATE TABLE 或 ALTER TABLE 中设置 COMPRESSION 列选项来覆盖它。）受支持的压缩方法是 pglz 和（如果 PostgreSQL 编译时带有 --with-lz4） lz4。默认值为 pglz。

temp_tablespaces (string) #

这个变量指定在 CREATE 命令未显式指定表空间时，用于创建临时对象（临时表以及临时表上的索引）的表空间。用于排序大数据集等目的的临时文件也在这些表空间中创建。

该值是一个表空间名字的列表。当列表中有多于一个名字时，每次要创建一个临时对象时， PostgreSQL 都会随机选择列表中的一个成员；不过在一个事务内，相继创建的临时对象会被放置到列表中相继的表空间中。如果列表中被选中的元素是空字符串， PostgreSQL 将自动改用当前数据库的默认表空间。

当以交互方式设置 temp_tablespaces 时，指定一个不存在的表空间是一个错误，指定一个用户没有 CREATE 特权的表空间同样如此。不过，在使用先前设置的值时，不存在的表空间会被忽略，用户缺少 CREATE 特权的表空间同样如此。特别地，这条规则适用于使用在 postgresql.conf 中设置的值时。

默认值为空字符串，这会导致所有临时对象均创建在当前数据库的默认表空间中。

Note

两阶段预备事务（Prepared Transactions）不受此超时的限制。

lock_timeout (integer) #

中止在尝试获取表、索引、行或其他数据库对象的锁时等待超过指定时长的任何语句。该时间限制独立应用于每一次获取锁的尝试。该限制既适用于显式加锁请求（如 LOCK TABLE 或不带 NOWAIT 的 SELECT FOR UPDATE），也适用于隐式获取的锁。若不带单位按毫秒计算。值为 0（默认值）表示禁用此锁等待超时。

与 statement_timeout 不同，该超时仅在排队等待获取锁时才会发生。请注意，若 statement_timeout 非零，将 lock_timeout 设置为相同或更大的值是没有意义的，因为语句超时始终会先于其触发。若 log_min_error_statement 设置为 ERROR 或更低，超时的语句将被记录到日志中。

不建议在全局 postgresql.conf 中设置 lock_timeout，因为这会波及所有会话。

idle_in_transaction_session_timeout (integer) #

终止在打开的事务内部处于空闲状态（即等待客户端提交下一条查询）超过指定时长的任何会话（idle in transaction）。若指定该值时不带单位，则按毫秒计算。值为 0（默认值）表示禁用该超时。

该选项可用于确保空闲会话不会在事务中无休止地持有物理锁或表锁。即使未持有重要行锁，一个未提交的空闲事务也会死死卡住系统的 xmin 事务视界，阻止 vacuum 及时清理回收对其可能可见的死元组，从而直接加剧全表的严重膨胀。详见 Section 24.1。

idle_session_timeout (integer) #

终止在未开启事务的状态下处于空闲等待状态超过指定时长的任何会话。若不带单位按毫秒计算。值为 0（默认值）表示禁用该空闲连接超时。

与未提交事务的情况不同，不处于事务中的空闲会话不会阻塞 vacuum 或持有关键锁，因而对服务端的开销很小，其开启的紧迫性显著低于 idle_in_transaction_session_timeout。

在通过数据库连接池软件（如 PgBouncer）或其他中间件代理建立的连接上强制实施此超时需格外谨慎，因为中间件层可能无法妥善处理连接被后端主动断开的异常。通常仅为终端交互式人机会话或针对特定用户启用此超时更为合适。

bytea_output (enum) #

设置 bytea 类型值的输出格式。有效值是 hex（默认值）和 escape（传统的 PostgreSQL 格式）。更多信息请参见 Section 8.4。无论这个设置如何，bytea 类型在输入时总是接受两种格式。

xmlbinary (enum) #

设置二进制值在 XML 中的编码方式。这适用于例如当 bytea 值通过 xmlelement 或 xmlforest 函数被转换为 XML 时。可能的值是 base64 和 hex，两者都在 XML Schema 标准中有定义。默认值为 base64。有关 XML 相关函数的更多信息，请参见 Section 9.15。

这里实际的选择主要取决于偏好，只受客户端应用程序中可能存在的限制约束。两种方法都支持所有可能的值，虽然 hex 编码会比 base64 编码稍大一些。

xmloption (enum) #

设置在 XML 与字符串值之间转换时隐式使用 DOCUMENT 还是 CONTENT。相关描述请参见 Section 8.13。有效值是 DOCUMENT 和 CONTENT。默认值为 CONTENT。

按照 SQL 标准，设置这个选项的命令是

SET XML OPTION { DOCUMENT | CONTENT };

这种语法在 PostgreSQL 中同样可用。

gin_pending_list_limit (integer) #

设置 GIN 索引待处理列表的最大尺寸，该列表在 fastupdate 被启用时使用。如果列表增长得比这个最大尺寸还大，它会通过把其中的条目批量移入索引的主 GIN 数据结构来清理。如果这个值没有指定单位，则以千字节为单位。默认值为四兆字节（4MB）。通过更改索引存储参数可以为单个 GIN 索引覆盖这个设置。更多信息请参见 Section 65.4.4.1 和 Section 65.4.5。

createrole_self_grant (string) #

如果一个拥有 CREATEROLE 但没有 SUPERUSER 的用户创建一个角色，并且这个参数被设置为非空值，那么新建的角色将按照指定的选项被授予创建该角色的用户。该值必须是 set、 inherit，或以逗号分隔的这两者列表。默认值为空字符串，它禁用该特性。

这个选项的目的是允许非超级用户的 CREATEROLE 用户自动继承任何被创建的用户，或自动获得对它们 SET ROLE 的能力。由于 CREATEROLE 用户总是被隐式授予所创建角色的 ADMIN OPTION，该用户始终可以执行一条 GRANT 语句来达到与这个设置相同的效果。不过，从易用性角度出发，让授予自动发生会很方便。超级用户自动继承每个角色的特权，并且总是可以对任何角色 SET ROLE；这个设置可用于为 CREATEROLE 用户产生的用户产生类似的行为。

event_triggers (boolean) #

允许临时禁用事件触发器的执行，以便排查和修复有缺陷的事件触发器。把它设置为 false 会禁用所有事件触发器。把值设置为 true 允许所有事件触发器触发，这是默认值。只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

restrict_nonsystem_relation_kind (string) #

设置禁止访问非系统关系的关系种类。该值采用以逗号分隔的关系种类列表的形式。目前，受支持的关系种类是 view 和 foreign-table。

19.11.2. 区域与显示格式化 #

DateStyle (string) #

设置日期和时间值的显示格式，以及解释有歧义的日期输入值的规则。出于历史原因，这个变量包含两个独立的组成部分：输出格式规范（ISO、 Postgres、SQL 或 German）以及年/月/日顺序的输入/输出规范（DMY、MDY 或 YMD）。它们可以被分开设置或一起设置。关键字 Euro 和 European 是 DMY 的同义词；关键字 US、 NonEuro 和 NonEuropean 是 MDY 的同义词。更多信息请参见 Section 8.5。内置默认值为 ISO, MDY，但 initdb 将用一个与所选 lc_time 区域设置行为相应的设置来初始化配置文件。

IntervalStyle (enum) #

设置 interval 值的显示格式。值 sql_standard 将产生与 SQL 标准 interval 字面量相匹配的输出。值 postgres（默认值）将产生与 PostgreSQL 8.4 之前发行版在 DateStyle 参数被设置为 ISO 时相匹配的输出。值 postgres_verbose 将产生与 PostgreSQL 8.4 之前发行版在 DateStyle 参数被设置为非 ISO 输出时相匹配的输出。值 iso_8601 将产生与 ISO 8601 第 4.4.3.2 节中定义的时间间隔 “带指示符的格式”相匹配的输出。

IntervalStyle 参数还影响对有歧义的 interval 输入的解释。更多信息请参见 Section 8.5.4。

TimeZone (string) #

设置用于解释与格式化呈现日期时间戳的会话时区。内置默认值为 GMT，但它通常会在 postgresql.conf 中被覆盖；initdb 会在那里安装一个与其系统环境相应的设置。更多信息请参见 Section 8.5.3。

timezone_abbreviations (string) #

设置服务器为日期时间输入接受的其他时区缩写集合（在当前 TimeZone 设置定义的缩写之外）。默认值为 'Default'，它是一个在世界上大多数地区都能工作的集合；另外还有 'Australia' 和 'India'，其他集合也可以为特定安装定义。更多信息请参见 Section B.4。

extra_float_digits (integer) #

这个参数调整浮点值（包括 float4、 float8 和几何数据类型）文本输出所用的位数。

如果值为 1（默认值）或更大，浮点值将以最短精确格式输出；参见 Section 8.1.3。实际产生的位数只取决于被输出的值，与这个参数的值无关。 float8 值最多需要 17 位， float4 值最多需要 9 位。这种格式既快速又精确，在正确读取时能精确地保留原始的二进制浮点值。出于历史兼容性，允许最大到 3 的值。

如果值为零或负数，则输出会被舍入到给定的小数精度。使用的精度是该类型的标准位数（适当地为 FLT_DIG 或 DBL_DIG），再按照这个参数的值进行缩减。（例如，指定 -1 将导致 float4 值被输出为舍入到 5 个有效数字， float8 值被舍入到 14 位。）这种格式较慢，并且不保留二进制浮点值的全部位，但可能更便于人类阅读。

Note

这个参数的含义和默认值在 PostgreSQL 12 中发生了变化；进一步的讨论请参见 Section 8.1.3。

client_encoding (string) #

设置客户端字符集编码（如 UTF8、GBK 等）。默认使用数据库编码。 PostgreSQL 服务器支持的字符集在 Section 23.3.1 中描述。

lc_messages (string) #

设置显示消息所用的语言。可接受的值取决于系统；更多信息请参见 Section 23.1。如果这个变量被设置为空字符串（这是默认值），则该值将以系统相关的方式从服务器的执行环境中继承。

在某些系统上，这个区域设置类别不存在。设置这个变量仍然可以工作，但不会有任何效果。此外，也有可能不存在所需语言的翻译消息。在这种情况下你将继续看到英文消息。

只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

lc_monetary (string) #

设置用于格式化货币金额的区域设置，例如使用 to_char 函数族时。可接受的值取决于系统；更多信息请参见 Section 23.1。如果这个变量被设置为空字符串（这是默认值），则该值将以系统相关的方式从服务器的执行环境中继承。

lc_numeric (string) #

设置用于格式化数字的区域设置，例如使用 to_char 函数族时。可接受的值取决于系统；更多信息请参见 Section 23.1。如果这个变量被设置为空字符串（这是默认值），则该值将以系统相关的方式从服务器的执行环境中继承。

lc_time (string) #

设置用于格式化日期和时间的区域设置，例如使用 to_char 函数族时。可接受的值取决于系统；更多信息请参见 Section 23.1。如果这个变量被设置为空字符串（这是默认值），则该值将以系统相关的方式从服务器的执行环境中继承。

icu_validation_level (enum) #

当遇到 ICU 区域设置验证问题时，控制用于报告该问题的消息级别。有效值是 DISABLED、DEBUG5、 DEBUG4、DEBUG3、 DEBUG2、DEBUG1、 INFO、NOTICE、 WARNING、ERROR 和 LOG。

如果设置为 DISABLED，则完全不报告验证问题。否则以给定的消息级别报告问题。默认值为 WARNING。

default_text_search_config (string) #

为那些没有用显式参数指定配置的文本搜索函数变体选择要使用的文本搜索配置。更多信息请参见 Chapter 12。内置默认值为 pg_catalog.simple，但如果能够找到与所选 lc_ctype 区域设置匹配的配置， initdb 将用一个与之相应的设置来初始化配置文件。

19.11.3. 共享库预加载设置 #

有多种设置可用于把共享库预加载到服务器中，以加载额外的功能或获得性能收益。例如，设置 '$libdir/mylib' 会导致从安装的标准库目录预加载 mylib.so （或在某些平台上为 mylib.sl）。这些设置之间的区别在于它们何时生效，以及更改它们需要什么特权。

PostgreSQL 的过程语言库可以用这种方式预加载，通常通过 '$libdir/plXXX' 语法，其中 XXX 是 pgsql、perl、 tcl 或 python。

只有专门设计用于 PostgreSQL 的共享库才能以这种方式加载。每个 PostgreSQL 支持的库都有一个 “魔法块”，会被检查以保证兼容性。因此，非 PostgreSQL 的库无法以这种方式加载。你或许可以使用 LD_PRELOAD 之类的操作系统设施来做到这一点。

一般而言，加载某个特定模块的推荐方式，请参见该模块的文档。

local_preload_libraries (string) #

这个变量指定一个或多个要在连接开始时预加载的共享库。它包含一个以逗号分隔的库名列表，每个名字按照 LOAD 命令的方式解释。条目之间的空白会被忽略；如果需要在库名中包含空白或逗号，请用双引号把库名括起来。参数值只在连接开始时生效。之后的更改没有效果。如果找不到指定的库，连接尝试将失败。

这个选项可以由任何用户设置。正因如此，能够加载的库被限制为出现在安装的标准库目录的 plugins 子目录中的那些库。（确保只有“安全”的库被安装到那里，是数据库管理者的责任。） local_preload_libraries 中的条目可以显式指定这个目录，例如 $libdir/plugins/mylib，或者只指定库名 — mylib 会与 $libdir/plugins/mylib 具有相同的效果。

这个特性的意图是让非特权用户能够把调试或性能测量库加载到特定的会话中，而无需显式的 LOAD 命令。为此，典型的做法是在客户端用 PGOPTIONS 环境变量或使用 ALTER ROLE SET 来设置这个参数。

然而，除非一个模块是专门为非超级用户以这种方式使用而设计的，这通常不是应该使用的正确设置。请改用 session_preload_libraries。

session_preload_libraries (string) #

这个变量指定一个或多个要在连接开始时预加载的共享库。它包含一个以逗号分隔的库名列表，每个名字按照 LOAD 命令的方式解释。条目之间的空白会被忽略；如果需要在库名中包含空白或逗号，请用双引号把库名括起来。参数值只在连接开始时生效。之后的更改没有效果。如果找不到指定的库，连接尝试将失败。只有超级用户和具有相应 SET 权限的用户可以更改这个设置。

这个特性的意图是允许把调试或性能测量库加载到特定的会话中，而无需给出显式的 LOAD 命令。例如，通过用 ALTER ROLE SET 设置这个参数，可以让 auto_explain 对某个给定用户名下的所有会话启用。此外，这个参数可以在不重启服务器的情况下更改（但更改只在新会话启动时生效），因此即使模块应当应用于所有会话，用这种方式添加新模块也更方便。

与 shared_preload_libraries 不同，在会话开始时加载库与在首次使用时加载库相比，并没有大的性能优势。不过，当使用连接池时会有一些优势。

shared_preload_libraries (string) #

这个变量指定一个或多个要在服务器启动时预加载的共享库。它包含一个以逗号分隔的库名列表，每个名字按照 LOAD 命令的方式解释。条目之间的空白会被忽略；如果需要在库名中包含空白或逗号，请用双引号把库名括起来。这个参数只能在服务器启动时设置。如果找不到指定的库，服务器将无法启动。

某些库需要执行只能在 postmaster 启动时发生的特定操作，例如分配共享内存、保留轻量级锁或启动后台工作进程。这些库必须通过这个参数在服务器启动时加载。详情请参见每个库的文档。

其他库也可以被预加载。通过预加载一个共享库，可以避免该库首次使用时的库启动时间。然而，即使某个进程从不使用该库，启动每个新服务器进程的时间也可能略微增加。因此，只建议对大多数会话都会用到的库使用这个参数。另外，更改这个参数需要重启服务器，因此对于比如说短期调试任务，这不是应当使用的正确设置。那种场景请改用 session_preload_libraries。

Note

在 Windows 主机上，在服务器启动时预加载库并不能减少启动每个新服务器进程所需的时间；每个服务器进程都会重新加载所有预加载库。不过，对于需要在 postmaster 启动时执行操作的库， shared_preload_libraries 在 Windows 主机上仍然有用。

jit_provider (string) #

这个变量是要使用的 JIT 提供者库的名字（参见 Section 30.4.2）。默认值为 llvmjit。这个参数只能在服务器启动时设置。

如果被设置为一个不存在的库， JIT 将不可用，但不会抛出错误。这允许把 JIT 支持与主 PostgreSQL 包分开安装。

19.11.4. 其他连接默认值 #

dynamic_library_path (string) #

如果需要打开一个动态可加载模块，而 CREATE FUNCTION 或 LOAD 命令中指定的文件名不带目录部分（即名字中不含斜杠），系统将在这个路径中搜索所需的文件。

dynamic_library_path 的值必须是一个以冒号（Windows 上为分号）分隔的绝对目录路径列表。如果列表元素以特殊字符串 $libdir 开头，则编译进 PostgreSQL 包的库目录会被替换进去；这是标准 PostgreSQL 发行版提供的模块被安装的位置。（使用 pg_config --pkglibdir 可以查出这个目录的名字。）例如：

dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'

或者在 Windows 环境中：

dynamic_library_path = 'C:	ools\postgresql;H:\my_project\lib;$libdir'

这个参数的默认值是 '$libdir'。如果该值被设置为空字符串，则自动路径搜索被关闭。

这个参数可以在运行时由超级用户和具有相应 SET 特权的用户更改，但那样做的设置只会持续到客户端连接结束，因此这种方法应当保留给开发用途。设置这个参数的推荐方式是在 postgresql.conf 配置文件中。

extension_control_path (string) #

用于搜索扩展（具体是扩展控制文件（name.control））的路径。其余的扩展脚本和次级控制文件随后会从找到主控制文件的同一目录加载。详情请参见 Section 36.17.1。

extension_control_path 的值必须是一个以冒号（Windows 上为分号）分隔的绝对目录路径列表。如果列表元素以特殊字符串 $system 开头，则编译进 PostgreSQL 包的扩展目录会被替换进去；这是标准 PostgreSQL 发行版提供的扩展被安装的位置。（使用 pg_config --sharedir 可以查出这个目录的名字。）例如：

extension_control_path = '/usr/local/share/postgresql:/home/my_project/share:$system'

或者在 Windows 环境中：

extension_control_path = 'C:	ools\postgresql;H:\my_project\share;$system'

注意，所指定的路径元素应当带有一个 extension 子目录，其中包含 .control 和 .sql 文件； extension 后缀会自动追加到每个路径元素上。

这个参数的默认值是 '$system'。如果该值被设置为空字符串，也会假定默认值 '$system'。

如果同名的扩展出现在配置路径的多个目录中，只会使用在路径中最先找到的那个实例。

注意，如果你设置这个参数以便从非标准位置加载扩展，你很可能还需要把 dynamic_library_path 设置为对应的位置，例如，

extension_control_path = '/usr/local/share/postgresql:$system'
dynamic_library_path = '/usr/local/lib/postgresql:$libdir'

gin_fuzzy_search_limit (integer) #

GIN 索引扫描返回的集合尺寸的软上限。更多信息请参见 Section 65.4.5。

上一页	上一级	下一页
19.10. 清理与维护参数	首页	19.12. 锁管理与死锁超时设置