文档首页/ 云数据库 GaussDB/ 开发指南（分布式_V2.0-8.x）/ 应用程序开发教程/ 基于JDBC开发/ 开发步骤/ 连接数据库/ 连接参数参考
更新时间：2025-05-29 GMT+08:00
查看PDF
分享

连接参数参考

info参数连接的所有属性名称对大小写敏感。常用的属性如表1所示。

表1 info参数的连接属性

属性名称

属性说明

属性值

PGDBNAME

表示数据库名称（url中无需配置该参数，自动从Properties文件中解析）。

属性类型：String

PGHOST

主机IP地址（url中无需配置该参数，自动从Properties文件中解析），同时支持IPv4和IPv6。若配置多个CN，它们的IP和端口用“:”分隔，并作为整体以逗号分隔其他CN。

属性类型：String

PGPORT

主机端口号（url中无需配置该参数，自动从Properties文件中解析）。

属性类型：Integer

user

表示创建连接的数据库用户。

属性类型：String

password

表示数据库用户的密码。

属性类型：String

driverInfoMode

控制驱动描述信息的输出模式。

属性类型：String

取值范围：postgresql、gaussdb。

  • postgresql表示输出postgresql相关的驱动描述信息。
  • gaussdb表示输出gaussdb相关的驱动描述信息。

默认值：postgresql

enable_ce

表示密态等值查询的能力。

属性类型：String

取值范围：

  • enable_ce=1表示JDBC支持密态等值查询基本能力。
  • enable_ce=3表示JDBC支持密态等值查询基本能力。

默认值：该属性不设置则为空，表示不开启密态等值查询。

key_info

与enable_ce一起使用，在密态数据库中，用于设置访问外部密钥管理者的参数。

属性类型：String

默认值：该属性不设置则为空。

refreshClientEncryption

指定密态数据库是否支持客户端缓存刷新。

属性类型：String

取值范围：

  • 1或NULL表示密态数据库支持客户端缓存刷新。
  • 其他字符串表示密态数据库不支持客户端缓存刷新。

默认值：NULL

loggerLevel

指定日志记录级别。

属性类型：String

取值范围：目前支持4种级别（不区分大小写）：OFF、INFO、DEBUG、TRACE。

  • OFF表示关闭日志。
  • INFO、DEBUG和TRACE表示记录的日志信息详细程度不同。

默认值：OFF

loggerFile

用于指定日志输出路径（目录和文件名）。一般要求明确指定日志目录和文件名。

在开启连接监控功能时用于指定输出监控日志路径，如需将JDBC日志输出到指定路径，可通过 java.util.logging属性文件或系统属性进行配置。仅限开启连接监控场景下使用，其他情况则不能使用。

属性类型：String

默认值：该属性不设置则为空，未指定目录则会在客户端运行程序目录下生成日志文件。

logger

表示JDBC Driver要使用的日志输出框架。JDBC Driver支持对接用户应用程序使用的日志输出框架。

属性类型：String

取值范围：Slf4JLogger

  • 如果缺省，则JDBC Driver使用JdkLogger。
  • 目前支持的第三方日志输出框架只有基于Slf4j-API的日志框架。具体使用方式，请参见日志管理。

allowEncodingChanges

设置该参数值为true进行字符集类型更改，配合参数characterEncoding设置字符集，二者使用“&”分隔。例：allowEncodingChanges=true&characterEncoding=UTF8。

属性类型：Boolean

取值范围：

  • true表示更改字符集类型。
  • false表示不更改字符集类型。

默认值：false

characterEncoding

需要配合allowEncodingChanges使用，allowEncodingChanges为false的情况下，characterEncoding仅允许设置为UTF8；allowEncodingChanges为true的情况下，characterEncoding可在取值范围内进行设置。

属性类型：String

取值范围：UTF8、GBK、LATIN1、GB18030、GB18030_2022、ZHS16GBK。

默认值：UTF8

currentSchema

设置当前连接的schema，在search-path中指定要设置的schema。如果schema名包含除字母、数字、下划线之外的特殊字符，需要在schema名上加引号，注意加引号后schema名大小写敏感。如需配置多个schema，要用逗号“,”进行分隔。

例如：currentSchema=schema_a,"schema-b","schema/c"

属性类型：String

缺省：如果未设置，则默认schema为连接使用的用户名。

loadBalanceHosts

指定是否使用负载均衡功能。

属性类型：Boolean

取值范围：

  • true表示使用洗牌算法从候选主机中随机选择一个主机建立连接。
  • false表示顺序连接url中指定的多个主机。

默认值：false

autoBalance

指定负载均衡的策略。

注意：
  1. 负载均衡是基于连接级别，不是基于事务级别。如果连接是长连接，并且连接上的负载不均衡，无法保证CN主机上的负载均衡。
  2. 该参数仅能在分布式场景下使用，集中式环境中不可使用。
  3. 如果在连接容灾集群时开启了负载均衡功能，那么查询请求会发送到主集群上，导致查询性能会受到影响。
  4. 在开启负载均衡时，url中可以配置浮动IP或数据IP，如果配置为浮动IP，系统会根据浮动IP获取对应的数据IP，通过获取的数据IP实现负载均衡。因此无论url中配置浮动IP或数据IP时，都需要确保数据IP网络连接正常，否则负载均衡功能将使用异常。

属性类型：String

