KingbaseES V8 JDBC连接属性说明

JDBC连接属性

除了标准的连接参数外，JDBC 驱动程序还提供了一些额外的连接参数去指定一些 JDBC 驱动程序的工作方式。这些参数或者可以在 connection URL 中设置，或者可以保存在一个 Properties object 中。以下例子分别使用以上两种方法建立一个不使用转义字符的连接：

String url = "jdbc:kingbase8://localhost:54321/testdb";
java.util.Properties info = new java.util.Properties();
info.put ("user", "system");
info.put ("password", "manager");
Connection con = DriverManager.getConnection(url, info);

String url = "jdbc:kingbase8://localhost:54321/testdb?user=system&password=manager";
Connection con = DriverManager.getConnection(url);

除以上方法外，当连接参数较多时，也可通过配置文件配置连接参数，此时需在连接串中添加参数ConfigurePath来指定配置文件的路径。

以下例子分别使用两种方式来建立读写分离的配置，以集群：node1[192.168.8.128:54321]、node2[192.168.8.223:54322]、node3[192.168.8.130:54323]为例：

只用连接串 开启JDBC读写分离 一主两备：
URL  jdbc:kingbase8://192.168.8.128:54321/test?USEDISPATCH=true
        &SLAVE_ADD=192.168.8.223,192.168.8.130
        &SLAVE_PORT=54322,54323
        &nodeList=node1,node2,node3

连接串+配置文件 开启JDBC读写分离 一主两备：
URL  jdbc:kingbase8://192.168.8.128:54321/test?ConfigurePath=jdbc.conf
jdbc.conf配置文件
USEDISPATCH=true
SLAVE_ADD=192.168.8.223,192.168.8.130
SLAVE_PORT=54322,54323
nodeList=node1,node2,node3

在连接中可以额外指定的连接参数如下列各表所示：

表 3.1.10 认证参数表

参数名称	参数值类型	参数说明	默认值
DBNAME	String	指定要连接的数据库名称（可以直接在JDBC URL中指定）	null
HOST	String	指定服务器的地址（可以直接在JDBC URL中指定）	null
PORT	String	指定服务器的端口号（可以直接在JDBC URL中指定）	null
user	String	指定连接数据库的用户名	null
password	String	指定连接数据库的密码	null
passwordEncryption	String	指定密码的加密方式，目前只支持base64	null

表 3.1.11 协议参数表

参数名称	参数值类型	参数说明	默认值
protocolVersion	String	指定建立连接时采用的通信协议，当前只支持版本3	null

表 3.1.12 预编译缓存控制参数表

参数名称	参数值类型	参数说明	默认值
preferQueryMode	String	指定使用哪种模式发送查询给数据库： "simple"全部语句只发送Q报文，不发送parse/bind/execute报文； "extended"全部语句都发送parse/bind/execute报文； "extendedForPrepared"只有prepare语句才发送parse/bind/execute报文； "extendedCacheEveryting"和"extended"一样并且缓存每一条语句。	extended
prepareThreshold	Integer	指定同一条prepare语句执行多少次后才启用服务器端prepare	5
preparedStatementCacheQueries	Integer	指定prepare语句的最大缓存数目	256
preparedStatementCacheSizeMiB	Integer	指定prepare语句的缓存最大大小（以兆字节为单位）	5

表 3.1.13 元信息控制参数表

参数名称	参数值类型	参数说明	默认值
unknownLength	Integer	指定未知长度类型的返回长度	2147483647
databaseMetadataCacheFields	Integer	指定数据库元数据的最大缓存数目	65536
databaseMetadataCacheFieldsMiB	Integer	指定数据库元数据的缓存最大大小（以兆字节为单位）	5

表 3.1.14 性能扩展参数表

