示例 示例1：连接数据库 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 //以下用例以gsjdbc4.jar为例。 //以下代码将获取数据库连接操作封装为一个接口，可通过给定用户名和密码来连接数据库。 public static Connection getConnect(String username, String passwd) { //驱动类。 String driver = "org.postgresql.Driver"; //数据库连接描述符。 String sourceURL = "jdbc:postgresql://$ip:$port/postgres"; Connection conn = null; try { //加载驱动。 Class.forName(driver); } catch( Exception e ) { e.printStackTrace(); return null; } try { //创建连接。 conn = DriverManager.getConnection(sourceURL, username, passwd); System.out.println("Connection succeed!"); } catch(Exception e) { e.printStackTrace(); return null; } return conn; } 示例2：使用Properties对象作为参数建立连接 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 // 以下代码将使用Properties对象作为参数建立连接 public static Connection getConnectUseProp(String username, String passwd) { //驱动类。 String driver = "org.postgresql.Driver"; //数据库连接描述符。 String sourceURL = "jdbc:postgresql://$ip:$port/postgres?autoBalance=true"; Connection conn = null; Properties info = new Properties(); try { //加载驱动。 Class.forName(driver); } catch( Exception e ) { e.printStackTrace(); return null; } try { info.setProperty("user", username); info.setProperty("password", passwd); //创建连接。 conn = DriverManager.getConnection(sourceURL, info); System.out.println("Connection succeed!"); } catch(Exception e) { e.printStackTrace(); return null; } return conn; } 常用参数详情请参见JDBC常用参数参考。