取值范围：

  • true、balance或roundrobin：表示开启JDBC负载均衡功能，将应用程序的多个连接均衡到数据库集群中的各个可用CN。

    例如：

    jdbc:gaussdb://host1:port1,host2:port2/database?autoBalance=true

    JDBC会定期刷新整个集群的可用CN列表（CN列表中获取的host是数据IP），该刷新周期可以通过参数refreshCNIpListTime进行配置，默认值为10秒。比如获取到的列表为：

    host1:port1,host2:port2,host3:port3,host4:port4

    在启用负载均衡时，host1和host2仅在首次连接时保证高可用性。之后，Driver将从host1、host2、host3和host4中依次选择可用CN来刷新可用CN列表。后续用户新建的连接将使用轮询（RoundRobin）算法从host1、host2、host3和host4中选择CN主机进行连接。

  • priorityn：表示开启JDBC优先级负载均衡功能，将应用程序的多个连接首先均衡到url上配置的前n个中可用的CN数据库节点。当url上配置前n个节点全部不可用时，连接会随机分配到数据库集群中其他可用CN数据库节点。n为正整数，且小于url上配置的CN数量。当parseCandidatesByDomain设置为true时，priorityn的优先级配置不生效，这种场景下的优先级使用priorityDomains参数配置。使用priorityn进行负载均衡时，host不能使用IPv6。在多进程建立连接场景下，该策略会出现负载不均衡。

    例如：

    jdbc:gaussdb://host1:port1,host2:port2,host3:port3,host4:port4/database?autoBalance=priority2

    JDBC将定期获取整个集群可用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：表示开启JDBC随机负载均衡功能，将应用程序的多个连接随机均衡到数据库集群中的各个可用CN。

    例如：

    jdbc:gaussdb://host1:port1,host2:port2,host3:port3/database?autoBalance=shuffle

    JDBC将定期获取整个集群的可用CN列表，比如获取到的列表为：

    host1:port1,host2:port2,host3:port3,host4:port4

    host1、host2和host3仅在首次连接时保证高可用性，后续将使用洗牌（shuffle）算法在刷新后的CN列表中随机选择一个CN节点进行连接。

  • specified：表示开启JDBC负载均衡功能，并且只在用户url中指定的节点上建立连接。

    例如：

    jdbc:gaussdb://host1:port1,host2:port2,host3:port3,host4:port4/database?autoBalance=specified&priorityServers=2

    JDBC 将识别用户指定的 host1 和 host2 为主集群中用于建立连接的节点，而 host3 和 host4 则作为备集群的连接节点。建立连接时，JDBC 会首先在 host1 和 host2 上均匀分配连接。如果主集群中的所有节点（host1 和 host2）均发生故障，JDBC 不会尝试在剩余的集群节点上建立连接。当备节点升级为主节点后，JDBC 会在 host3 和 host4 上均匀分配连接。如果备集群中的所有节点（host3 和 host4）均发生故障，JDBC 同样不会尝试在剩余的集群节点上建立连接。

  • shufflen：表示开启JDBC在指定节点上优先随机负载均衡功能，将应用程序的多个连接首先随机均衡到url上配置的前n个中可用的CN数据库节点。当url上配置前n个节点全部不可用时，连接会随机分配到数据库集群中其他可用CN数据库节点。n为正整数，且小于等于url上配置的CN数量。

    当parseCandidatesByDomain设置为true时，shufflen的优先级配置不生效，这种场景下的优先级使用priorityDomains参数配置。使用shufflen进行负载均衡时，host不能使用IPv6。在多进程建立连接场景下，通过该策略可以实现指定优先节点的负载均衡连接。

    例如：

    jdbc:gaussdb://host1:port1,host2:port2,host3:port3,host4:port4/database?autoBalance=shuffle2

    JDBC将定期获取整个集群的可用CN列表，比如获取到的列表为：

    host1:port1,host2:port2,host3:port3,host4:port4,host5:port5,host6:port6

    Driver将优先从host1、host2中进行随机负载均衡，host1和host2全部不可用才从host3、host4、host5和host6中随机选择CN主机进行连接。

    • 当parseCandidatesByDomain设置为true时，shufflen的优先级配置不生效，这种场景下的优先级使用priorityDomains参数配置。使用shufflen进行负载均衡时，host不能使用IPv6。在多进程建立连接场景下，通过该策略可以实现指定优先节点的负载均衡连接。
    • 例如：
  • false：表示不开启JDBC负载均衡功能和优先级负载均衡功能。

默认值：false

refreshCNIpListTime

获取CN列表的缓存有效时间。JDBC在建连时会检测数据库集群中CN状态，在refreshCNIpListTime时间内可信。超过则状态失效，下次建连时再次获取可用CN的IP列表。

属性类型：Integer

属性单位：s

取值范围：1-9999

默认值：10

建议：根据业务需要进行调整，需要配合autoBalance进行使用。

hostRecheckSeconds

JDBC尝试连接主机后会保存主机状态：连接成功或连接失败。在hostRecheckSeconds时间内保持可信，超过则状态失效。

属性类型：Integer

属性单位：s

取值范围：0 ~

默认值：10

ssl

表示以SSL方式连接数据库。

ssl=true可支持NonValidatingFactory通道和使用证书的方式。

属性类型：Boolean

取值范围：

  • true表示以SSL方式连接数据库。
  • false表示不以SSL方式连接数据库。

默认值：该属性不设置则为空，与false等效。

sslmode

SSL认证方式。

属性类型：String

