# 连接参数说明 libpq的所有连接参数统一以字符串形式构造和传递，无论参数类型是主机名、端口、密码还是布尔选项。 具体参数及其描述如下表所示： 表1连接参数 | 参数 | 描述 | 参数默认值 | |:---|:---|:---| | host | 要连接的主机名。如果主机名以斜杠（/）开头，则它声明使用Unix域套接字通讯而不是TCP/IP通讯，该值就是套接字文件所存储的目录。如果没有声明host，那么默认是与位于/tmp目录（或者安装GaussDB的时候声明的套接字目录）里面的Unix-域套接字连接。在没有Unix域套接字的机器上，默认与localhost连接。 接受以","分割的字符串来指定多个主机名，支持指定多个主机名。 | NULL | | hostaddr | 与之连接的主机的IP地址，是标准的IPv4地址格式，比如，172.28.40.9。如果机器支持IPv6，那么也可以使用IPv6的地址。如果声明了一个非空的字符串，那么使用TCP/IP通讯机制。 接受以","分割的字符串来指定多个IP地址，支持指定多个IP地址。 使用hostaddr取代host可以让应用避免一次主机名查找，这一点对于那些有时间约束的应用来说可能是非常重要的。不过，GSSAPI或SSPI认证方法要求主机名（host）。因此，应用下面的规则： 1. 如果声明了不带hostaddr的host那么就强制进行主机名查找。 2. 如果声明中没有host，hostaddr的值给出服务器网络地址。如果认证方法要求主机名，那么连接尝试将失败。 3. 如果同时声明了host和hostaddr，那么hostaddr的值作为服务器网络地址。host的值将被忽略，除非认证方法需要它，在这种情况下它将被用作主机名。 须知： - 如果host不是网络地址hostaddr处的服务器名，那么认证很有可能失败。 - 如果主机名（host）和主机地址都没有，那么libpq将使用一个本地的Unix域套接字进行连接，或者是在没有Unix域套接字的机器上，它将尝试与localhost连接。 | NULL | | port | 主机服务器的端口号，或者在Unix域套接字连接时的套接字扩展文件名。 接受以","分割的字符串来指定多个端口号，支持指定多个端口号。 | NULL | | user | 要连接的用户名，默认与运行该应用的用户操作系统名同名的用户。 | 当前操作系统用户名 | | dbname | 数据库名，默认与用户名相同。 | 与user参数相同 | | password | 如果服务器要求密码认证，所用的密码。 | NULL | | connect_timeout | 连接的最大等待时间，以秒计，0或者不声明表示无穷大。不建议把连接超时的值设置小于2秒。 | 0（无超时） | | client_encoding | 为该连接设置client_encoding配置参数。除了对应的服务器选项接受的值，还可以使用auto从客户端中的当前环境中确定正确的编码（Unix系统上是LC_CTYPE环境变量）。 | 与服务器端编码一致 | | tty | 该参数当前不生效（早期版本用于指定服务器调试输出的位置）。 | NULL | | options | 指定在连接开始时发送到服务器的命令行选项。例如，将该参数设置为"-c geqo=off"表示设置会话的geqo参数值为off。 | NULL | | application_name | 为application_name配置参数指定一个值，表明当前用户身份。 | NULL | | fallback_application_name | 为application_name配置参数指定一个后补值。如果通过连接参数或PGAPPNAME环境变量没有为application_name给定一个值，将使用这个值。在一般工具程序中，若设置一个默认名，但不希望这个默认名被用户覆盖，可以通过指定一个后补值来实现。 | NULL | | keepalives | 控制客户端侧的TCP保持激活是否使用。缺省值是1，表示保持激活；如果不需要保持激活，可以更改为0，表示关闭。通过Unix域套接字进行连接将忽略这个参数。 | 1 | | keepalives_idle | 在TCP应该发送一个保持激活的信息给服务器之后，控制不活动的秒数。0值或者不配置表示使用系统缺省。如果是通过 Unix 域套接字进行连接，或者禁用了"保持激活"功能，则该参数将被忽略。 | 默认值：0，表示使用系统TCP配置值。 | | keepalives_interval | 在TCP保持激活信息没有被应该传播的服务器承认之后，控制探活报文发送的间隔秒数。0值或者不配置表示使用系统缺省。如果是通过 Unix 域套接字进行连接，或者禁用了"保持激活"功能，则该参数将被忽略。 | 默认值：0，表示使用系统TCP配置值。 | | keepalives_count | 控制TCP发送保持激活信息的次数。0值或者不配置表示使用系统缺省。如果是通过 Unix 域套接字进行连接，或者禁用了"保持激活"功能，则该参数将被忽略。 | 默认值：0，表示使用系统TCP配置值。 | | tcp_user_timeout | 在支持TCP_USER_TIMEOUT套接字选项的操作系统上，指定传输的数据在TCP连接被强制关闭之前可以保持未确认状态的最大时长。单位为毫秒，0值或者不配置表示使用系统缺省。通过Unix域套接字进行连接将忽略这个参数。 | 默认值：0，表示使用系统TCP配置值。 | | tcp_syn_retries | 在支持TCP_SYNCNT套接字选项的操作系统上，指定客户端建立连接三次握手阶段SYN包发送失败而重新传输的次数。0值或者不配置表示使用系统缺省。通过Unix域套接字进行连接将忽略这个参数。 | 默认值：0，表示使用系统TCP配置值。 | | rw_timeout | 设置客户端连接读写超时时间，单位为秒。默认值为0，表示不设置超时时间。 当libpq侧触发超时且连接关闭时，其下发给数据库侧正在运行的业务会被强制终止。该能力受GUC参数check_disconnect_query控制，设置为on表示支持该能力，设置为off表示不支持该能力。 | 0 | | sslmode | 启用SSL加密的方式： - disable：不使用SSL安全连接。 - allow：如果数据库服务器要求使用，则可以使用SSL安全加密连接，但不验证数据库服务器的真实性。 - prefer：如果数据库支持，那么首选使用SSL安全加密连接，但不验证数据库服务器的真实性，为默认值。 - require：必须使用SSL安全连接，但是只做了数据加密，而并不验证数据库服务器的真实性。 - verify-ca：必须使用SSL安全连接，当前windows ODBC不支持cert方式认证。 - verify-full：必须使用SSL安全连接，当前windows ODBC不支持cert方式认证。 | prefer | | sslcompression | 如果设置为1（默认），SSL连接之上传送的数据将被压缩（这要求OpenSSL版本为0.9.8或更高）。如果设置为0，压缩将被禁用（这要求OpenSSL版本为1.0.0或更高）。如果建立的是一个没有SSL的连接，这个参数会被忽略。如果使用的OpenSSL版本不支持该参数，它也会被忽略。压缩会占用CPU时间，但是当瓶颈为网络时可以提高吞吐量。如果CPU性能是限制因素，禁用压缩能够改进响应时间和吞吐量。 | 1（开启SSL时） | | sslcert | 该参数指定客户端SSL证书的文件名。如果没有建立SSL连接，这个参数会被忽略。 | NULL | | sslkey | 该参数指定用于客户端证书的密钥位置。它能够指定一个从外部"引擎"（引擎是OpenSSL的可载入模块）得到的密钥。一个外部引擎说明应该由一个冒号分隔的引擎名称以及一个引擎相关的关键标识符组成。如果没有建立SSL连接，这个参数会被忽略。 | NULL | | sslrootcert | 该参数指定一个包含SSL证书机构（CA）证书的文件名称。如果该文件存在，服务器的证书将被验证是由这些机构之一签发。 | NULL | | sslcrl | 该参数指定SSL证书撤销列表（CRL）的文件名。列在这个文件中的证书如果存在，在尝试认证该服务器证书时会被拒绝。 | NULL | | requirepeer | 该参数指定服务器的操作系统用户，例如requirepeer=postgres。当建立一个Unix域套接字连接时，如果设置了这个参数，客户端在连接开始时检查服务器进程是否运行在指定的用户名之下。如果发现不是，该连接会被一个错误中断。这个参数能被用来提供与TCP/IP连接上SSL证书相似的服务器认证（注意，如果Unix域套接字在/tmp或另一个公共可写的位置，任何用户能启动一个在那里侦听的服务器。使用这个参数来保证所连接的是一个由可信用户运行的服务器）。这个选项只在实现了peer认证方法的平台上支持。 | NULL | | krbsrvname | 当用GSSAPI认证时，要使用的Kerberos服务名。为了让Kerberos认证成功，这必须匹配在服务器配置中指定的服务名。 | NULL | | gsslib | 用于GSSAPI认证的GSS库。只用在Windows上。设置为gssapi可强制libpq用GSSAPI库来代替默认的SSPI进行认证。 | NULL | | service | 用于附加参数的服务名。它指定保持附加连接参数的pg_service.conf中的一个服务名。这允许应用只指定一个服务名，这样连接参数能被集中维护。 | NULL | | authtype | 不再使用"authtype"，因此将其标记为"不显示"。将其保留在数组中，以免拒绝旧应用程序中的conninfo字符串，这些应用程序可能仍在尝试设置它。 | NULL | | remote_nodename | 指定连接本地节点的远端节点名称。 | NULL | | localhost | 指定在一个连接通道中的本地地址。 | NULL | | localport | 指定在一个连接通道中的本地端口。 | NULL | | fencedUdfRPCMode | 控制fenced UDF RPC协议是使用unix域套接字或特殊套接字文件名。缺省值是0，意思为关闭。使用unix domain socket模式，文件类型为".s.PGSQL.%d"，但是要使用fenced udf ，文件类型为.s.fencedMaster_unixdomain，可以更改为1，意思为开启。 | 0 | | replication | 这个选项决定是否该连接应该使用复制协议而不是普通协议。这是PostgreSQL的复制连接以及pg_basebackup之类的工具在内部使用的协议，但也可以被第三方应用使用。支持下列值，大小写无关： - true、on、yes、1、reply 用于集群内的连接，连接进入到物理复制模式。 - standby_cluster、hadr_main_standby、hadr_standby_cn 用于集群间的连接，连接进入到物理复制模式。 - database 连接进入到逻辑复制模式，连接到dbname参数中指定的数据库。 - false、off、no、0、NULL（缺省值） 该连接是一个常规连接，这是默认行为。 在物理或者逻辑复制模式中，仅能使用简单查询协议。 | NULL | | backend_version | 传递到远端的后端版本号。 | NULL | | prototype | 设置当前协议级别，默认：1。该参数当前不生效。 | 1 | | enable_ce | 控制是否允许客户端连接全密态数据库。默认值为0，不开启密态功能。如果需要开启密态等值查询基本能力，则修改为1或者3。 | 0 | | key_info | 与enable_ce一起使用，在密态数据库中，用于设置访问外部密钥管理者的参数。 | NULL | | connection_info | connection_info是一个包含driver_name、driver_version、driver_path和os_user的json字符串。 如果不为NULL，使用connection_info 忽略connectionExtraInfo。 如果为NULL，生成与libpq相关的连接信息字符串，当connectionExtraInfo为0时connection_info只有driver_name和driver_version。 | 0 | | connectionExtraInfo | 是否将当前驱动的部署路径、进程属主用户信息上报到数据库。默认值为0，表示不打开；设置1，表示打开。 说明： 当设置为1时，libpq会将当前驱动的部署路径、进程属主用户上报到数据库中，记录在GUC参数connection_info里，同时可以在PG_STAT_ACTIVITY中查询到。 | 0 | | target_session_attrs | 设定连接的主机的类型。主机的类型和设定的值一致时才能连接成功。指定多IP或者域名对应的是多IP时才会校验此参数。target_session_attrs的设置规则如下： - any：可以对所有类型的主机进行连接。 - read-write：仅对可读写的主机进行连接。 - read-only：仅对只读的主机进行连接。 - primary（默认值）：仅对主备系统中的主节点进行连接。 - standby：仅对主备系统中的备节点进行连接。 - prefer-standby：首先尝试与主备系统中的备节点进行连接。如果对hosts列表的所有备节点都连接失败，那么尝试"any"模式进行连接。 | primary | | enable_host_cache | 是否开启节点缓存功能，0表示不开启，1表示开启。默认不开启。 说明： 节点缓存在连接串配置单IP或者target_session_attrs=any时不生效。 | 0 | | hostcache_expiration_time | libpq尝试连接主机后将记录主机状态。在设定的hostcache_expiration_time时间内保持记录的主机状态可信，超时后记录的主机状态失效。参数单位为秒（s），默认值为10，取值范围：0 \~ INT_MAX。 说明： hostcache_expiration_time在enable_host_cache=1时生效。 | 10 | | driver_type | 区分libpq的上层驱动类型，默认为"GaussDB LIBPQ Driver"。该参数不建议设置，保持默认即可。 | GaussDB LIBPQ Driver | | force_no_truncation/supportZeroCharacter | 使部分数据库执行语句函数和异步命令处理函数在以文本格式传递参数（paramFormats中对应的值为0）时，强制使用函数调用者指定的参数长度（paramLengths中对应的值）。force_no_truncation/supportZeroCharacter的设置规则如下： - 1：打开。需要保证客户端字符集和数据库字符集一致。 - 0（默认值）：关闭。 force_no_truncation/supportZeroCharacter打开后影响以下数据库执行语句函数和异步命令处理函数： - PQexecParams - PQexecParamsBatch - PQexecPrepared - PQexecPreparedBatch - PQsendQueryParams - PQsendQueryPrepared 须知： 使用以上涉及的数据库执行语句函数和异步命令处理函数时，传递包含'\\0'字符的文本参数值但不希望导致文本参数值被'\\0'字符截断，则必须打开此参数。 | 0 | ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/notice_3.0-zh-cn.png) 配置以上连接参数时，建议配置合法值，如果配置非法值，可能导致建立连接失败或者实际生效值为默认值。 #### 建立连接的首包介绍 驱动与数据库建立连接过程中，Socket（套接字）建立之后，由驱动以key value形式向数据库发送的第一个报文为首包。首包内容包括用户名（user）、数据库名（database）、部分GUC参数信息（replication、redistribution、backend_version、application_name、client_encoding、connect_timeout、enable_full_encryption、DateStyle、TimeZone、geqo、connection_info、gaussdb.capacity_version）以及[options]配置参数信息。GUC参数的介绍参见《参考》中"数据库运行参数说明 \> GUC参数说明"。 ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/notice_3.0-zh-cn.png) - gaussdb.capacity_version参数表示驱动支持的兼容性能力集的版本号，用于驱动与数据库协商此次建立连接时使用的兼容性特性集合。该参数为内部参数。 - 数据库执行以下命令后，上述首包GUC参数的值将被更改为首包设置的值。 ``` reset all; ```