参数 表1 数据库连接参数 参数 描述 url gsjdbc4.jar数据库连接描述符。格式如下： jdbc:postgresql:(数据库名称缺省则与用户名一致) jdbc:postgresql:database jdbc:postgresql://host/database(端口值缺省会使用默认端口） jdbc:postgresql://host:port/database jdbc:postgresql://host:port/database?param1=value1¶m2=value2 jdbc:postgresql://host1:port1,host2:port2/database?param1=value1¶m2=value2 说明： 使用gsjdbc200.jar时，将“jdbc:postgresql”修改为“jdbc:gaussdb” database为要连接的数据库名称。 host为数据库服务器名称或IP地址。 由于安全原因，数据库CN禁止集群内部其他节点无认证接入。如果要在集群内部访问CN，请将JDBC程序部署在CN所在机器，host使用"127.0.0.1"。否则可能会出现“FATAL: Forbid remote connection with trust method!”错误。 建议业务系统单独部署在集群外部，否则可能会影响数据库运行性能。 缺省情况下，连接服务器为localhost。 port为数据库服务器端口。 缺省情况下，会尝试连接到5431端口的database。 param为参数名称，即数据库连接属性。 参数可以配置在URL中，以"?"开始配置，以"="给参数赋值，以"&"作为不同参数的间隔。也可以采用info对象的属性方式进行配置，详情见示例。 value为参数值，即数据库连接属性值。 info 数据库连接属性（所有属性大小写敏感）。常用的属性如下： PGDBNAME：String类型。表示数据库名称（URL中无需配置该参数，自动从URL中解析）。 PGHOST：String类型。主机IP地址。若配置多个CN，它们的IP和端口用“:”分隔，并作为整体以逗号分隔其他CN（URL中无需配置该参数，自动从URL中解析）。详情见示例。 PGPORT：Integer类型。主机端口号。若配置多个CN，它们的端口号和IP用":"分割，并作为整体以逗号分隔其他CN（URL中无需配置该参数，自动从URL中解析）。详情见示例。 user：String类型。表示创建连接的数据库用户。 password：String类型。表示数据库用户的密码。 enable_ce：String类型。其中enable_ce=1表示JDBC支持密态等值查询基本能力。 refreshClientEncryption: String类型。其中refreshClientEncryption=1表示密态数据库支持客户端缓存刷新(默认值为1)。 loggerLevel：String类型。目前支持4种级别：OFF、INFO、DEBUG、TRACE。设置为OFF关闭日志。设置为INFO、DEBUG和TRACE记录的日志信息详细程度不同，缺省值为null，不启用。 loggerFile：String类型。用于指定日志输出路径（目录和文件名）。若只指定文件名，未指定目录则日志生成在客户端运行程序目录；若不配置或配置的路径不存在，则日志会默认通过流输出。此参数已废弃，不再生效，如需使用可通过 java.util.logging 属性文件或系统属性进行配置。 logger：String类型。表示JDBC Driver要使用的日志输出框架。JDBC Driver支持对接用户应用程序使用的日志输出框架。目前仅支持第三方的基于Slf4j-API的日志框架。具体使用方式，请参见6.2.9日志管理。 如果不设置或设置为JDK LOG GER，则JDBC Driver使用JDK LOGGER。 否则必须设置采用基于slf4j-API 第三方日志框架。 allowEncodingChanges：Boolean类型。设置该参数值为“true”进行字符集类型更改，配合characterEncoding=CHARSET设置字符集，二者使用"&"分隔；characterEncoding取值范围{UTF8、GBK、LATIN1、GB18030}，缺省值为false。 说明： 当连接到字符集为GB18030_2022的数据库时，characterEncoding设置为GB18030_2022不生效，会默认使用UTF8，需要设置为GB18030才能正常解析服务端的GB18030_2022字符。 currentSchema：String类型。在search-path中指定要设置的schema。如果Schema名包含除字母、数字、下划线之外的特殊字符，建议在Schema名上加引号，注意加引号后Schema名大小写敏感。如需配置多个Schema，要用“,”进行分隔，包含特殊字符的Schema也需要加引号处理。 例如：currentSchema=schema_a、"schema-b"、"schema/c"。 loadBalanceHosts：Boolean类型。在默认模式下（禁用），顺序连接URL中指定的多个主机。如果启用，则使用洗牌算法从候选主机中随机选择一个主机建立连接。 autoBalance：String类型。 设置为true、balance或roundrobin表示开启JDBC负载均衡功能，将应用程序的多个连接均衡到数据库集群中的各个可用CN。 例如：jdbc:postgresql://host1:port1,host2:port2/database?autoBalance=true JDBC将定期获取（周期刷新可使用参数refreshCNIpListTime配置，默认为10s）整个集群可用CN列表（CN列表中获取的host是数据ip），比如获取到的列表为：host1:port1,host2:port2,host3:port3,host4:port4。 host1和host2在autoBalance启用时，仅在首次连接做高可用用途，后续Driver将从host1、host2、host3和host4中依次选择可用的CN刷新可用CN列表，后续用户新建的connection将使用RoundRobin算法从host1、host2、host3和host4选取CN主机进行连接。 设置为priorityn表示开启JDBC优先级负载均衡功能，将应用程序的多个连接首先均衡到url上配置的前n个中可用的CN数据库节点。当url上配置前n个节点全部不可用时，连接会随机分配到数据库集群中其他可用CN数据库节点。n为数字，不小于0，且小于url上配置的CN数量。 例如：jdbc:postgresql://host1:port1,host2:port2,host3:port3,host4:port4/database?autoBalance=priority2 JDBC将定期获取（周期按refreshCNIpListTime定义）整个集群可用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:postgresql://host1:port1,host2:port2,host3:port3/database?autoBalance=shuffle JDBC将定期获取(周期刷新可使用参数refreshCNIpListTime配置，默认为10S)整个集群的可用CN列表，比如获取到的列表为：host1:port1,host2:port2,host3:port3,host4:port4。 host1:port1,host2:port2,host3:port3,仅在首次连接做高可用，后续连接将在刷新后的CN列表中，使用shuffle算法随机选用一个CN节点进行连接。 设置为specified表示开启JDBC负载均衡功能，并且只在用户url中指定的节点上建连。 例如：jdbc:postgresql://host1:port1,host2:port2,host3:port3,host4:port4/database?autoBalance=specified&priorityServers=2 JDBC将识别用户，指定host1、host2为用户指定主集群中建立连接的节点，host3、host4为备集群指定建立连接的节点。建立连接时，首先在host1、host2上均匀建连，全部故障时不会在集群剩余节点上建连。备升主后，在host3、host4上均匀建连，全部故障不会在集群剩余节点上建连。 设置为false，不开启JDBC负载均衡功能和优先级负载均衡功能。默认为false。 注意： 负载均衡是基于连接级别，不是基于事务级别。如果连接是长连接，并且连接上的负载不均衡，无法保证CN主机上的负载均衡。 负载均衡仅能在分布式场景下使用，集中式环境中不可使用。 在开启负载均衡时，URL中可以配置浮动IP或数据IP，如果配置为浮动IP，系统会根据浮动IP获取对应的数据IP，通过获取的数据IP做负载均衡。因此URL中配置浮动IP或数据IP时，都需要确保数据IP网络连接正常，否则负载均衡功能异常。 refreshCNIpListTime：Integer类型。JDBC定期检测数据库集群中CN状态，获取可用CN的IP列表的时间间隔，默认为10秒。 hostRecheckSeconds：Integer类型。JDBC尝试连接主机后会保存主机状态：连接成功或连接失败。在hostRecheckSeconds时间内保持可信，超过则状态失效。缺省值是10秒。 ssl：Boolean类型。以SSL方式连接。 ssl=true可支持NonValidatingFactory通道和使用证书的方式： 1、NonValidatingFactory通道需要配置用户名和密码，同时将SSL设置为true。 2、配置客户端证书、密钥、根证书，将SSL设置为true。 sslmode：String类型。SSL认证方式。取值范围为：disable、allow、prefer、require、verify-ca、verify-full。 disable：不使用SSL安全连接。 allow：如果数据库服务器要求使用，则可以使用SSL安全加密连接，但不验证数据库服务器的真实性。 prefer：如果数据库支持，那么首选使用SSL连接，但不验证数据库服务器的真实性。 require只尝试SSL连接，不会检查服务器证书是否由受信任的CA签发，且不会检查服务器主机名与证书中的主机名是否一致。 verify-ca只尝试SSL连接，并且验证服务器是否具有由可信任的证书机构签发的证书。 verify-full只尝试SSL连接，并且验证服务器是否具有由可信任的证书机构签发的证书，以及验证服务器主机名是否与证书中的一致。 sslcert：String类型。提供证书文件的完整路径。客户端和服务端证书的类型为End Entity。 sslkey：String类型。提供密钥文件的完整路径。如果客户端证书不是DER格式，使用时将客户端证书转换为DER格式，生成方式请参见连接数据库（以SSL方式）章节。 sslrootcert：String类型。SSL根证书的文件名。根证书的类型为CA。 sslpassword：String类型。提供给ConsoleCallbackHandler使用。 sslpasswordcallback：String类型。SSL密码提供者的类名。缺省值：org.postgresql.ssl.jdbc4.LibPQFactory.ConsoleCallbackHandler。 sslfactory：String类型。提供的值是SSLSocketFactory在建立SSL连接时用的类名。 sslprivatekeyfactory: String类型。提供的值是实现私钥解密方法的接口org.postgresql.ssl.PrivateKeyFactory的实现类的完整限定类名。如果不提供，首先尝试默认的jdk私钥解密算法，如果无法解密，则使用org.postgresql.ssl.BouncyCastlePrivateKeyFactory，用户需要提供bcpkix-jdk15on.jar包，版本建议：1.65以上。 sslfactoryarg：String类型。此值是sslfactory类的构造函数的可选参数（不推荐使用该参数）。 sslhostnameverifier：String类型。主机名验证程序的类名。接口实现javax.net.ssl.HostnameVerifier，默认使用org.postgresql.ssl.PGjdbcHostnameVerifier。 loginTimeout：Integer类型。指建立数据库连接的等待时间。超时时间单位为秒。当url配置多IP时，若获取连接花费的时间超过此值，则连接失败，不再尝试后续IP。缺省值为0，表示禁用。 connectTimeout：Integer类型。用于连接服务器操作的超时值。如果连接到服务器花费的时间超过此值，则连接断开。超时时间单位为秒，值为0时表示已禁用，timeout不生效。当url配置多IP时，表示连接单个IP的超时时间，缺省值为0。 socketTimeout：Integer类型。用于socket读取操作的超时值。如果从服务器读取所花费的时间超过此值，则连接关闭。超时时间单位为秒，值为0时表示已禁用，timeout不生效，缺省值为0。 socketTimeoutInConnecting：Integer类型。用于控制建连阶段socket读取操作的超时值。如果建连时从服务器读取所花费的时间超过此值，则查找下一个节点建连。超时时间单位为秒，默认为5s。 statementTimeout：Integer类型。用于控制connection中statement执行时间的超时值。如果statement执行时间超过此值，则取消该statement执行。超时时间单位为毫秒，值为0表示已禁用，timeout不生效，缺省值为0。 driverInfoMode：String类型。用于控制驱动描述信息的输出模式。取值范围为postgresql、gaussdb，默认缺省值为postgresql，输出postgresql相关的驱动描述信息；设置为gaussdb时输出gaussdb相关的驱动描述信息。 cancelSignalTimeout：Integer类型。发送取消消息本身可能会阻塞，此属性控制用于取消命令的“connect超时”和“socket超时”。超时时间单位为秒，默认值为10秒。 tcpKeepAlive：Boolean类型。启用或禁用TCP保活探测功能。默认为false。 logUnclosedConnections：Boolean类型。客户端可能由于未调用Connection对象的close()方法而泄漏Connection对象。最终这些对象将被垃圾回收，并且调用finalize()方法。如果调用者忽略了此操作，该方法将关闭Connection，缺省值为false。 assumeMinServerVersion（废弃）：String类型。该参数设置要连接的服务器版本。 ApplicationName：String类型。设置正在使用连接的应用程序名称。通过在CN上查询pgxc_stat_activity表可以看到正在连接的客户端信息，显示在application_name列。缺省值为PostgreSQL JDBC Driver。 connectionExtraInfo：Boolean类型。表示驱动是否上报当前驱动的部署路径、进程属主用户到数据库。 取值范围：true或false，默认值为false。设置connectionExtraInfo为true，JDBC驱动会将当前驱动的部署路径、进程属主用户、url连接配置信息上报到数据库中，记录在connection_info参数里；同时可以在PG_STAT_ACTIVITY和PGXC_STAT_ACTIVITY中查询到。 autosave：String类型。共有3种："always", "never", "conservative"。如果查询失败，指定驱动程序应该执行的操作。在autosave=always模式下，JDBC驱动程序在每次查询之前设置一个保存点，并在失败时回滚到该保存点。在autosave=never模式（默认）下，无保存点。在autosave=conservative模式下，每次查询都会设置保存点，但是只会在“statement XXX无效”等情况下回滚并重试，缺省值为never。 protocolVersion：Integer类型。连接协议版本号，目前仅支持1和3。设置1时仅代表连接的是V1服务端。设置3时将采用MD5加密方式，需要同步修改数据库的加密方式，将GUC参数password_encryption_type设置为1，重启集群生效后需要创建用MD5方式加密口令的用户。同时修改pg_hba.conf，将客户端连接方式修改为MD5，用新建用户进行登录（因为设置该值后，只能使用低等级的加密方式（MD5）,降低安全性，所以不推荐设置）。 说明： MD5加密算法安全性低，存在安全风险，建议使用更安全的加密算法。 prepareThreshold：Integer类型。该值决定着PreparedStatement对象在执行多少次以后使用服务端已经准备好的statement。默认值是5，意味着在执行同一个PreparedStatement对象时，在第五次以及以上执行时不再向服务端发送parse消息对statement进行解析，而使用之前在服务端已经解析好的statement。 preparedStatementCacheQueries：Integer类型。该参数确定了每个连接的cache缓存Statement对象生成query的最大个数。默认值为256，若Statement对象生成query个大于256则会将最近最少使用的query从缓存中丢弃。“0”表示禁用缓存。 preparedStatementCacheSizeMiB：Integer类型，该参数确定了每个连接的cache缓存Statement对象所生成query的最大值（以兆字节为单位），默认情况下是5。若缓存了超过5MB的query，则最近最少使用的查询缓存将被丢弃。“0”表示禁用缓存。 databaseMetadataCacheFields：Integer类型。默认值是65536。指定每个连接可缓存的最大字段的个数。“0”表示禁用缓存。 databaseMetadataCacheFieldsMiB：Integer类型。默认值是5。指定每个连接可缓存的字段的最大值，单位是MB。“0”表示禁用缓存。 stringtype：String类型。可选字段为："unspecified"、"varchar"。设置通过setString()方法使用的PreparedStatement参数的类型，如果stringtype设置为VARCHAR（默认值），则这些参数将作为varchar参数发送给服务器。若stringtype设置为unspecified，则参数将作为untyped值发送到服务器，服务器将尝试推断适当的类型。 batchMode：String类型。用于确定是否使用batch模式连接。默认值为on，表示开启batch模式。设置batchMode=on执行成功的返回结果为[count, 0, 0...0]，数组第一个元素为批量影响的总条数；设置batchMode=off执行成功的返回结果为[1, 1, 1...1]，数组各元素对应单次修改的影响条数。 fetchsize：Integer类型。用于设置数据库连接所创建statement的默认fetchsize。默认值为0，表示一次获取所有结果。与defaultRowFetchSize等价。 reWriteBatchedInserts：Boolean类型。批量导入时，该参数设置为true，可将N条插入语句合并为一条：insert into TABLE_NAME values(values1, ..., valuesN), ..., (values1, ..., valuesN);使用该参数时，需设置batchMode=off，缺省值为false。 unknownLength：Integer类型。默认为Integer.MAX_VALUE。某些postgresql类型（例如TEXT）没有明确定义的长度，当通过ResultSetMetaData.getColumnDisplaySize和ResultSetMetaData.getPrecision等函数返回关于这些类型的数据时，此参数指定未知长度类型的长度。 defaultRowFetchSize：Integer类型。确定一次fetch在ResultSet中读取的行数。限制每次访问数据库时读取的行数可以避免不必要的内存消耗，从而避免OutOfMemoryException。缺省值是0，意味着ResultSet中将一次获取所有行。本参数不允许设置为负值。 binaryTransfer：Boolean类型。使用二进制格式发送和接收数据，默认值为“false”。 binaryTransferEnable：String类型。启用二进制传输的类型列表，以逗号分隔。OID编号和名称二选一，例如binaryTransferEnable=INT4_ARRAY,INT8_ARRAY。 比如：OID名称为BLOB，编号为88，可以进行如下配置： binaryTransferEnable=BLOB 或 binaryTransferEnable=88。 binaryTransferDisEnable：String类型。禁用二进制传输的类型列表，以逗号分隔。OID编号和名称二选一。覆盖binaryTransferEnable的设置。 blobMode：String类型。用于设置setBinaryStream方法绑定参数的数据类型，当该值为on时表示setBinaryStream绑定的数据类型为blob类型，为off时表示绑定的数据类型为bytea类型，默认为on。建议从Oracle、Mysql迁移的系统将该值设定为on，从Postgresql迁移的系统设定为off。 socketFactory：String类型。用于创建与服务器socket连接的类的名称。该类必须实现接口“javax.net.SocketFactory”，并定义无参或单String参数的构造函数。 socketFactoryArg：String类型。此值是上面提供的socketFactory类的构造函数的可选参数，不推荐使用。 receiveBufferSize：Integer类型。该值用于设置连接流上的SO_RCVBUF。 sendBufferSize：Integer类型。该值用于设置连接流上的SO_SNDBUF。 preferQueryMode：String类型。共有4种："extended"、"extendedForPrepared"、"extendedCacheEverything"和"simple"。用于指定执行查询的模式，默认值为extended。simple模式只发送Q消息，仅支持文本模式，不支持parse与bind；extended模式会使用parse、bind和execute消息；extendedForPrepared模式下只有Prepared Statement对象使用扩展查询，Statement对象只使用简单查询；extendedCacheEverything模式会缓存每个Statement对象所生成的query。 ApplicationType：String类型。共有2种："not_perfect_sharding_type"、"perfect_sharding_type"。用于设置是否开启分布式写入和查询，默认值为"not_perfect_sharding_type"。not_perfect_sharding_type模式下开启分布式写入和查询，perfect_sharding_type模式下默认禁止分布式写入和查询，只有在sql文中加入/* multinode */ 才能执行分布式写入和查询。该项设置只有数据库处于gtm free场景的情况下才会有效。 priorityServers：Integer类型。此值用于指定url上配置的前n个节点作为主集群被优先连接。默认值为NULL。该值为数字，大于0，且小于url上配置的CN数量。用于流式容灾场景。 例如：jdbc:postgresql://host1:port1,host2:port2,host3:port3,host4:port4,/database?priorityServers=2，即表示host1与host2为主集群节点，host3与host4为容灾集群节点。 usingEip：Boolean类型。此值用于控制是否使用弹性公网IP做负载均衡。默认值为true，表示使用弹性公网IP做负载均衡，false表示使用数据IP做负载均衡。当usingEip=true或者不配置时，url中的host需使用弹性公网IP，usingEip=false时，url中的host需使用数据IP，否则会导致priorityn负载均衡策略失效。 traceInterfaceClass：String类型。默认值为NULL，用于获取traceId的实现类。值是实现获取traceId方法的接口org.postgresql.log.Tracer的实现类的完整限定类名。 use_boolean：Boolean类型。用于设置extended模式下setBoolean方法绑定的oid类型，默认为false，绑定int2类型；设置为true则绑定bool类型。 allowReadOnly：Boolean类型。用于设置是否允许只读模式，默认为true，允许设置只读模式；设置为false则禁用只读模式。 TLSCiphersSupperted：String类型。用于设置支持的TLS加密套件，默认为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：Boolean类型。默认值为false，设置为true则去除numeric类型后的0，仅对ResultSet.getObject(int columnIndex)生效。 enableTimeZone：Boolean类型。默认值为true，用于指定是否启用服务端时区设置，ture表示获取JVM时区指定数据库时区，false表示使用数据库时区。 enableStandbyRead：Boolean类型。默认值为false，用于指定是否开启备机读模式，true表示启用，false表示禁用。 oracleCompatible：String类型。默认为false。用户控制驱动接口的ORA兼容特性。有以下几种取值： 设置为true或on，表示开启驱动侧所有的ORA兼容特性。 设置为false或off，表示关闭驱动侧所有的ORA兼容特性。 设置为“tag1,tag2,tag3”，配置一个或多个tag，tag之间用“,”隔开，表示开启驱动侧部分的ORA兼容特性，每个tag对应一个ORA兼容特性。 当前支持的tag有： getProcedureColumns：DatabaseMetaData#getProcedureColumns接口的行为兼容ORA行为。 batchInsertAffectedRows：reWriteBatchedInserts开启后，执行批量插入接口Statement#executeBatch的返回结果兼容ORA行为。 printSqlInLog：Boolean类型。默认值为true，用于指定异常信息中或日志中是否输出sql语句，true表示启用，false表示禁用。 parseCandidatesByDomain：Boolean类型。默认值false，用于指定是否根据域名获得备节点。true表示启用，false表示禁用。开启后需要将url中的host信息配置成域名+端口的形式，驱动基于域名获得IP，并生成备节点集合，并可以配合autoBalance参数做负载均衡。 primaryDomains：Integer类型。用于指定url上配置的前n个域名作为主集群被优先连接。默认为0，表示关闭。开启时需要大于0，且小于url上配置的域名数量。 例如：jdbc:postgresql://domain1:port1,domain2:port2,domain3:port3,domain4:port4,/database?primaryDomains=2。即表示domain1和domain2对应主机群，优先连domain1和domain2对应的IP。如果发生主备切换，讲domain3和domain4标记为主机群，优先对domain3和domain4建连。 priorityDomains：Integer类型。用于指定url上配置的前n个节点作为优先连接的节点。默认为0，开启时需要大于0，且小于url上配置的域名数量，如果配置了primaryDomains，则需要小于primaryDomains配置的数值。 例如：jdbc:postgresql://domain1:port1,domain2:port2,domain3:port3,domain4:port4,/database?primaryDomains=2&priorityDomains=1。即表示domain1和domain2对应的主机群，但是优先连domain1对应的IP，domain1不可连后才尝试连domain2。如果发生主备切换，将domain3和domain4标记成主集群，但是优先连domain3对应的IP，domain3不可以连后才尝试连domain4对应的IP。 refreshDomainResolveTime：Integer类型。默认为10，单位是秒，最小值为1。代表域名解析结果的刷新周期，需要将parseCandidatesByDomain参数设置为true时才能生效，将url中涉及的域名解析刷新时间设置为指定的数值，并在异步线程中定时更新。 user 数据库用户。 password 数据库用户的密码。 uppercaseAttributeName参数开启后，如果数据库中有小写、大写和大小写混合的元数据，则只能查询出小写部分的元数据，并以大写的形式输出。使用前请务必确认元数据的存储是否全为小写以避免数据出错。