取值范围：disable、allow、prefer、require、verify-ca、verify-full。

  • disable：不使用SSL安全连接。
  • allow：如果数据库服务器要求使用，则可以使用SSL安全加密连接，但不验证数据库服务器的真实性。
  • prefer：如果数据库支持，那么首选使用SSL连接，但不验证数据库服务器的真实性。
  • require：只尝试SSL连接，不会检查服务器证书是否由受信任的CA签发，且不会检查服务器主机名与证书中的主机名是否一致。
  • verify-ca：只尝试SSL连接，并且验证服务器是否具有由可信任的证书机构签发的证书。
  • verify-full：只尝试SSL连接，并且验证服务器是否具有由可信任的证书机构签发的证书，以及验证服务器主机名是否与证书中的一致。

默认值：该属性不设置则为空，与require等效。

sslgmcipher

指定国密TLS采用的加密算法套件。

属性类型：String

取值范围：

  • ECC_SM4_SM3：支持国密单向/双向认证。
  • ECDHE_SM4_SM3：仅支持国密双向认证。

sslcert

提供客户端证书文件的完整路径。证书类型为End Entity。

属性类型：String

默认值：该属性不设置则为空，读取用户根目录。

sslkey

提供密钥文件的完整路径，使用时需将该密钥转换为DER格式。

openssl pkcs8 -topk8 -outform DER -in client.key -out client.key.pk8 -nocrypt

属性类型：String

默认值：该属性不设置则为空，读取用户根目录。

sslenccert

提供国密TLS客户端加密证书的完整路径，证书类型为End Entity。

属性类型：String

默认值：该属性不设置则为空，读取用户根目录。

sslenckey

提供国密TLS加密密钥文件的完整路径，使用时需将该密钥转换为DER格式。

openssl pkcs8 -topk8 -outform DER -in client_enc.key -out client_enc.key.pk8 -nocrypt

属性类型：String

默认值：该属性不设置则为空，读取用户根目录。

sslrootcert

SSL根证书的文件名。根证书的类型为CA。

属性类型：String

默认值：该属性不设置则为空，读取用户根目录。

sslpassword

SSL密码，提供给ConsoleCallbackHandler使用。

属性类型：String

sslpasswordcallback

SSL密码提供者的类名。

属性类型：String

默认值：com.huawei.gaussdb.jdbc.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler

sslfactory

指定SSLSocketFactory在建立SSL连接时用的类名。

属性类型：String

默认值：该属性不设置则为空。

sslprivatekeyfactory

指定实现私钥解密方法的接口com.huawei.gaussdb.jdbc.ssl.PrivateKeyFactory的实现类的完整限定类名。如果不提供，首先尝试默认的jdk私钥解密算法，如果无法解密，则使用com.huawei.gaussdb.jdbc.ssl.BouncyCastlePrivateKeyFactory，用户需要提供bcpkix-jdk15on.jar包，版本建议1.65以上。

属性类型：String

默认值：该属性不设置则为空，会尝试使用默认的jdk私钥解密算法进行解密。

sslfactoryarg

此值是sslfactory类的构造函数的可选参数（不推荐使用）。

属性类型：String

默认值：该属性不设置则为空。

sslhostnameverifier

主机名验证程序的类名。接口实现javax.net.ssl.HostnameVerifier，默认使用com.huawei.gaussdb.jdbc.ssl.PGjdbcHostnameVerifier。

属性类型：String

默认值：该属性不设置则为空，默认使用com.huawei.gaussdb.jdbc.ssl.PGjdbcHostnameVerifier。

loginTimeout

指建立数据库连接的等待时间。当url配置多IP时，若获取连接花费的时间超过此值，则连接失败，不再尝试后续IP。

loginTimeout时间包括connectTimeout和socketTimeoutInConnecting，计算方式为：loginTimeout=(connectTimeout+连接认证时间+初始化语句执行时间)*节点数量。

须知：
  • 此参数设置后对于多IP而言，时间是尝试连接IP的时间，可能会出现因为设置的值较小导致后面的IP无法连接的问题。例如设置了三个IP，如果loginTimeout为5s，但前两个IP建连总共用了5s，第三个IP会无法进行连接。
  • 当CPU、内存、I/O负载中的任意一项接近100%时，会出现连接慢的现象，可能会导致连接时间超过阈值的问题，可通过以下方式进行问题排查：
    1. 登录连接慢的物理机或通过管理工具查询资源负载：可通过top命令等确认CPU使用率；通过free命令确认内存使用情况；通过iostat命令确认I/O负载；此外还可以通过cm_agent中的监控日志，以及数据库运维平台中的监测记录进行检查。
    2. 针对短时间内大量慢查询导致的峰值负载场景，可通过[数据库服务器的端口号+1]端口连接，查询pg_stat_activity视图；针对慢查询，可以使用pg_terminate_backend(pid int)函数进行查杀会话。
    3. 针对业务量长期超负载情况（即无明显慢查询，或慢查询查杀后但新的查询依然会变成慢查询），应考虑降低业务负载、增加数据库资源的方式进行优化。

属性类型：Integer

属性单位：s（秒）

取值范围：0 ~ 2147483647。0表示已禁用，timeout不生效。

默认值：0

建议：配置后每次建连都会开启一个异步线程，在连接数较多的情况可能会导致客户端压力增大，可以根据业务酌情调整此参数，建议调整为max(connectTimeout, socketTimeoutInConnecting) * 节点数，防止在网络异常情况且第n个IP为主的情况下无法连接。

connectTimeout

用于连接服务器操作系统的超时值。如果连接到服务器操作系统花费的时间超过此值，则连接断开。当url配置多IP时，表示连接单个IP的超时时间。