参数名称	参数值类型	参数说明	默认值
defaultRowFetchSize	Integer	获取结果集行数的默认值，0意思是一次获取结果集的所有行	0
disableColumnSanitiser	boolean	指定是否启用禁用列名净化的优化器	false
reWriteBatchedInserts	boolean	指定是否启用优化以重写和折叠批处理的兼容性INSERT语句	false
zipLevel	Integer	指定通信传输压缩的比率，取值范围为0~9的整数值，0表示不进行压缩，9表示最高压缩比率。使用时需依赖C库，通过java.library.path指定其路径。Windows下为compresskb.dll和compresskb.lib（可通过PATH指定其路径），Linux下为libcompresskb.so（通过LD_LIBRARY_PATH指定其路径）。 该功能适用于网络IO为瓶颈（带宽小于100Mb）的情况。该参数需要V8R6C5以上版本的数据库才能支持。 注意：传输压缩，需要双发压缩和解压协议消息，因此会带来额外CPU开销，如果网络不是瓶颈，那么开启压缩反而会降低性能。	0
useFetchSizeInAutoCommit	boolean	指定是否在自动提交模式下使用按需执行的功能。使用时需打开服务器自动提交模式下的按需执行功能，同时指定参数defaultRowFetchSize	false
optimizeBatchedDML	boolean	指定是否开启批量INSERT、UPDATE、DELETE、MERGE优化，批量是指JDBC标准批量处理接口executeBatch。该参数要求待执行SQL必须包含占位符，同时如果设置了reWriteBatchedInserts=true 或者preferQueryMode=simple，那么该参数会被忽略。开启该参数后，批量执行返回的数组第一个位置为所有影响行数之和，其余位置为0	false

表 3.1.15 诊断信息参数表

参数名称	参数值类型	参数说明	默认值
loggerLevel	String	指定日志记录级别。日志记录级别为："OFF", "WARNING", "INFO", "DEBUG", "TRACE"	null
loggerFile	String	指定日志信息文件的保存路径。可以是相对路径，也可以是绝对路径，如果为null则不生成日志文件，而是打印到控制台。如果有指定路径，则只打印到文件。例如：LogFile=e:\logFile.txt	null
logUnclosedConnections	boolean	指定当未显式关闭的连接被垃圾回收时，是否从连接的打开记录堆栈跟踪泄漏源	false
logServerErrorDetail	boolean	指定是否在错误信息里包含服务器错误的详细信息	true

表 3.1.16 会话属性参数表

参数名称	参数值类型	参数说明	默认值
binaryTransfer	boolean	指定是否使用二进制格式发送和接收数据	true
readOnlyMode	String	指定连接设置为只读时的处理行为。 "ignore"表示设置readOnly无效； "transaction"表示当readOnly为true且为非自动提交时事务为只读事务； "always"表示当readOnly为true时，如果为自动提交事务模式，会话将设置为只读，如果为非自动提交模式，事务将开始只读。	transaction
readOnly	boolean	指定连接是否为只读模式	false
binaryTransferEnable	String	指定逗号分隔的类型列表以启用二进制传输。指定OID值或名称。	无默认值
binaryTransferDisable	String	指定逗号分隔的类型列表以禁用二进制传输。指定OID值或名称。重写驱动程序缺省的和binaryTransferEnable设置的值	无默认值
clientEncoding	String	指定客户端的编码格式，值为null时采用jvm的编码格式	null
assumeMinServerVersion	String	假设服务器至少是这个版本	null
ApplicationName	String	指定应用程序的名称	Kingbase8 JDBC Driver
allowEncodingChanges	boolean	指定是否允许更改clientEncoding	false
currentSchema	String	指定要在搜索路径中设置的模式	null
options	String	指定options连接初始化参数	null
hideUnprivilegedObjects	boolean	指定数据库元信息中是否隐藏当前用户没有权限的数据库对象	false
initParams	String	指定用来初始化数据库连接的session级参数，可指定多个，各个参数之间用分号进行分隔，如initParams=client_encoding='UTF8';extra_float_digits=2	null

表 3.1.17 事务控制参数表

参数名称	参数值类型	参数说明	默认值
autosave	String	指定当一个查询失败时驱动如何做: "always"每一个查询前都设置savepoint，失败是都回滚到savepoint； "never"什么都不做; "conservative"每一个查询前都设置savepoint，但是回滚只针对极少情况才做。	never
cleanupSavepoints	booelan	指定是否清除autosave功能在每个语句前设置的保存点	false

表 3.1.18 通信加密参数表