在CopyManager场景使用连接池获取连接，Connection无法转换为BaseConnection 问题分析：BaseConnection为非公开类，需要对连接池对象解封装然后获取原始PGConnection。 处理方法： 对当前对象解包装，返回原始对象以允许访问未公开方法。 1 2 3 4 5 //解封装 PGConnection unwrap = connection.unwrap(PGConnection.class); //转换BaseConnection BaseConnection baseConnection = (BaseConnection)unwrap; CopyManager copyManager = new CopyManager(baseConnection);

JDBC DEV环境没问题，测试环境连接出错报空指针或URI报错uri is not hierarchical 问题分析：某些虚拟环境不支持获取扩展参数，需关闭。 处理方法：在连接时可设置连接参数“connectionExtraInfo=false”，详情可参见使用JDBC连接数据库。 1 jdbc:postgresql://host:port/database?connectionExtraInfo=false

No suitable driver found for XXXX 问题分析：通过JDBC建连时URL格式错误。 处理方法：将URL格式修改为正确的格式。 gsjdbc4.jar对应URL格式为： jdbc:postgresql://host:port/database 在使用pom依赖时对应8.1.x版本 gsjdbc200.jar对应URL格式为：jdbc:gaussdb://host:port/database 在使用pom依赖时对应8.1.x-200版本