属性类型：Integer

属性单位：s（秒）

取值范围：0 ~ 2147483647。0表示已禁用，timeout不生效。

默认值：0

socketTimeout

用于socket读取操作的超时值。如果从服务器读取数据流所花费的时间超过此值，则连接关闭。如果不配置该参数，在数据库进程异常情况下，会导致客户端出现长时间等待，建议根据业务可以接受的SQL执行时间进行配置。

说明：

当JDBC侧触发超时且连接关闭时，其下发给数据库侧正在运行的业务会被强制终止。业务强制终止的能力受GUC参数check_disconnect_query控制，设置为on表示支持该能力，设置为off表示不支持该能力。

属性类型：Integer

属性单位：s（秒）

取值范围：0 ~ 2147483647。0表示已禁用，timeout不生效。

默认值：0

socketTimeoutInConnecting

用于控制建连阶段socket读取操作的超时值。在建连阶段，如果从服务器读取数据流超过此阈值，则尝试查找下一个节点建连。

属性类型：Integer

属性单位：s（秒）

取值范围：0 ~ 2147483647

默认值：5

statementTimeout

用于控制connection中statement执行时间的超时值。如果statement执行时间超过此值，则取消该statement执行。

属性类型：Integer

属性单位：ms（毫秒）

取值范围：0 ~ 2147483647。0表示已禁用，timeout不生效。

默认值：0

cancelSignalTimeout

发送取消命令的消息本身可能会阻塞，用于控制取消命令的“connect超时”和“socket超时”。如果取消命令超过指定时间未响应，会中断该连接，减少占用客户端资源。

属性类型：Integer

属性单位：s（秒）

取值范围：0 ~ 2147483647

默认值：10

tcpKeepAlive

TCP保活探测功能的控制开关。

属性类型：Boolean

取值范围：

  • true表示启用TCP保活探测功能。
  • false表示禁用TCP保活探测功能。

默认值：false

logUnclosedConnections

客户端可能由于未调用Connection对象的close()方法而泄漏Connection对象。最终这些对象将被垃圾回收，并且调用finalize()方法。

属性类型：Boolean

取值范围：

  • true表示如果用户没有调用close()方法，finalize()方法将关闭Connection对象。
  • false表示如果用户没有调用close()方法，将不会关闭Connection对象。

默认值：false

assumeMinServerVersion（废弃）

该参数设置要连接的服务器版本。

如assumeMinServerVersion高于或者等于9.0，可以在建立连接时减少相关包的发送，客户端不会发送请求将float精度设置为3（即维持原来设置的float精度2）。

属性类型：String

默认值：该属性不设置则为空。

ApplicationName

表示正在连接的JDBC驱动名称。在CN上查询pgxc_stat_activity表可以看到正在连接的客户端信息，application_name字段表示JDBC驱动名称。

属性类型：String

默认值：PostgreSQL JDBC Driver

connectionExtraInfo

表示驱动是否将当前驱动的部署路径、进程属主用户、url连接配置信息上报到数据库。

属性类型：Boolean

取值范围：

  • true表示JDBC驱动会将当前驱动的部署路径、进程属主用户、url连接配置信息上报到数据库中，记录在connection_info参数里，同时可以在PG_STAT_ACTIVITY和PGXC_STAT_ACTIVITY中查询到。
  • false表示JDBC驱动不会将当前驱动的部署路径、进程属主用户、url连接配置信息上报到数据库中。

默认值：false

autosave

如果查询失败，指定驱动程序应该执行的操作。

属性类型：String

取值范围：always、never、conservative。

  • always表示JDBC驱动程序在每次查询之前设置一个保存点，并在失败时回滚到该保存点。
  • never表示无保存点。
  • conservative表示每次查询都会设置保存点，但是只会在“statement XXX无效”等情况下回滚并重试。

默认值：never

protocolVersion

连接协议版本号。

属性类型：Integer

取值范围：目前仅支持1和3。

  • 设置1时代表连接的是V1服务端。
  • 设置3时代表连接的是V5服务端。

默认值：该属性不设置则为空，与设置为3等效。

prepareThreshold

该值决定PreparedStatement对象在执行多少次以后使用服务端已经解析好的statement。

说明：

不建议通过JDBC，并且使用prepareStatement方法执行涉及密码的语句（例如：CREATE USER user_name WITH PASSWORD '********'；），原因是执行达到prepareThreshold指定次数时，数据库将SQL语句进行缓存，基于安全因素不会将密码进行缓存，该prepareStatement方法再次执行时会报错（Password must contain at least 8 characters.）。

属性类型：Integer

取值范围：0 ~ 2147483647

默认值：5。意味着在执行同一个PreparedStatement对象时，在第五次及以上执行时不再向服务端发送parse消息对statement进行解析，而使用之前在服务端已经解析好的statement。

preparedStatementCacheQueries

表示每个连接中缓存Query（PreparedStatement触发prepareThreshold后会缓存Query）的最大数量。

属性类型：Integer

取值范围：0 ~ 2147483647。0表示禁用缓存。

默认值：256。若在prepareStatement()调用中使用超过256个不同的查询，则最近最少使用的查询缓存将被丢弃。

建议：根据业务需要进行调整。配合prepareThreshold使用。

preparedStatementCacheSizeMiB

表示每个连接中用于缓存Query（PreparedStatement触发prepareThreshold后会缓存Query）的缓冲区空间大小。

属性类型：Integer

属性单位：MB

取值范围：0 ~ 2147483647。0表示禁用缓存。