参数名称	参数值类型	参数说明	默认值
ssl	boolean	指定在使用 JDBC 连接时，是否使用 SSL 安全方式传输数据	false
sslmode	String	指定控制 SSL 使用的参数	null
sslfactory	String	指定使用 SSL 的 SSLSocketFactory 类	null
sslfactoryarg	String	指定被转发到 SSLSocketFactory 类的构造函数的参数	null
sslhostnameverifier	String	指定一个实现了 javax.net.ssl.HostnameVerifier ，且可以验证服务器的类	null
sslcert	String	指定客户端SSL证书的位置	null
sslkey	String	指定客户端 PKCS#8 SSL 密钥的位置	null
sslrootcert	String	指定用于对服务器进行身份验证的根证书的位置	null
sslpassword	String	指定客户端ssl密钥的密码（如果设置了 sslpasswordcallback ，则忽略）	null
sslpasswordcallback	String	指定一个实现了 javax.security.auth.callback.CallbackHandler ，且可以为ssl密码处理PasssworCallback的类	null

表 3.1.19 网络控制参数表

参数名称	参数值类型	参数说明	默认值
tcpKeepAlive	Boolean	指定是否打开TCP的心跳保活机制	false
socketTimeout	Integer	指定底层socket receive的超时时间，单位是秒，值可以为任意正整数，“0”表示没有超时，一直等，直到返回	0
loginTimeout	Integer	指定等待数据库建立连接的超时时间，单位是秒	0
connectTimeout	Integer	指定Socket做connect时的超时时间，单位是秒	10
cancelSignalTimeout	Integer	指定发送取消命令的超时时间，单位是秒	10
socketFactory	String	指定用于创建套接字的套接字工厂	null
socketFactoryArg	String	SocketFactory类的构造函数的参数	null
receiveBufferSize	Integer	指定Socket做read时的buffer大小，“-1”意思是用系统默认值	-1
sendBufferSize	Integer	指定Socket做send时的buffer大小，“-1”意思是用系统默认值	-1

表 3.1.20 认证扩展参数表

参数名称	参数值类型	参数说明	默认值
jaasLogin	boolean	指定是否在进行GSSAPI身份验证之前使用JAAS登录	true
jaasApplicationName	String	指定JAAS系统或应用程序登录配置的名称	null
kerberosServerName	String	指定使用GSSAPI进行身份验证时要使用的Kerberos服务名称	null
useSpnego	boolean	指定是否在SSPI身份验证请求中使用SPNEGO	false
gsslib	String	指定强制SSPI或GSSAPI，取值可以为auto、sspi、gssapi	auto
sspiServiceClass	String	指定用于SPN的Windows SSPI服务类	null

表 3.1.21 高可用扩展参数表

参数名称	参数值类型	参数说明	默认值
targetServerType	String	指定要连接的服务器类型，取值可以为any、master、slave、preferSlave	any
loadBalanceHosts	boolean	如果禁用，主机按照给定的顺序连接。如果启用，从合适的候选集合中随机选择启用的主机	false
hostRecheckSeconds	Integer	指定检查主机状态的周期，以防它们发生更改，单位是秒	10
replication	String	指定启动报文的连接参数replication的值(true，database)。布尔值 true 告诉后端进入 walsender 模式，其中可以发出一小组复制命令而不是SQL语句。在 walsender 模式下只能使用简单查询协议。将数据库作为值传递指示walsender连接到dbname参数中指定的数据库，这将允许连接用于从该数据库进行逻辑复制（后端 >= 8.6）	null

表 3.1.22 读写分离配置参数表

