pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。
百科 / 连接参数
libpq 连接关键字、环境变量、默认值与优先级。
当前查看 PostgreSQL 18。
共 55 个条目，PostgreSQL 18 收录 51 个。
将 GSS 凭据转发（委派）给服务器。默认值为 0 ，表示不向服务器转发凭据。将其设置为 1 时，会在可能的情况下转发凭据。
这个选项确定是否以及以何种优先级与服务器协商安全的 GSS TCP/IP 连接。有三种模式： disable 仅尝试未经 GSSAPI 加密的连接 prefer （默认） 如果存在 GSSAPI 凭据（即在凭据缓存中），首先尝试 GSSAPI 加密连接；如果失败或没有凭据，则尝试未经 GSSAPI 加密的连接。这是在编译 PostgreSQL 时使用 GSSAPI 支持时的默认设置。 require 仅尝试 GSSAPI 加密连接 gssencmode 在 Unix 域套接字通信中被忽略。如果…
用于 GSSAPI 认证的 GSS 库。目前，除了包含 GSSAPI 和 SSPI 支持的 Windows 构建之外，这将被忽略。在这种情况下，将其设置为 gssapi ，以使 libpq 使用 GSSAPI 库进行认证，而不是默认的 SSPI。
使用 GSSAPI 认证时所用的 Kerberos 服务名。这必须与服务器配置中指定的 Kerberos 认证服务名称匹配，才能成功进行认证。（另请参见 第 20.6 节 。）默认值通常为 postgres ，但在构建 PostgreSQL 时，可以通过 configure 的 --with-krb-srvnam 选项更改。在大多数环境中，通常不需要更改此参数。一些 Kerberos 实现可能需要不同的服务名称，例如 Microsoft Active Directory 需要服务名称为大写（ …
此选项已弃用，请改用 sslmode 设置。 如果设置为 1，则需要与服务器建立 SSL 连接（这相当于 sslmode require ）。 libpq 将拒绝连接，如果服务器不接受 SSL 连接。如果设置为 0（默认值）， libpq 将与服务器协商连接类型（相当于 sslmode prefer ）。此选项仅在 PostgreSQL 编译时启用了 SSL 支持的情况下可用。
这个参数指定连接允许的最大 SSL/TLS 协议版本。有效值为 TLSv1 、 TLSv1.1 、 TLSv1.2 和 TLSv1.3 。支持的协议取决于使用的 OpenSSL 版本，旧版本不支持最新的协议版本。如果未设置，则忽略此参数；如果后端定义了最大限制，连接将使用该限制。设置最大协议版本主要用于测试或者某些组件无法使用较新协议时。
这个参数指定连接允许的最低 SSL/TLS 协议版本。有效值为 TLSv1 、 TLSv1.1 、 TLSv1.2 和 TLSv1.3 。支持的协议取决于所使用的 OpenSSL 版本，旧版本不支持最现代的协议版本。如果未指定，默认值为 TLSv1.2 ，符合本文撰写时的行业最佳实践。
这个参数指定客户端 SSL 证书的文件名，替换默认的 ~/.postgresql/postgresql.crt 。如果没有建立 SSL 连接，则此参数将被忽略。
此选项决定是否可以向服务器发送客户端证书，以及服务器是否必须请求客户端证书。共有三种模式： disable 即使客户端有可用证书（默认位置或通过 sslcert 提供），也绝不发送客户端证书。 allow （默认） 如果服务器请求证书且客户端有证书可发，则可以发送证书。 require 服务器 必须 请求证书。如果客户端没有发送证书而服务器仍成功认证了客户端，则连接将失败。 注意 sslcertmode=require 不会增加额外的安全性，因为无法保证服务器一定正确验证了证书； Postgr…
如果设置为 1，通过 SSL 连接发送的数据将被压缩。如果设置为 0，将禁用压缩。默认值为 0。如果进行非 SSL 连接，则忽略此参数。 SSL 压缩现在被认为是不安全的，不再建议使用。 OpenSSL 1.1.0 默认禁用压缩，许多操作系统发行版也在之前的版本中禁用了压缩，因此如果服务器不接受压缩，将此参数设置为 on 将不会产生任何效果。 PostgreSQL 14 在后端完全禁用了压缩。 如果安全性不是主要考虑因素，压缩可以提高吞吐量，如果网络是瓶颈的话。如果 CPU 性能是限制因素，禁…
此参数指定 SSL 服务器证书吊销列表（CRL）的文件名。如果该文件存在，在验证服务器证书时，会拒绝其中列出的证书。如果既未设置 sslcrl ，也未设置 sslcrldir ，则采用 ~/.postgresql/root.crl 。
此参数指定 SSL 服务器证书吊销列表（CRL）的目录名。如果该目录存在，在验证服务器证书时，会拒绝该目录下文件中列出的证书。 目录需要使用 OpenSSL 命令 openssl rehash 或 c_rehash 进行准备。详细信息请参阅其文档。 sslcrl 和 sslcrldir 可以一起指定。
这个参数指定了用于客户端证书的密钥的位置。它可以指定一个文件名，该文件名将被用来替代默认的 ~/.postgresql/postgresql.key ，或者它可以指定一个从外部 “ 引擎 ” （引擎是 OpenSSL 可加载模块）获取的密钥。外部引擎的指定形式应包含一个由冒号分隔的引擎名称和一个引擎特定的密钥标识符。如果没有进行 SSL 连接，则此参数将被忽略。
这个参数指定 libpq 记录此 SSL 上下文所用密钥的位置。这对于调试 PostgreSQL 协议交互，或者借助 Wireshark 之类的网络检查工具分析客户端连接很有用。如果未建立 SSL 连接，或者使用的是 LibreSSL （其不支持密钥记录），则会忽略此参数。密钥将按 NSS 格式记录。 警告 密钥记录会在 keylog 文件中暴露潜在敏感信息。应当像处理 sslkey 文件一样谨慎处理 keylog 文件。
这个选项确定是否以及以何种优先级与服务器协商安全的 SSL TCP/IP 连接。有六种模式： disable 仅尝试非 SSL 连接 allow 首先尝试非 SSL 连接；如果失败，则尝试 SSL 连接 prefer （默认） 首先尝试 SSL 连接；如果失败，则尝试非 SSL 连接 require 仅尝试 SSL 连接。如果存在根 CA 文件，则验证证书的方式与指定了 verify-ca 时相同 verify-ca 仅尝试 SSL 连接，并验证服务器证书是否由受信任的证书颁发机构（ CA ）…
如果使用 SSL，此选项控制如何与服务器协商 SSL 加密。在默认的 postgres 模式下，客户端会先询问服务器是否支持 SSL；在 direct 模式下，客户端会在建立 TCP/IP 连接后直接开始标准 SSL 握手。传统的 PostgreSQL 协议协商能兼容更多不同的服务器配置；如果已知服务器支持直接 SSL 连接，则后一种方式可以减少一次往返，从而降低连接延迟，也允许使用与协议无关的 SSL 网络工具。直接 SSL 选项是在 PostgreSQL 17 中引入的。 postgres…
这个参数指定了在 sslkey 中指定的密钥的密码，允许客户端证书私钥在磁盘上以加密形式存储，即使交互式密码输入不可行。 当向 libpq 提供加密的客户端证书密钥时，将此参数指定为任意非空值，都将抑制 OpenSSL 默认发出的 Enter PEM pass phrase: 提示。 如果密钥未加密，则忽略此参数。该参数对由 OpenSSL 引擎指定的密钥没有影响，除非引擎使用 OpenSSL 密码回调机制进行提示。 没有与此选项等效的环境变量，也没有在 .pgpass 中查找它的功能。它可以…
此参数指定包含 SSL 证书颁发机构（ CA ）证书的文件名。如果文件存在，则会验证服务器证书是否由这些机构之一签名。默认值为 ~/.postgresql/root.crt 。 也可以指定特殊值 system ，此时会加载 SSL 实现提供的受信任 CA 根证书。这些根证书的确切位置因 SSL 实现和平台而异。对于 OpenSSL ，还可以通过 SSL_CERT_DIR 和 SSL_CERT_FILE 环境变量进一步修改这些位置。 注意 使用 sslrootcert=system 时，默认的 …
如果设置为 1（默认值），libpq 会在启用 SSL 的连接上设置 TLS 扩展 “ 服务器名称指示 ” （ SNI ）。通过将此参数设置为 0，可以关闭此功能。 支持 SSL 的代理可以利用服务器名称指示来路由连接，而无需解密 SSL 流。（注意，除非代理能够识别 PostgreSQL 协议握手，否则需要将 sslnegotiation 设为 direct 。）不过， SNI 会使目标主机名以明文形式出现在网络流量中，因此在某些情况下可能不希望使用它。
所选版本未收录此条目。
指定 application_name 配置参数的值。
这将为此连接设置 client_encoding 配置参数。除了对应服务器选项接受的值外，您还可以使用 auto 来从客户端的当前区域设置（Unix 系统上的 LC_CTYPE 环境变量）确定正确的编码。
指定 application_name 配置参数的后备值。如果没有通过连接参数或 PGAPPNAME 环境变量为 application_name 指定值，则将使用此值。在通用实用程序中指定后备名称很有用，该程序希望设置默认应用程序名称，但允许用户覆盖它。
这个参数指定要向服务器请求的协议版本。默认会使用 PostgreSQL 协议的 3.0 版本；但如果连接字符串指定了依赖更高协议版本的特性，则会使用 libpq 支持的最新版本。如果服务器不支持客户端请求的协议版本，连接会自动降级为服务器支持的较低次版本协议。连接尝试完成后，你可以使用 PQfullProtocolVersion 来确定最终协商得到的确切协议版本。 当前支持的值是 3.0 、 3.2 和 latest 。 latest 等价于正在使用的 libpq 版本所支持的最新协议版本，目…
这个参数指定该连接允许的最低协议版本。默认情况下，允许使用 libpq 所支持的任何 PostgreSQL 协议版本，目前即 3.0 。如果服务器不支持此协议版本或更高版本，则连接将被关闭。 当前支持的值是 3.0 、 3.2 和 latest 。 latest 等价于正在使用的 libpq 版本所支持的最新协议版本，目前即 3.2 。
指定连接开始时发送到服务器的命令行选项。例如，将其设置为 -c geqo=off 或 --geqo=off 会把会话的 geqo 参数值设为 off 。此字符串中的空格被视为分隔命令行参数，除非用反斜杠（ \ ）转义；写 \\ 表示字面上的反斜杠。有关可用选项的详细讨论，请参阅 第 19 章 。
这个选项确定连接是否应该使用复制协议而不是正常协议。这就是 PostgreSQL 复制连接以及诸如 pg_basebackup 这样的工具在内部使用的方式，但也可以被第三方应用程序使用。要了解复制协议的描述，请参考 第 54.4 节 。 支持以下值（不区分大小写）： true , on , yes , 1 连接进入物理复制模式。 database 连接进入逻辑复制模式，连接到 dbname 参数中指定的数据库。 false , off , no , 0 连接是常规连接，这是默认行为。 在物理或…
所选版本未收录此条目。
所选版本未收录此条目。
连接时的最长等待时间，以秒为单位（写成十进制整数，例如， 10 ）。零、负值或未指定表示无限等待。此超时时间分别适用于每个主机名或 IP 地址。例如，如果指定了两个主机且 connect_timeout 为 5，那么每个主机在 5 秒内未建立连接就会超时，因此等待连接的总时间可能长达 10 秒。
控制是否使用客户端 TCP keepalive。默认值为 1，表示开启；如果不需要 keepalive，可以将其设为 0，表示关闭。对于通过 Unix 域套接字建立的连接，此参数会被忽略。
控制在客户端与服务器之间的连接被视为中断之前，可以丢失多少个 TCP keepalive 消息。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接，或禁用 keepalive 时，此参数会被忽略。此参数仅在支持 TCP_KEEPCNT 或等效套接字选项的系统上受支持；在其他系统上无效。
控制在多久没有活动后，TCP 应向服务器发送 keepalive 消息，以秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接，或禁用 keepalive 时，此参数会被忽略。此参数仅在支持 TCP_KEEPIDLE 或等效套接字选项的系统以及 Windows 上受支持；在其他系统上无效。
控制未被服务器确认收到的 TCP keepalive 消息在多少秒后应被重传。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接，或禁用 keepalive 时，此参数会被忽略。此参数仅在支持 TCP_KEEPINTVL 或等效套接字选项的系统以及 Windows 上受支持；在其他系统上无效。
控制已发送的数据在连接被强制关闭之前最多可以保持未确认状态多长时间，以毫秒为单位。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接，此参数会被忽略。此参数仅在支持 TCP_USER_TIMEOUT 的系统上受支持；在其他系统上无效。
这个选项控制客户端对通道绑定的使用。设置为 require 表示连接必须使用通道绑定， prefer 表示客户端将在可用时选择通道绑定，而 disable 则阻止使用通道绑定。默认情况下，如果 PostgreSQL 是使用 SSL 支持编译的，则默认为 prefer ；否则默认为 disable 。 通道绑定是服务器向客户端证明自身身份的一种方法。它只在使用 PostgreSQL 11 或更高版本服务器、并采用 SCRAM 认证方法的 SSL 连接上受支持。
所选版本未收录此条目。
由授权服务器发放的 OAuth 2.0 客户端标识符。如果 PostgreSQL 服务器为该连接 请求 OAuth 令牌 ，并且没有安装 自定义 OAuth 钩子 来提供该令牌，那么就必须设置此参数；否则连接会失败。
与 OAuth 授权服务器通信时要使用的客户端密码（如果有）。该参数是否必需由 OAuth 提供者决定；公开客户端（public client）通常不使用密钥，而机密客户端（confidential client）通常会使用。
如果服务器为该连接请求 OAuth 令牌，要联系的受信任签发者的 HTTPS URL。所有 OAuth 连接都必须设置此参数；它应当与 服务器 HBA 配置 中的 issuer 设置完全一致。 作为标准认证握手的一部分， libpq 会向服务器请求一个 发现文档 ，也就是一个提供一组 OAuth 配置参数的 URL。服务器必须提供一个可由 oauth_issuer 的各组成部分直接构造出来的 URL，并且该值必须与发现文档自身声明的签发者标识符完全一致，否则连接会失败。这是为了防止 OAuth…
发送给授权服务器的访问请求的授权范围，以空格分隔的 OAuth 授权范围标识符列表指定（列表可以为空）。该参数是可选的，面向高级用法。 通常客户端会从 PostgreSQL 服务器获得合适的授权范围设置。如果使用这个参数，服务器请求的授权范围列表会被忽略。这可以防止不那么受信任的服务器向最终用户请求不恰当的访问授权范围。不过，如果客户端的授权范围设置不包含服务器所要求的授权范围，服务器很可能会拒绝已经签发的令牌，连接也会失败。 空授权范围列表的含义取决于提供者。OAuth 授权服务器可以选择签…
指定用于存储密码的文件名（参见 第 32.16 节 ）。默认为 ~/.pgpass ，或在 Microsoft Windows 上为 %APPDATA%\postgresql\pgpass.conf 。（如果此文件不存在，则不会报告错误。）
服务器要求密码认证时所使用的密码。
指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端，或者服务器没有完整完成认证握手，则连接将失败。也可以提供一个以逗号分隔的方法列表，此时服务器必须恰好使用其中一种方法，连接才会成功。默认情况下接受任意认证方法，并且服务器也可以完全跳过认证。 可以在方法名前加上 ! 前缀以表示否定，此时服务器 不得 尝试所列方法；除此之外，任何其他方法都可接受，并且服务器也可以完全不认证客户端。如果提供的是逗号分隔列表，服务器不得尝试其中 任何一个 被否定的方法。否定形式和非否定形…
这个参数指定了服务器的操作系统用户名，例如 requirepeer=postgres 。在建立 Unix 域套接字连接时，如果设置了这个参数，客户端会在连接开始时检查服务器进程是否在指定的用户下运行；如果不是，则连接会因错误而中止。这个参数可用于提供类似于在 TCP/IP 连接上使用 SSL 证书的服务器认证。（请注意，如果 Unix 域套接字位于 /tmp 或其他公共可写位置，任何用户都可以在那里启动一个服务器监听。使用这个参数来确保您连接到由受信任用户运行的服务器。）此选项仅在实现了 pe…
以 Base64 编码的 SCRAM 客户端密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见 第 F.38.1.10 节 。用户或客户端应用不应直接指定它。
以 Base64 编码的 SCRAM 服务器密钥。外部数据包装器或类似中间件可以利用它启用透传式 SCRAM 认证。一个实现示例见 第 F.38.1.10 节 。用户或客户端应用不应直接指定它。
建立连接所用的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。
数据库名称。默认为与用户名相同。在某些情况下，该值会被检查是否为扩展格式；有关更多详细信息，请参阅 第 32.1.1 节 。
要连接的主机名。 如果主机名看起来像绝对路径名，则指定的是 Unix 域通信，而非 TCP/IP 通信；此值是存放套接字文件的目录名。（在 Unix 上，绝对路径名以斜杠开头。在 Windows 上，也会识别以驱动器号开头的路径。）如果主机名以 @ 开头，则将其视为抽象命名空间中的 Unix 域套接字（目前在 Linux 和 Windows 上支持）。当未指定 host 或其值为空时，默认连接到 /tmp （或构建 PostgreSQL 时指定的套接字目录）中的 Unix 域套接字。 在 Wi…
要连接的主机的数字 IP 地址。这应该是标准的 IPv4 地址格式，例如， 172.28.40.9 。如果您的机器支持 IPv6，也可以使用这些地址。当为此参数指定非空字符串时，总是使用 TCP/IP 通信。如果未指定此参数，则会根据 host 的值查找相应的 IP 地址 — 或者，如果 host 指定了 IP 地址，则将直接使用该值。 使用 hostaddr 允许应用程序避免主机名查找，这在有时间限制的应用程序中可能很重要。但是，对于 GSSAPI 或 SSPI 认证方法以及 verify-…
控制客户端尝试连接可用主机和地址的顺序。一旦某次连接尝试成功，就不会再尝试其他主机和地址。该参数通常与多个主机名或返回多个 IP 地址的 DNS 记录一起使用。它还可以与 target_session_attrs 组合使用，例如只在备库之间进行负载均衡。连接一旦成功建立，随后在返回的连接上发出的所有查询都会发送到同一台服务器。目前有两种模式： disable （默认） 不在主机之间执行负载均衡。主机会按提供的顺序进行尝试，地址会按从 DNS 或 hosts 文件获得的顺序进行尝试。 rando…
连接到服务器主机的端口号，或者 Unix 域连接的套接字文件名扩展。 如果在 host 或 hostaddr 参数中给出了多个主机，则此参数可以指定与主机列表长度相同的逗号分隔的端口列表，或者可以指定用于所有主机的单个端口号。空字符串，或逗号分隔列表中的空项，指定了在构建 PostgreSQL 时建立的默认端口号。
用于额外参数的服务名称。它指定了 pg_service.conf 中保存额外连接参数的服务名称。这允许应用程序只指定一个服务名称，以便可以集中维护连接参数。参见 第 32.17 节 。
这个选项确定会话是否必须具有某些属性才能被接受。通常与多个主机名结合使用，以便在多个主机中选择第一个可接受的候选项。有六种模式： any （默认） 任何成功的连接都是可接受的 read-write 会话必须默认接受读写事务（即，服务器不能处于热备模式，并且 default_transaction_read_only 参数必须为 off ） read-only 会话默认不接受读写事务（相反） primary 服务器不能处于热备模式 standby 服务器必须处于热备模式 prefer-stand…
已收录首次收录接口或属性变化不再收录
版本方格表示采样构建中的收录情况，不代表实际引入时间。点击方格可查看对应版本的定义和来源。
这些是 libpq 客户端连接关键字，与服务端 GUC 分开。仅有源码的关键字与编译默认表达式保留来源标识，不当作实测生效值。