默认值：5。若缓存了超过5MB的Query，则最近最少使用的查询缓存将被丢弃。

databaseMetadataCacheFields

指定每个连接可缓存的字段的最大个数。

属性类型：Integer

取值范围：0 ~ 2147483647。0表示禁用缓存。

默认值：65536

databaseMetadataCacheFieldsMiB

指定每个连接可缓存的字段的最大值。

属性类型：Integer

属性单位：MB

取值范围：0 ~ 2147483647。0表示禁用缓存。

默认值：5

stringtype

指定调用java.sql.PreparedStatement#setString方法时传给数据库的参数类型。

属性类型：String

取值范围：unspecified、varchar。

  • varchar表示参数将作为varchar类型发送给服务器。
  • unspecified表示参数将不指定类型发送到服务器，服务器将尝试推断适当的类型。

默认值：varchar

batchMode

表示是否使用batch模式连接。

说明：

配置batchMode=on时，执行批量插入/批量修改操作，每一列的数据类型以第一条数据指定的类型为准，若数据类型混用可能会导致报错或者插入的数据异常。

属性类型：String

取值范围：

  • on表示开启batch模式，可以提升批量更新的性能。设置batchMode=on执行成功的返回结果为[count, 0, 0...0]，数组第一个元素为批量影响的总条数。
  • off表示关闭batch模式。设置batchMode=off执行成功的返回结果为[1, 1, 1...1]，数组各元素对应单次修改的影响条数。

默认值：on

建议：如果本身业务框架（例如hibernate）在批量更新时会检测返回值，可以通过调整此参数来解决。

fetchsize

设置数据库连接所创建statement的默认fetchsize。

确定一次fetch在ResultSet中读取的行数，与defaultRowFetchSize功能等价。如果fetchsize和defaultRowFetchSize同时设置，以fetchsize为准。

属性类型：Integer

取值范围：0 ~ 2147483647

默认值：0。表示一次从数据库获取所有结果。

建议：用户根据自身的业务查询数据数量和客户端机器内存情况来配置此参数，设置fetchsize时要关闭自动提交模式（autocommit=false），否则会导致fetchsize无法生效。

defaultRowFetchSize

确定一次fetch在ResultSet中读取的行数。限制每次访问数据库时读取的行数可以避免不必要的内存消耗，从而避免OutOfMemoryException。

属性类型：Integer

取值范围：0 ~ 2147483647

默认值：0。表示一次从数据库获取所有结果。

reWriteBatchedInserts

表示批量插入时，是否重写SQL语句。使用该参数时，要求设置batchMode=off。

属性类型：Boolean

取值范围：

  • true表示批量插入时，可将N条插入语句合并为一条：insert into TABLE_NAME values(values1, ..., valuesN), ..., (values1, ..., valuesN)。
  • false表示批量插入时，不重写SQL语句。

默认值：false

unknownLength

某些GaussDB类型（例如TEXT）没有明确定义的长度，当通过ResultSetMetaData.getColumnDisplaySize和ResultSetMetaData.getPrecision等函数返回关于这些类型的数据时，此参数指定未知长度类型的长度。

属性类型：Integer

取值范围：0 ~ 2147483647

默认值：2147483647

uppercaseAttributeName

该属性开启后会将获取元数据的接口的查询结果转为大写。主要适用场景为数据库中存储元数据全为小写，但要使用大写的元数据作为出参和入参。

涉及到的接口请参见：java.sql.DatabaseMetaData、java.sql.ResultSetMetaData。

说明：

uppercaseAttributeName参数开启后，如果数据库中有小写、大写和大小写混合的元数据，只能查询出小写部分的元数据，并以大写的形式输出，使用前请务必确认元数据的存储是否全为小写以避免数据出错。

属性类型：String

取值范围：

  • true、upper表示将元数据转为大写。
  • false表示以内核GUC参数uppercase_attribute_name配置为准。
  • lower表示将元数据转为小写。

默认值：false

binaryTransfer

是否启用二进制格式发送和接收数据。

属性类型：Boolean

取值范围：

  • true表示启用。
  • false表示不启用。

默认值：false

binaryTransferEnable

启用二进制传输的类型列表。以逗号分隔，例如：binaryTransferEnable=Integer4_ARRAY,Integer8_ARRAY。

OID编号和名称二选一。比如：OID名称为BLOB，编号为88，可以进行如下配置：binaryTransferEnable=BLOB 或 binaryTransferEnable=88。

属性类型：String

默认值：该属性不设置则为空。

binaryTransferDisable

禁用二进制传输的类型列表。以逗号分隔，OID编号和名称二选一。如果binaryTransferDisable与binaryTransferEnable有相同的value，则会禁用。

属性类型：String

默认值：该属性不设置则为空。

blobMode

设置setBinaryStream()方法为不同类型的数据赋值。建议从ORA、MYSQL迁移的系统将该值设定为on，从PG迁移的系统设定为off。

属性类型：String

取值范围：

  • on表示为blob类型数据赋值。
  • off表示为bytea类型数据赋值。

默认值：on

socketFactory

创建与服务器socket连接的类的名称。该类必须实现接口“javax.net.SocketFactory”，并定义无参或单String参数的构造函数。

属性类型：String

socketFactoryArg

此值是上面提供的socketFactory类的构造函数的可选参数，不推荐使用。

属性类型：String

receiveBufferSize

该值用于设置连接流上的SO_RCVBUF。

属性类型：Integer

属性单位：字节

取值范围：-1 ~ 2147483647

