# 连接参数参考 #### 常用连接参数 Go驱动的常用连接参数，如[表1]所示。 表1数据库连接参数 | 参数名称 | 参数说明 | |:---|:---| | host | 主机IP地址，默认值为localhost。也可通过环境变量PGHOST来指定。 | | port | 主机服务器的端口号，默认值为5432。也可通过环境变量PGPORT来指定。 | | dbname | 数据库名，也可通过环境变量PGDATABASE来指定。 | | user | 用户名，也可通过环境变量PGUSER来指定。 | | password | 密码。 | | connect_timeout | 指定连接服务器操作的超时时间，也可通过环境变量PGCONNECT_TIMEOUT来指定。默认值为0，表示没有超时。 | | sslmode | 启用SSL加密的方式，也可通过环境变量PGSSLMODE来指定。默认值为prefer。 参数取值范围： - disable：不使用SSL安全连接。 - allow：如果数据库服务器要求使用，则可以使用SSL安全加密连接，但不验证数据库服务器的真实性。 - prefer：如果数据库支持，那么首选使用SSL安全加密连接，但不验证数据库服务器的真实性。 - require：必须使用SSL安全连接，但是只做了数据加密，而并不验证数据库服务器的真实性。 - verify-ca：必须使用SSL安全连接，并验证服务器是否具有由可信任的证书机构签发的证书。 - verify-full：必须使用SSL安全连接，并且验证服务器是否具有由可信任的证书机构签发的证书，以及验证服务器主机名是否与证书中的一致。 | | sslkey | SSL连接时，指定客户端密钥路径。也可通过设置环境变量PGSSLKEY来指定。 | | sslcert | SSL连接时，指定客户端证书路径。也可通过设置环境变量PGSSLCERT来指定。 | | sslrootcert | SSL连接时，指定根证书路径。也可通过设置环境变量PGSSLROOTCERT来指定。 | | sslcrl | 指定SSL证书吊销列表（CRL，Certificate Revocation List）的文件路径。也可通过设置环境变量PGSSLCRL来指定。若服务端证书存在于已配置的CRL中，客户端在SSL握手阶段将拒绝认证并终止连接。 | | sslpassword | 指定解密SSL密钥文件的密码短语。启用此参数时，表明sslkey文件是通过加密方式存储的，当前sslkey支持DES/AES加密方式。 说明： DES加密算法安全性低，存在安全风险，建议使用更安全的加密算法。 | | disable_prepared_binary_result | 表示此连接在从预准备语句接收查询结果时，是否使用二进制格式。该参数为字符串类型，仅用于调试。默认值为no。 取值范围： - yes：表示此连接在从预准备语句接收查询结果时不使用二进制格式。 - no：表示此连接在从预准备语句接收查询结果时使用二进制格式。 | | binary_parameters | 表示连接期间是否以二进制形式发送\[\]byte。该参数属于字符串类型。默认值为no。 取值范围： - yes：表示以二进制形式发送\[\]byte。建议值为yes，绑定参数按照\[\]byte绑定，可以减少内部类型转换。 - no：表示不以二进制形式发送\[\]byte。 | | target_session_attrs | 指定数据库的连接类型，该参数用于识别主备节点，也可通过环境变量PGTARGETSESSIONATTRS来指定。默认值为any，该参数共有六种取值：any、master、slave、preferSlave、read-write、read-only。 - any：尝试连接URL连接串中的任何一个数据节点。 - master：尝试连接到URL连接串中的主节点，如果找不到就抛出异常。 - slave：尝试连接到URL连接串中的备节点，如果找不到就抛出异常。 - preferSlave：尝试连接到URL连接串中的备数据节点。若没有可用的备数据节点，则连接到主数据节点。 - read-write：仅对可读写的主机进行连接。 - read-only：仅对只读的主机进行连接。 | | loggerLevel | 指定日志级别，打印相关日志信息，也可通过环境变量PGLOGGERLEVEL来指定。 支持trace、debug、info、warn、error、none，级别从高到低。默认值为error。 说明： 日志或报错信息中若含有安全相关的关键字（PASSWORD、GS_ENCRYPT、IDENTIFIED等），Go驱动会使用\*\*\*\*\*\*代替相关信息。 | | application_name | 标识连接到数据库的应用程序名称。默认值为go-driver，该参数不建议用户配置。 | | RuntimeParams | 设置连接会话时默认运行的USERSET类型GUC参数的值。例如参数search_path、application_name、statement_timeout等，可以在连接字符串中进行配置。 | | autoBalance | 分布式环境下，指定负载均衡的策略，为字符串类型。默认值为false，参数取值共有六种：true、balance、roundrobin、shuffle、priorityn、false。 - true、balance或roundrobin：表示开启go驱动sql负载均衡功能，将应用程序的多个连接均衡到数据库集群中各个可用的CN。 例如： ``` gaussdb://user:password@host1:port1,host2:port2/database?autoBalance=true ``` Driver将定期刷新整个集群可用CN列表，该刷新周期可使用参数recheckTime进行配置，默认值为10s。比如获取到的列表为： ``` host1:port1,host2:port2,host3:port3,host4:port4 ``` 在启用负载均衡时，host1和host2仅在首次连接时保证高可用性。之后，Driver将从host3、host4、host1、host2中依次选择可用的CN来刷新可用CN列表，后续用户调用的Connector.Connect将使用RoundRobin算法从host1、host2、host3、host4选取CN节点进行连接。 - priorityn：表示开启Driver优先级负载均衡功能，将应用程序的多个连接首先均衡到url上配置的前n个中可用的CN数据库节点，当url上配置前n个节点全部不可用时，连接会随机分配到数据库集群中其他可用CN数据库节点。n为正整数，且小于url上配置的CN数量。 例如： ``` gaussdb://user:password@host1:port1,host2:port2,host3:port3/database?autoBalance=priority2 ``` Driver将定期获取整个集群可用CN列表，比如获取到的列表为： ``` host1:port1,host2:port2,host3:port3,host4:port4,host5:port5,host6:port6 ``` 其中host1和host2处于AZ1，host3和host4处于AZ2。Driver将从优先从host1，host2中做负载均衡，host1和host2全部不可用才从host3、host4、host5、host6中随机选择CN节点进行连接。 - shuffle：表示开启Driver随机负载均衡功能，将应用程序的多个连接随机均衡到数据库集群中的各个可用CN。 例如： ``` gaussdb://user:password@host1:port1,host2:port2,host3:port3/database?autoBalance=shuffle ``` Driver将定期获取整个集群的可用CN列表，比如获取到的列表为： ``` host1:port1,host2:port2,host3:port3,host4:port4 ``` host1、host2和host3仅在首次连接时保证高可用性，后续将使用洗牌（shuffle）算法在刷新后的CN列表中随机选择一个CN节点进行连接。 - false：表示不开启Driver负载均衡功能和优先级负载均衡功能。 说明： - 负载均衡是基于连接级别，不是基于事务级别。如果连接是长连接，并且连接上的负载不均衡，无法保证CN节点上的负载均衡。 - 负载均衡仅能在分布式场景下使用。 | | recheckTime | 表示定期检测数据库集群中CN状态，获取可用CN的IP列表的时间间隔。该参数为integer类型，单位为s，取值范围为5 \~ 60，默认为10s。 | | usingEip | 指定是否使用业务IP实现负载均衡。该参数为字符串类型，默认值为yes。 - yes：表示使用业务IP（对应pgxc_node表中node_host1和node_port1列）实现负载均衡。 - no：表示使用数据IP（对应pgxc_node表中node_host和node_port列）实现负载均衡。 | | tcp_syn_retries | 设置TCP连接建立阶段的最大重试次数。若未配置此参数，系统将采用设备默认的重试次数。建议通过以下公式确保合理配置：重试次数 × 单次重试间隔 \< [connect_timeout]。 说明： 单次重试间隔为系统底层实现值，通常无需手动配置。 | | socketTimeout | 设置读写超时时间，如果业务语句执行或者从网络读取数据流超过该值，连接中断。 说明： 该参数限制单条SQL语句最长的执行时间，单语句执行超过该值则会中断重连。建议根据业务特征进行配置，如果未配置，默认为0，即不会超时。 | | timeZone | 设置该参数后，建连时将数据库GUC参数TimeZone设为该参数值，查询不带时区的timestamp/date数据时，返回结果会自动补充GUC参数TimeZone指定的时区。该参数属于字符串类型。 取值范围：与数据库GUC参数TimeZone的取值范围一致。GUC参数TimeZone的取值范围，请参见《参考》中"数据库运行参数说明 \> GUC参数说明 \> 客户端连接缺省设置 \> 区域和格式化"。 | #### 连接参数配置值的生效优先级 Go驱动可以通过以下方式获取连接参数配置值，分别为： - DSN/URL连接串（显式指定） - 环境变量\[PGXX\]（部分参数可通过环境变量来指定，详见[表1]） - 默认值 连接参数配置值的生效优先级：DSN/URL连接串 \> 环境变量\[PGXX\] \> 默认值。以配置连接参数中的端口号为例： 1. 创建数据库连接对象时，端口号优先从DSN或URL连接串获取port参数的配置值。若连接串有配置port参数，则以该配置值作为端口号创建数据库连接对象。 2. 若连接串没有配置port参数，则Go驱动会进一步检查是否配置环境变量PGPORT。若环境变量PGPORT对应值不为空，则以该配置值作为端口号创建数据库连接对象。 3. 若连接串和环境变量都没有配置，则以默认值5432作为端口号创建数据库连接对象。 ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - \[PGXX\]为环境变量名，实际环境变量名参考[表1]中参数说明部分。 - 若选择使用\[PGXX\]环境变量中的值进行数据库连接对象创建，建议优先检查\[PGXX\]对应的值是否为预期值。 - 环境变量可以通过export PGXX="value"进行配置。\[PGXX\]为[表1]的环境变量，value为配置值。以PGTARGETSESSIONATTRS为例： ``` export PGTARGETSESSIONATTRS="master" ``` - 连接参数配置参考[方式一](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/gaussdb-12-0255.html#ZH-CN_TOPIC_0000002620719941__section119416991016)或[方式二](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/gaussdb-12-0255.html#ZH-CN_TOPIC_0000002620719941__section131958901011)。 #### 建立连接的首包介绍 驱动与数据库建立连接过程中，Socket（套接字）建立之后，由驱动以key value形式向数据库发送的第一个报文为首包。首包内容包括用户名（user）、数据库名（database）以及部分GUC参数信息（enable_full_encryption、application_name、RuntimeParams）。其中RuntimeParams指代数据库支持的USERSET类型GUC参数，而非参数名，具体介绍可以参考[RuntimeParams]。GUC参数的具体介绍，请参见《参考》中"数据库运行参数说明 \> GUC参数说明"。 ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/notice_3.0-zh-cn.png) 数据库执行以下命令后，上述首包GUC参数的值将被更改为首包设置的值。 ``` reset all; ```