Connections could not be acquired from the underlying database! 问题分析：按照新建连接排查项进行排查： 驱动配置是否有误。 数据库连接地址是否有误。 密码或账号是否有误。 数据库未启动或无权访问。 项目未引入对应的驱动jar包。 处理方法： 排查驱动配置，将其修改为正确的驱动配置。 gsjdbc4.jar driver=org.postgresql.Driver gsjdbc200.jar driver=com.huawei.gauss200.jdbc.Driver 排查数据库连接地址，将其修改为正确的数据库连接地址。 gsjdbc4.jar对应 jdbc:postgresql://host:port/database gsjdbc200.jar对应jdbc:gaussdb://host:port/database 排查用户名密码是否为数据库用户名或密码，将其修改为正确的数据库用户名或密码。 排查数据库是否启动或有权限访问。 检查使用的JDBC驱动是gsjdbc4.jar还是gsjdbc200.jar，请使用正确JDBC驱动jar包。 gsjdbc4.jar：与PostgreSQL保持兼容，其中类名、类结构与PostgreSQL驱动完全一致，曾经运行于PostgreSQL的应用程序可以直接移植到当前系统中使用。 gsjdbc200.jar：如果同一JVM进程内需要同时访问PostgreSQL及 GaussDB (DWS) 请使用该驱动包。该包主类名为“com.huawei.gauss200.jdbc.Driver”（即将“org.postgresql”替换为“com.huawei.gauss200.jdbc”），数据库连接的URL前缀为“jdbc:gaussdb”，其余与gsjdbc4.jar相同。

Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections. 问题分析：可能原因为客户端与服务端网络不通、或端口错误或待连接CN异常。 处理方法： 客户端ping服务端IP，看网络是否畅通，网络不通则解决网络问题。 检查URL中连接CN的端口是否正确，端口不正确修改为正确的端口（默认为8000）。