默认值：-1。表示不设置缓冲区大小。

sendBufferSize

该值用于设置连接流上的SO_SNDBUF。

属性类型：Integer

属性单位：字节

取值范围：-1 ~ 2147483647

默认值：-1。表示不设置缓冲区大小。

preferQueryMode

指定执行查询的模式。

属性类型：String

取值范围：simple、extended、 extendedForPrepared、extendedCacheEverything。

  • simple模式只发送Q消息，仅支持文本模式，不支持parse与bind；
  • extended模式支持parse、bind和execute；
  • extendedForPrepared模式下只有Prepared Statement对象使用扩展查询，Statement对象只使用简单查询；
  • extendedCacheEverything模式会缓存每个Statement对象所生成的query。

默认值：extended

ApplicationType

设置是否开启分布式写入和查询。该项设置只有数据库处于gtm free场景的情况下才会有效。

属性类型：String

取值范围：not_perfect_sharding_type、perfect_sharding_type

  • not_perfect_sharding_type：开启分布式写入和查询。
  • perfect_sharding_type：默认禁止分布式写入和查询，只有在sql文中加入/* multinode */ 才能执行分布式写入和查询。

默认值：not_perfect_sharding_type

priorityServers

指定url上配置的前n个节点作为主集群被优先连接。应用于流式容灾场景。

例如：jdbc:gaussdb://host1:port1,host2:port2,host3:port3,host4:port4/database?priorityServers=2。即表示host1与host2为主集群节点，host3与host4为容灾集群节点。

属性类型：Integer

取值范围：大于0且小于url上配置的CN数量。

默认值：NULL

usingEip

指定是否使用弹性公网IP实现负载均衡。

须知：

当usingEip=true时，url中的host需使用弹性公网IP；当usingEip=false时，url中的host需使用数据IP，否则会导致priorityn和shufflen负载均衡策略失效。

属性类型：Boolean

取值范围：

  • true表示使用弹性公网IP实现负载均衡。
  • false表示使用数据IP实现负载均衡。

默认值：true

traceInterfaceClass

获取traceId方法接口com.huawei.gaussdb.jdbc.log.Tracer的实现类的完整限定类名。

属性类型：String

默认值：NULL

use_boolean

设置extended模式下setBoolean()方法绑定的oid类型。

属性类型：Boolean

取值范围：

  • false表示绑定int2类型。
  • true表示绑定bool类型。

默认值：false

allowReadOnly

设置是否允许连接开启只读模式。

属性类型：Boolean

取值范围：

  • true允许设置只读模式。
  • false不允许设置只读模式，此时调用connection.setReadOnly(true)不生效，仍可以修改数据。

默认值：true

TLSCiphersSupperted

设置支持的TLS加密套件。

属性类型：String

默认值：TLS_DHE_RSA_WITH_AES_128_GCM_SHA256,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

stripTrailingZeros

设置是否去除numeric类型后的0，仅对ResultSet.getObject(int columnIndex)生效。

属性类型：Boolean

取值范围：

  • true表示去除numeric类型后的0。
  • false表示不去除numeric类型后的0。

默认值：false

enableTimeZone

指定是否启用客户端时区设置。

属性类型：Boolean

取值范围：

  • true表示启用客户端时区设置（获取JVM时区指定数据库时区）。
  • false表示不启用客户端时区设置（使用数据库时区）。

默认值：true

enableStandbyRead

指定是否开启备机读模式。

属性类型：Boolean

取值范围：

  • true表示启用。
  • false表示禁用。

默认值：false

compatibilityTags

将驱动的部分特性恢复到早期版本，以确保前向兼容。可配置一个或多个tag，每个tag代表开启对应的前向兼容性特性，不同tag之间用“,”隔开。目前支持的tag如下：

typeMapInitNull：使用该tag后，兼容驱动早期版本的行为，java.sql.Connection中typeMap的初始值为NULL。如果不使用该tag，初始值为空Map。

须知：

一般不建议使用该参数，除非有明确的前向兼容问题。

属性类型：String

默认值：该属性不设置则为空。

parseCandidatesByDomain

指定是否根据域名获得候选节点。

属性类型：Boolean

取值范围：

  • true表示启用。开启后需要将url中的host信息配置成域名+端口的形式，驱动会基于域名获得IP，生成备节点集合，并可以配合autoBalance参数做负载均衡。
  • false表示禁用。

默认值：false

primaryDomains

指定url上配置的前n个域名作为主集群被优先连接。大于0表示开启主集群被优先连接功能，需要将parseCandidatesByDomain参数设置为true时才能生效。将url中的域名拆分成两个分组，前一个分组为主集群，后一个分组为备集群。发生主备切换后，两个分组交换位置，前一个分组为主集群，后一个分组为备集群。适用于流式容灾和Dorado双集群场景。

例如：jdbc:gaussdb://domain1:port1,domain2:port2,domain3:port3,domain4:port4/database?parseCandidatesByDomain=true&primaryDomains=2，即表示domain1和domain2对应主集群，优先连domain1和domain2对应的IP。如果发生主备切换，将domain3和domain4标记为主集群，优先对domain3和domain4建立连接。

属性类型：Integer

取值范围：0 ~ url上配置的域名数量。

默认值：0。表示关闭。

priorityDomains

指定url上配置的前n个域名作为优先连接的域名。大于0表示开启，需要将parseCandidatesByDomain参数设置为true时才能生效。