参数名称	参数值类型	参数说明	默认值
ConfigurePath	String	指定配置文件的路径，只能在连接串中配置，值为null时，不读取配置文件。当连接参数较多时，可通过配置文件配置连接参数。当文件中配置的连接参数与URL中的参数重复时，会覆盖掉URL中的参数值	null
TransactionDispatchStrategy	Integer	指定事务中的分发策略，1表示事务都不分发，2表示事务中的写语句之前的读语句可以分发。此功能开启需要同时开启读写分离功能	2
USEDISPATCH	boolean	指定是否使用读写分离功能。此配置项关闭JDBC就变成单机JDBC，无读写分离功能	false
HOSTLOADRATE	Integer	指定主机负载率。此功能开启需要同时开启读写分离功能。根据当前发给主机的语句数目与总语句数目的比例与HOSTLOADRATE设置的比例进行比较，当前者大于后者时，发给备机，否则发给主机，当总语句数目达到Integer.MAX_VALUE时，用当前分发的实际比例的分子分母更新当前发给主机的语句数目与总语句数目	0
SLAVE_ADD	String	指定备机地址，可指定多个，用“,”隔开。此功能开启需要同时开启读写分离功能	无
SLAVE_PORT	String	指定备机端口，与备机地址一一对应，可指定多个，用“,”隔开。此功能开启需要同时开启读写分离功能且设置备机地址	无
MASTER_CHECK	boolean	指定是否在新建连接时检查当前连接数据库是否为master，如果不是则去slave中检查有没有master，如果还是找不到就会向上报错。此功能开启需要同时开启读写分离功能	true
MONITORINTERVAL	Integer	指定集群检测线程每次检测的时间间隔，单位是秒。此功能开启需要同时开启读写分离功能和集群备机检测功能。	5
RETRYTIMES	Integer	指定失败重发的最高次数。此功能开启需要同时开启读写分离功能	10
WhiteList	String	指定只读函数列表，可指定多个，各个函数之间用分号分隔	null
BlackList	String	默认情况下认为函数都是只读的，BlackList指定写函数列表，可指定多个，各个函数之间用分号分隔，如：BlackList=updateXXX;writeXXX 这样。 目前只支持函数名字的比较，不支持函数名重载的区分。不与WhiteList同时配置，与WhiteList同时配置时，只有BlackList生效。此功能开启需要同时开启读写分离功能	null
MasterFunctionList	String	指定只发主机，但不改变事务状态的函数语句列表，可指定多个，各个函数之间用分号分隔，如：MasterFunctionList=updateXXX;writeXXX 这样。 目前只支持函数名字的比较，不支持函数名重载的区分。此功能开启需要同时开启读写分离功能	null
TempTable	String	指定临时表，如果是查询临时表的查询语句，则只发主机且不改变事务状态。可指定多个，各个表名之间用分号分隔，如：aaa；bbb这样。 此功能开启需要同时开启读写分离功能	null
BlackSqlList	String	指定只发主机，但不改变事务状态的sql语句列表，可指定多个，可指定多个，各个语句之间用分号分隔，如：BlackSqlList=SET TRANSACTION READ WRITE;BEGIN READ WRITE 这样。此功能开启需要同时开启读写分离功能	null
masterKeyword	String	指定一个包含在注释中的单词，包含该注释的语句只发主机，但不改变事务状态	null
nodeList	String	指定各节点的名称，各节点的名称为./repmgr cluster show命令查询出的Name字段。要求开启读写分离时必须配置此项，不允许为空并要与节点的地址配置顺序完全一致。各个节点名称之间用逗号分隔，如：nodeList=node1,node2,node3	无
readListStrategy	Integer	指定可分发节点选择列表策略，1表示所有在线节点均可分发，2表示只分发主节点和同步备机节点。此功能开启需要同时开启读写分离功能	1

表 3.1.23 兼容扩展参数表

参数名称	参数值类型	参数说明	默认值
escapeSyntaxCallMode	String	指定驱动程序如何将JDBC转义调用语法转换为底层SQL，以调用过程或函数。 "select"表示驱动始终使用select语句； "callIfNoReturn"表示如果没有指定返回参数，则驱动使用call语句，否则驱动使用select语句； "call"表示驱动始终使用call语句。	call
nullConvertEmptyLob	boolean	指定当驱动接收到数据库返回的大对象为null时，驱动返回给上层空的大对象还是null，默认返回空大对象	true
storeCase	String	指定数据库存储SQL标识符的大小写形式,取值可以为lower、upper和original： storeCase为lower时，DatabaseMetaData的storesLowerCaseIdentifiers()返回true，storesUpperCaseIdentifiers()和storesMixedCaseIdentifiers()返回false； storeCase为upper时，storesUpperCaseIdentifiers()返回true，其余二者返回false； storeCase为original时，storesMixedCaseIdentifiers()返回true，其余二者返回false。	lower
structType	String	指定数据库复合类型返回的数据类型,取值可以为Struct（即返回java.sql.Struct）和KBobject（即返回com.kingbase8.util.KBobject），为null时返回KBobject。 注意： a. 如果返回Struct类型，Struct中包含字符串类型的字段值，该值两端有双引号且个数不匹配时，取值会出现错误。 b.如果以Struct类型作为绑定参数，Struct中包含二进制类型的字段值，该值中包含转义字符、中文等，无法正确处理（存值时报错，或存取值不对）。	null
rowidType	String	指定数据库tid类型返回的数据类型,取值可以为rowid（即返回java.sql.RowId）和KBobject（即返回com.kingbase8.util.KBobject），默认值是null，即返回KBobject。	null
stringtype	String	指定bind参数时设置类型为unspecified或者varchar	null