连接参数参考

常用连接参数

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] > 默认值。以配置连接参数中的端口号为例：

创建数据库连接对象时，端口号优先从DSN或URL连接串获取port参数的配置值。若连接串有配置port参数，则以该配置值作为端口号创建数据库连接对象。
若连接串没有配置port参数，则Go驱动会进一步检查是否配置环境变量PGPORT。若环境变量PGPORT对应值不为空，则以该配置值作为端口号创建数据库连接对象。
若连接串和环境变量都没有配置，则以默认值5432作为端口号创建数据库连接对象。

[PGXX]为环境变量名，实际环境变量名参考表1中参数说明部分。
若选择使用[PGXX]环境变量中的值进行数据库连接对象创建，建议优先检查[PGXX]对应的值是否为预期值。
环境变量可以通过export PGXX="value"进行配置。[PGXX]为表1的环境变量，value为配置值。以PGTARGETSESSIONATTRS为例：
```
export PGTARGETSESSIONATTRS="master"
```
连接参数配置参考方式一或方式二。

建立连接的首包介绍

驱动与数据库建立连接过程中，Socket（套接字）建立之后，由驱动以key value形式向数据库发送的第一个报文为首包。首包内容包括用户名（user）、数据库名（database）以及部分GUC参数信息（enable_full_encryption、application_name、RuntimeParams）。其中RuntimeParams指代数据库支持的USERSET类型GUC参数，而非参数名，具体介绍可以参考RuntimeParams。GUC参数的具体介绍，请参见《参考》中“数据库运行参数说明 > GUC参数说明”。