conflict 问题分析：JDBC jar包和应用程序冲突。例如JDBC和应用程序拥有相同路径相同名称的类导致： gsjdbc4.jar和开源postgresql.jar冲突，两者具有完全相同的类名。 gsjdbc4.jar 由于 IAM 特性引入了一些其他工具，例如fastjson，和应用程序中的fastjson冲突。 处理方法： 针对和开源postgresql.jar的冲突，DWS提供了gsjdbc200.jar，使用和开源驱动不同的url格式和驱动路径，驱动名由org.postgresql.Driver修改为com.huawei.gauss200.jdbc.Driver，URL格式由org:postgresql://host:port/database改为jdbc:gaussdb://host:port/database，彻底解决了和开源jar包的冲突。 针对JDBC引入的jar和应用程序中引入jar的冲突，可以通过maven的shade修改了jar中类的路径，解决此类冲突。 排查使用的JDBC驱动是gsjdbc4.jar还是gsjdbc200.jar，如果是gsjdbc4.jar应该替换为gsjdbc200.jar，尝试建立连接。 对于pom依赖，将对于8.1.x版本替换为8.1.x-200版本。

org.postgresql.util.PSQLException: FATAL: terminating connection due to administrator command Session unused timeout 问题分析：会话超时导致连接断开。 处理方法：排查CN和客户端JDBC上的超时配置，按业务实际情况调长超时时间或关闭超时设置。 查看报错的CN日志，如果有session unused timeout这样的日志，说明是会话超时导致的。 解决办法： 登录控制台单击指定集群名称。 在左侧导航栏选择“参数修改”，搜索参数“session_timeout”查看超时时间参数。 将session_timeout的CN、DN参数值设置为0，详情可参见修改数据库参数。