例如：jdbc:gaussdb://domain1:port1,domain2:port2,domain3:port3,domain4:port4/database?parseCandidatesByDomain=true&primaryDomains=2&priorityDomains=1，即表示domain1和domain2对应主集群，但是优先连domain1对应的IP，domain2是备用域名，只有domain1不可连后才尝试连domain2。如果发生主备切换，将domain3和domain4标记成主集群，但是优先连domain3对应的IP，domain3不可以连后才尝试连domain4对应的IP。

属性类型：Integer

取值范围：0 ~ url上配置的域名数量。如果配置了primaryDomains，则需要小于primaryDomains配置的数值。

默认值：0。表示关闭。

refreshDomainResolveTime

代表域名解析结果的刷新周期，需要将parseCandidatesByDomain参数设置为true时才能生效，生效后会将url中涉及的域名解析刷新时间设置为指定的数值，并在异步线程中定时更新域名解析结果。

须知：

驱动仅通过应用所在环境的DNS服务获取域名解析结果，为保障域名绑定的变更被驱动及时感知，需要应用所在环境的DNS服务保障域名绑定关系变更后能够及时生效。

属性类型：Integer

属性单位：s（秒）

取值范围：1 ~ 2147483647

默认值：10

oracleCompatible

用户控制驱动接口的ORA兼容特性。

属性类型：String

取值范围：有以下几种取值。
  1. true或on：表示开启驱动侧所有的ORA兼容特性。
  2. false或off：表示关闭驱动侧所有的ORA兼容特性。
  3. "tag1,tag2,tag3"：配置一个或多个tag，tag之间用逗号隔开，表示开启驱动侧部分的ORA兼容特性，每个tag对应一个ORA兼容特性。

    当前支持的tag有：

    • getProcedureColumns：DatabaseMetaData#getProcedureColumns接口的行为兼容ORA行为。
    • getCallableStatementResults：开启后，调用CallableStatement的getLong、getInt、getShort、getByte四个接口时与ORA模式数据库保持一致。在注册出参类型为java.sql.Types#NUMERIC时，调用CallableStatement的getLong、getInt、getShort、getByte接口，能够正常接收out的值，只有out数值超过java数值，数据类型取值范围会提示SQLException异常。
    • batchInsertAffectedRows：reWriteBatchedInserts开启后，执行批量插入接口Statement#executeBatch的返回结果兼容ORA行为。
    • setDateTime：开启后，PBE模式下绑定Date、Time、Timestamp类型参数时，指定具体oid下发至内核。

默认值：false

mCompatible

用户控制驱动接口的M-Compatibility特性。

属性类型：String

取值范围：有以下几种取值。
  • true或on：表示开启驱动侧所有的M-Compatibility特性。
  • false或off：表示关闭驱动侧所有的M-Compatibility特性。
  • "tag1,tag2,tag3"：配置一个或多个tag，tag之间用逗号隔开，表示开启驱动侧部分的M-Compatibility特性，每个tag对应一个M-Compatibility特性。当前支持配置tag为DatetimeAsTimeStampType：开启后，使用java.sql.ResultSet#getObject接口获取datetime数据类型字段时会返回Timestamp类型的对象。

默认值：false

printSqlInLog

指定异常信息或日志中是否输出SQL语句。

属性类型：Boolean

取值范围：

  • true表示启用。
  • false表示禁用。

默认值：true

useGsClobBlobClass

改变使用java.sql.ResultSet#getObject接口获取获取clob字段和blob字段时返回的对象。

属性类型：Boolean

取值范围：

  • 设置为true开启后，使用java.sql.ResultSet#getObject接口获取clob字段时会返回PGClob类型的对象，获取blob字段时会返回PGBlob类型的对象。通过元数据接口java.sql.ResultSetMetaData#getColumnClassName获取clob字段的类型名称会返回java.sql.Clob，获取blob字段的类型名称时会返回java.sql.Blob。
  • 设置为false关闭后，使用java.sql.ResultSet#getObject接口获取clob字段时会返回PGClob类型的对象，获取blob字段时会返回byte[]类型的对象。通过元数据接口java.sql.ResultSetMetaData#getColumnClassName获取clob字段的类型名称会返回java.sql.CLOB，获取blob字段的类型名称时会返回java.sql.BLOB。

默认值：false

sessionType

指定当前会话的类型，根据用户实际取值生成执行计划。

属性类型：String

取值范围：singleNode、globalReadOnly、normal。

  • normal：表示普通会话，根据数据库原有逻辑执行计划。
  • singleNode：表示会话为单节点会话，会话的读写操作支持下推。单节点会话模式是通过CN向指定的目标DN进行1对1的会话模式。需与参数execTargetNode同时使用，设置参数execTargetNode为目标DN节点名称，JDBC会优先连接目标DN节点对应的本地CN节点。
  • globalReadOnly：表示会话为跨节点只读会话模式。该模式下，会正常生成分布式计划，但禁止分布式写操作。

默认值：normal

execTargetNode

表示单节点会话模式下对应的DN节点。此参数需与sessionType同时使用，参数sessionType设置为singleNode模式时生效。

说明：

若参数sessionType设置为singleNode模式，未指定execTargetNode时，效果与sessionType设置为normal一致。

属性类型：String

取值范围：当前集群内的所有DN节点名称。

默认值：NULL

executeUpdateQueryable

指定executeUpdate()方法是否开启执行DQL语句。

说明：

不推荐开启此参数。

属性类型：Boolean

取值范围：

  • true表示启用。开启后，executeUpdate()方法执行DQL语句的返回值为-1，能够得到结果集。
  • false表示禁用。

