pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。
百科 / 连接参数
libpq 连接关键字、环境变量、默认值与优先级。
当前查看 PostgreSQL 18.6。
共 55 个条目，PostgreSQL 18.6 收录 51 个。
将 GSS 凭据转发（委派）给服务器。默认值为 0 ，表示不向服务器转发凭据。将其设置为 1 时，会在可能的情况下转发凭据。
决定是否与服务器协商安全的 GSS TCP/IP 连接，以及协商时的优先级。共有三种模式：
GSSAPI 认证使用的 GSS 库。目前仅在同时支持 GSSAPI 和 SSPI 的 Windows 构建中生效，其他情况忽略。此时设为 gssapi，可让 libpq 使用 GSSAPI 库认证，而非默认的 SSPI。
GSSAPI 认证使用的 Kerberos 服务名。此值必须与服务器配置中的服务名匹配，Kerberos 认证才能成功，另见第 20.6 节。默认值通常为 postgres，但构建 PostgreSQL 时可通过 configure 的 --with-krb-srvnam 选项更改。多数环境无需修改此参数；某些 Kerberos 实现可能要求不同的服务名，例如 Microsoft Active Directory 要求使用大写 POSTGRES。
此选项已弃用，应改用 sslmode。
指定连接允许使用的最高 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 连接时，此参数被忽略。
此选项决定是否可以向服务器发送客户端证书，以及服务器是否必须请求客户端证书。共有三种模式：
设为 1 时，对 SSL 连接上传输的数据进行压缩；设为 0 时禁用压缩。默认值为 0。未使用 SSL 连接时，此参数被忽略。
指定 SSL 服务器证书吊销列表（CRL）的文件名。如果文件存在，其中列出的证书将在认证服务器证书时被拒绝。如果 sslcrl 和 sslcrldir 均未设置，则使用 ~/.postgresql/root.crl。
指定 SSL 服务器证书吊销列表（CRL）的目录名。如果目录存在，其中各文件列出的证书将在认证服务器证书时被拒绝。
指定客户端证书私钥的位置。可以是文件名，代替默认的 ~/.postgresql/postgresql.key；也可以指定来自外部引擎的密钥，引擎是 OpenSSL 的可加载模块。外部引擎的指定格式是引擎名与引擎专用密钥标识符，两者用冒号分隔。未建立 SSL 连接时，此参数被忽略。
这个参数指定 libpq 记录此 SSL 上下文所用密钥的位置。这对于调试 PostgreSQL 协议交互，或者借助 Wireshark 之类的网络检查工具分析客户端连接很有用。如果未建立 SSL 连接，或者使用的是 LibreSSL （其不支持密钥记录），则会忽略此参数。密钥将按 NSS 格式记录。
决定是否与服务器协商安全的 SSL TCP/IP 连接，以及协商时的优先级。共有六种模式：
使用 SSL 时，此选项控制与服务器协商 SSL 加密的方式。默认 postgres 模式下，客户端先询问服务器是否支持 SSL；direct 模式下，建立 TCP/IP 连接后立即开始标准 SSL 握手。传统 PostgreSQL 协议协商对不同服务器配置的适应性最强。如果已知服务器支持直接 SSL 连接，则 direct 可减少一次往返，降低连接延迟，还可使用不识别 PostgreSQL 协议的通用 SSL 网络工具。直接 SSL 选项从 PostgreSQL 17 引入。
指定 sslkey 所指私钥的密码，使客户端证书私钥即使在不便交互输入密码时，也能以加密形式存储在磁盘上。
指定包含 SSL 证书颁发机构（CA）证书的文件名。如果文件存在，会验证服务器证书是否由其中某个机构签发。默认为 ~/.postgresql/root.crt。
设为 1（默认值）时，libpq 在启用 SSL 的连接上设置 TLS 的服务器名称指示（SNI）扩展；设为 0 可关闭此行为。
所选版本未收录此条目。
指定 application_name 配置参数的值。
设置此连接的 client_encoding 配置参数。除对应服务器选项接受的值外，还可使用 auto，根据客户端当前区域设置确定适当编码，在 Unix 系统上依据 LC_CTYPE 环境变量。
指定 application_name 配置参数的后备值。如果连接参数和 PGAPPNAME 环境变量都未提供 application_name，就使用此值。通用工具程序可据此设置默认应用名，同时允许用户覆盖。
这个参数指定要向服务器请求的协议版本。默认会使用 PostgreSQL 协议的 3.0 版本；但如果连接字符串指定了依赖更高协议版本的特性，则会使用 libpq 支持的最新版本。如果服务器不支持客户端请求的协议版本，连接会自动降级为服务器支持的较低次版本协议。连接尝试完成后，你可以使用 PQfullProtocolVersion 来确定最终协商得到的确切协议版本。
这个参数指定该连接允许的最低协议版本。默认情况下，允许使用 libpq 所支持的任何 PostgreSQL 协议版本，目前即 3.0 。如果服务器不支持此协议版本或更高版本，则连接将被关闭。
指定连接开始时发送到服务器的命令行选项。例如，将其设置为 -c geqo=off 或 --geqo=off 会把会话的 geqo 参数值设为 off 。此字符串中的空格被视为分隔命令行参数，除非用反斜杠（ \ ）转义；写 \\ 表示字面上的反斜杠。有关可用选项的详细讨论，请参阅 第 19 章 。
这个选项确定连接是否应该使用复制协议而不是正常协议。这就是PostgreSQL复制连接以及诸如 pg_basebackup 这样的工具在内部使用的方式，但也可以被第三方应用程序使用。要了解复制协议的描述，请参考 第 54.4 节 。
所选版本未收录此条目。
所选版本未收录此条目。
建立连接时最长等待时间，单位为秒，以十进制整数书写，例如 10。零、负数或未指定表示无限等待。此超时分别应用于每个主机名或 IP 地址。例如，指定两个主机且 connect_timeout 为 5 时，每个主机在 5 秒内未连接成功就会超时，总等待时间可能达到 10 秒。
控制是否使用客户端 TCP 保活。默认值为 1，即启用；不需要保活时可改为 0，即禁用。通过 Unix 域套接字连接时，此参数被忽略。
控制允许丢失多少个 TCP 保活探测，之后才将客户端到服务器的连接视为失效。零表示使用系统默认值。通过 Unix 域套接字连接或禁用保活时，此参数被忽略。仅在提供 TCP_KEEPCNT 或等价套接字选项的系统上支持；其他系统中无效。
控制连接空闲多少秒后，TCP 应向服务器发送保活消息。零表示使用系统默认值。通过 Unix 域套接字连接或禁用保活时，此参数被忽略。仅在提供 TCP_KEEPIDLE 或等价套接字选项的系统以及 Windows 上支持；其他系统中无效。
控制 TCP 保活消息未获服务器确认后，等待多少秒再重新发送。零表示使用系统默认值。通过 Unix 域套接字连接或禁用保活时，此参数被忽略。仅在提供 TCP_KEEPINTVL 或等价套接字选项的系统以及 Windows 上支持；其他系统中无效。
控制已发送数据最多可保持未确认状态多少毫秒，超过后强制关闭连接。零表示使用系统默认值。通过 Unix 域套接字连接时，此参数被忽略。仅在提供 TCP_USER_TIMEOUT 的系统上支持；其他系统中无效。
控制客户端是否使用通道绑定。require 表示连接必须使用通道绑定；prefer 表示可用时优先使用；disable 表示禁止使用。PostgreSQL 构建时启用 SSL 支持则默认为 prefer，否则默认为 disable。
所选版本未收录此条目。
由授权服务器发放的 OAuth 2.0 客户端标识符。如果 PostgreSQL 服务器为该连接 请求 OAuth 令牌 ，并且没有安装 自定义 OAuth 钩子 来提供该令牌，那么就必须设置此参数；否则连接会失败。
与 OAuth 授权服务器通信时要使用的客户端密码（如果有）。该参数是否必需由 OAuth 提供者决定；公开客户端（public client）通常不使用密钥，而机密客户端（confidential client）通常会使用。
如果服务器为该连接请求 OAuth 令牌，要联系的受信任签发者的 HTTPS URL。所有 OAuth 连接都必须设置此参数；它应当与 服务器 HBA 配置 中的 issuer 设置完全一致。
发送给授权服务器的访问请求的授权范围，以空格分隔的 OAuth 授权范围标识符列表指定（列表可以为空）。该参数是可选的，面向高级用法。
指定用于存储密码的文件名（参见 第 32.16 节 ）。默认为 ~/.pgpass ，或在Microsoft Windows上为 %APPDATA%\postgresql\pgpass.conf 。（如果此文件不存在，则不会报告错误。）
服务器要求密码认证时使用的密码。
指定客户端要求服务器采用的认证方法。如果服务器没有使用所要求的方法来认证客户端，或者服务器没有完整完成认证握手，则连接将失败。也可以提供一个以逗号分隔的方法列表，此时服务器必须恰好使用其中一种方法，连接才会成功。默认情况下接受任意认证方法，并且服务器也可以完全跳过认证。
指定服务器的操作系统用户名，例如 requirepeer=postgres。建立 Unix 域套接字连接时，如果设置了此参数，客户端会在连接开始时检查服务器进程是否以指定用户运行；不符则报错并中止连接。此参数可提供类似于 TCP/IP 连接中 SSL 证书所提供的服务器身份认证。如果 Unix 域套接字位于 /tmp 等所有人可写的位置，任何用户都可能在那里启动监听服务器；使用此参数可确保连接的是可信用户运行的服务器。仅在实现了 peer 认证方法的平台上支持此选项，见第 20.9 节。
以 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 时，也可以使用 IPv6 地址。只要此参数为非空字符串，就始终使用 TCP/IP 通信。未指定此参数时，会解析 host 以取得对应 IP 地址；如果 host 本身是 IP 地址，则直接使用。
控制客户端尝试连接可用主机和地址的顺序。一旦某次连接尝试成功，就不会再尝试其他主机和地址。该参数通常与多个主机名或返回多个 IP 地址的 DNS 记录一起使用。它还可以与 target_session_attrs 组合使用，例如只在备库之间进行负载均衡。连接一旦成功建立，随后在返回的连接上发出的所有查询都会发送到同一台服务器。目前有两种模式：
服务器主机上要连接的端口号；对于 Unix 域连接，则为套接字文件名后缀。如果 host 或 hostaddr 指定了多个主机，可提供与主机列表等长的逗号分隔端口列表，或指定一个供所有主机使用的端口号。空字符串或列表中的空项表示使用 PostgreSQL 构建时确定的默认端口。
用于额外参数的服务名称。它指定了 pg_service.conf 中保存额外连接参数的服务名称。这允许应用程序只指定一个服务名称，以便可以集中维护连接参数。参见 第 32.17 节 。
决定会话必须具备哪些属性才能被接受。通常与多个主机名一起使用，从多台主机中选择第一个符合条件的连接。共有六种模式：
已收录首次收录接口或属性变化不再收录
版本方格表示采样构建中的收录情况，不代表实际引入时间。点击方格可查看对应版本的定义和来源。
这些是 libpq 客户端连接关键字，与服务端 GUC 分开。仅有源码的关键字与编译默认表达式保留来源标识，不当作实测生效值。