获取结果集中光标的位置 对于可滚动的结果集，可能会调用定位方法来改变光标的位置。JDBC驱动程序提供了获取结果集中光标所处位置的方法。获取光标位置的方法如表3所示。 表3 获取结果集光标的位置 方法 描述 isFirst() 是否在一行。 isLast() 是否在最后一行。 isBeforeFirst() 是否在第一行之前。 isAfterLast() 是否在最后一行之后。 getRow() 获取当前在第几行。

获取结果集中的数据 ResultSet对象提供了丰富的方法，以获取结果集中的数据。获取数据常用的方法如表4所示，其他方法请参考JDK官方文档。 表4 ResultSet对象的常用方法 方法 描述 int getInt(int columnIndex) 按列标获取int型数据。 int getInt(String columnLabel) 按列名获取int型数据。 String getString(int columnIndex) 按列标获取String型数据。 String getString(String columnLabel) 按列名获取String型数据。 Date getDate(int columnIndex) 按列标获取Date型数据。 Date getDate(String columnLabel) 按列名获取Date型数据。

在结果集中定位 ResultSet对象具有指向其当前数据行的光标。最初，光标被置于第一行之前。next方法将光标移动到下一行；因为该方法在ResultSet对象没有下一行时返回false，所以可以在while循环中使用它来迭代结果集。但对于可滚动的结果集，JDBC驱动程序提供更多的定位方法，使ResultSet指向特定的行。定位方法如表2所示。 表2 在结果集中定位的方法 方法 描述 next() 把ResultSet向下移动一行。 previous() 把ResultSet向上移动一行。 beforeFirst() 把ResultSet定位到第一行之前。 afterLast() 把ResultSet定位到最后一行之后。 first() 把ResultSet定位到第一行。 last() 把ResultSet定位到最后一行。 absolute(int) 把ResultSet移动到参数指定的行数。 relative(int) 向前或者向后移动参数指定的行。