默认值：false

dbMonitor

指定JDBC是否开启连接监控功能。

说明：
  • 连接监控功能支持监控JDBC端以下指标：应用开启连接的次数、关闭连接的次数、连接异常断开的次数、数据库访问量、客户端机器CPU的使用率、内存的使用率、上下行传输速率、应用端到数据库链路之间的网络时延、抖动、丢包率。
  • 将dbMonitor设置为true，loggerLevel设置为debug，loggerFile设置为filePath，可将客户端的连接监控输出到日志文件filePath中。具体示例参见监控数据库连接。

属性类型：Boolean

取值范围：

  • true表示启用。
  • false表示禁用。

默认值：false

enableStreamingQuery

控制是否开启流式读功能。

流式读功能：读取数据时，服务端一次获取全部数据，发送到客户端socket缓冲区中，缓冲区占满则暂停，有空余则继续向缓冲区中发送数据，同时JVM逐行从缓冲区中读取数据。优势是处理结果快，不会造成JVM内存溢出。劣势是只能向后遍历，数据处理完毕之前或者statement关闭之前，当前连接不能执行其他操作。具体示例参见使用流式读功能。

属性类型：Boolean

取值范围：

  • 设置为true，同时使用statement.setFetchSize(Integer.MIN_VALUE)或者statement.enableStreamingResults()，表示开启流式读功能。
  • 设置为false表示关闭。

默认值：false

yearIsDateType

使用java.sql.ResultSet#getObject接口和java.sql.ResultSet#getString接口获取year数据类型字段时，指定返回的数据对象是否以Date类型呈现。

属性类型：Boolean

取值范围：

  • 设置为true开启后，使用java.sql.ResultSet#getObject接口获取year数据类型字段时会返回Date类型的对象，使用java.sql.ResultSet#getString接口获取year数据时会返回yyyy-mm-dd格式的日期字符串，使用java.sql.ResultSet#getInt/getLong/getShort接口获取数据会返回年份数值。
  • 设置为false关闭后，使用java.sql.ResultSet#getObject接口获取year数据类型字段时会返回Integer类型的对象，使用java.sql.ResultSet#getString接口获取year数据时返回年份的字符串，使用java.sql.ResultSet#getInt/getLong/getShort接口获取数据会返回年份数值。

默认值：true

enableObjectTypeConv

控制是否允许ResultSet接口中getObject(int, Class<?>)方法支持兼容类型转换。当前已支持Integer与Long、Double、BigDecimal类型互转，Clob与String类型互转。

属性类型：Boolean

取值范围：

  • true表示允许兼容类型转换。
  • false表示不允许兼容类型转换。

默认值：false

disasterToleranceCluster

表示在开启负载均衡功能的场景下且JDBC连接数据库的url中只配置容灾集群节点时，判断负载均衡连接到主集群或连接到容灾集群。该参数不可与priorityServers参数共同使用。

属性类型：Boolean

取值范围：

  • true表示开启，会在容灾集群节点进行负载均衡。
  • false表示关闭，会在主集群节点间进行负载均衡。

默认值：false

pgCompatible

用于控制JDBC对SQL语法解析方式是否兼容PG。

属性类型：Boolean

取值范围：

  • true表示语法解析兼容PG，支持一个statement中包含多条SQL，并使用分号进行分隔的使用场景，在开启后不支持执行语句中带有分号的SQL。
  • false表示SQL语句解析方式采用默认行为（不兼容PG）。

默认值：false

setFloat

调用setFloat或者setObject指定类型为float时，传递给内核的Oid是否为float4的Oid。

属性类型：Boolean

取值范围：

  • 设置为true，调用setFloat或者setObject指定类型为float时，传递给内核的Oid为float4。
  • 设置为false，调用setFloat或者setObject指定类型为float时，传递给内核的Oid为float8。

默认值：false

enableGaussArrayAndStruct

开启此功能后，支持将集合和数组类型的投影列或出参获取为GaussArray和GaussStruct对象。

属性类型：Boolean

取值范围：true、false

默认值：false

actualErrorCodeForBatch

用于控制executeBatch接口执行报错时，返回异常的errorCode为0还是实际的错误码。

属性类型：Boolean

取值范围：

  • 设置为true，executeBatch接口执行报错时，返回异常的errorCode为实际的错误码。
  • 设置为false，executeBatch接口执行报错时，返回异常的errorCode为0。

默认值：false

JDBC驱动支持数据库DDL操作修改表结构后正常执行。

jdbc.version_num仅用在建连时向内核传递JDBC版本号，不做其他用途，请勿使用。jdbc.version_num从503.1版本开始支持（此前使用jdbc.version参数完成该功能，后续废弃），jdbc.version_num使用规范如下：

jdbc.version_num

版本

范围

使用规则

内核判断

备注

502xx

505.2

50200-50299

版本内必须先使用最小可用值。

版本号>=502xx（最新设置值）

相关兼容性改动必须同步合入更高版本分支。

501xx

505.1

50100-50199

版本内必须先使用最小可用值。

版本号>=501xx（最新设置值）

相关兼容性改动必须同步合入更高版本分支。

500xx

505.0

50000-50099

版本内必须先使用最小可用值。

版本号>=500xx（最新设置值）

相关兼容性改动必须同步合入更高版本分支。

301xx

503.1

30100-30199

版本内必须先使用最小可用值。

版本号>=301xx（最新设置值）

相关兼容性改动必须同步合入更高版本分支。
父主题： 连接数据库