设置结果集类型 不同类型的结果集有各自的应用场景，应用程序需要根据实际情况选择相应的结果集类型。在执行SQL语句过程中，都需要先创建相应的语句对象，而部分创建语句对象的方法提供了设置结果集类型的功能。具体的参数设置如表1所示。涉及的Connection的方法如下： 1 2 3 4 5 6 7 8 //创建一个Statement对象，该对象将生成具有给定类型和并发性的ResultSet对象。 createStatement(int resultSetType, int resultSetConcurrency); //创建一个PreparedStatement对象，该对象将生成具有给定类型和并发性的ResultSet对象。 prepareStatement(String sql, int resultSetType, int resultSetConcurrency); //创建一个CallableStatement对象，该对象将生成具有给定类型和并发性的ResultSet对象。 prepareCall(String sql, int resultSetType, int resultSetConcurrency); 表1 结果集类型 参数 描述 resultSetType 表示结果集的类型，具体有三种类型： ResultSet.TYPE_FORWARD_ONLY：ResultSet只能向前移动。是缺省值。 ResultSet.TYPE_SCROLL_SENSITIVE：在修改后重新滚动到修改所在行，可以看到修改后的结果。 ResultSet.TYPE_SCROLL_INSENSITIVE：对可修改例程所做的编辑不进行显示。 说明： 结果集从数据库中读取了数据之后，即使类型是ResultSet.TYPE_SCROLL_SENSITIVE，也不会看到由其他事务在这之后引起的改变。调用ResultSet的refreshRow()方法，可进入数据库并从其中取得当前游标所指记录的最新数据。 resultSetConcurrency 表示结果集的并发，具体有两种类型： ResultSet.CONCUR_READ_ONLY：如果不从结果集中的数据建立一个新的更新语句，不能对结果集中的数据进行更新。 ResultSet.CONCUR_UPDATEABLE：可改变的结果集。对于可滚动的结果集，可对结果集进行适当的改变。

参数 表1 数据库连接参数 参数 描述 url gsjdbc4.jar数据库连接描述符。格式如下： jdbc:postgresql:database jdbc:postgresql://host/database jdbc:postgresql://host:port/database jdbc:postgresql://host:port[,host:port][...]/database 说明： 使用gsjdbc200.jar时，将“jdbc:postgresql”修改为“jdbc:gaussdb” database为要连接的数据库名称。 host为数据库服务器名称或IP地址，当集群绑定弹性负载均衡(ELB)时，应设置为ELB的IP地址。 连接GaussDB(DWS)的机器与GaussDB(DWS)不在同一网段时，host指定的IP地址应为Manager界面上所设的mppdb.coo.cooListenIp2（应用访问IP）的取值。 由于安全原因，数据库CN禁止集群内部其他节点无认证接入。如果要在集群内部访问CN，请将JDBC程序部署在CN所在机器，host使用"127.0.0.1"。否则可能会出现“FATAL: Forbid remote connection with trust method!”错误。 建议业务系统单独部署在集群外部，否则可能会影响数据库运行性能。 port为数据库服务器端口。缺省情况下，会尝试连接到localhost的8000端口的database。 支持多ip端口配置形式，jdbc自动实现了负载均衡，多ip端口配置形式是采取随机访问+failover的方式，这个过程系统会自动忽略不可达IP。 以","隔开，例如jdbc:postgresql://10.10.0.13:8000,10.10.0.14:8000/database 使用JDBC连接集群时集群链接地址只支持指定jdbc连接参数，不支持增加变量参数。 info 数据库连接属性。常用的属性如下： user：String类型。表示创建连接的数据库用户。 password：String类型。表示数据库用户的密码。 ssl：Boolean类型。表示是否使用SSL连接。 loggerLevel：string类型。为LogStream或LogWriter设置记录进DriverManager当前值的日志信息量。目前支持"OFF"、"DEBUG"和"TRACE"。 值为"DEBUG"时，表示只打印DEBUG级别以上的日志，将记录非常少的信息。值等于TRACE时，表示打印DEBUG和TRACE级别的日志，将产生详细的日志信息。默认值为OFF，表示不打印日志。 prepareThreshold：integer类型。用于确定在转换为服务器端的预备语句之前，要求执行方法PreparedStatement的次数。缺省值是5。 batchMode : boolean类型，用于确定是否使用batch模式连接。 fetchsize ： integer类型，用于设置数据库链接所创建statement的默认fetchsize。 ApplicationName：string类型。应用名称，在不做设置时，缺省值为PostgreSQL JDBC Driver。 allowReadOnly:boolean类型，用于设置connection是否允许设置readonly模式，默认为false，若该参数不被设置为true，则执行connection.setReadOnly不生效。 blobMode:string类型，用于设置setBinaryStream方法为不同的数据类型赋值，设置为on时表示为blob数据类型赋值，设置为off时表示为bytea数据类型赋值，默认为on。 connectionExtraInfo：Boolean类型。表示驱动是否上报当前驱动的部署路径、进程属主用户到数据库。 说明： 取值范围：true或false，默认值为true。设置connectionExtraInfo为true，JDBC驱动会将当前驱动的部署路径、进程属主用户上报到数据库中，记录在connection_info参数（参见connection_info）里；同时可以在PG_STAT_ACTIVITY和PGXC_STAT_ACTIVITY中查询到。 user 数据库用户。 password 数据库用户的密码。

示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 //以下用例以gsjdbc4.jar为例，如果要使用gsjdbc200.jar，请替换驱动类名（将代码中的“org.postgresql”替换成“com.huawei.gauss200.jdbc”）与连接URL串前缀（将“jdbc:postgresql”替换为“jdbc:gaussdb”）。 //以下代码将获取数据库连接操作封装为一个接口，可通过给定用户名和密码来连接数据库。 public static Connection GetConnection(String username, String passwd) { //驱动类。 String driver = "org.postgresql.Driver"; //数据库连接描述符。 String sourceURL = "jdbc:postgresql://10.10.0.13:8000/postgres?currentSchema=test"; Connection conn = null; try { //加载驱动。 Class.forName(driver); } catch (ClassNotFoundException e ){ e.printStackTrace(); return null; } try { //创建连接。 conn = DriverManager.getConnection(sourceURL, username, passwd); System.out.println("Connection succeed!"); } catch (SQLException e) { e.printStackTrace(); return null; } return conn; }