跳转至

初始化驱动

初始化驱动

本章节重点介绍如何在应用中装载驱动并初始化

引入驱动

任何使用JDBC的程序都可以按照下面的方式引入java.sql包

import java.sql.*;

注意： 你不应该直接引入com.seaboxsql包，除非你使用的不是标准SeaboxSQL扩展

装载驱动

应用中不用明确的装载com.seaboxsql.Driver类，因为sdjdbc驱动包支持Java服务提供机制(JAVA Service Provider)。当应用连接SeaboxSQL时JVM会自动装载驱动，只要驱动的Jar包所在路径被正确的包含在classpath中即可。

注意: Java 1.6之前的版本，应用需要自己装载驱动，可以通过Class.forName("com.seaboxsql.Driver");或将驱动类名称作为参数传递给JVM java -Djdbc.drivers=com.seaboxsql.Driver example.ImageViewer

原有的装载驱动方式现在仍然被支持，但不是必须的。

连接数据库

在JDBC中，数据库以一个URL形式呈现。对于SeaboxSQL，可以表达为以下几种形式：

  • jdbc:seaboxsql:database

  • jdbc:seaboxsql:/

  • jdbc:seaboxsql://host/database

  • jdbc:seaboxsql://host/

  • jdbc:seaboxsql://host:port/database

  • jdbc:seaboxsql://host:port/

其中的参数含义如下：

host

需要连接的服务器主机名，默认为localhost。如果使用IPV6形式封装host参数，应该用方括号，例如

jdbc:seaboxsql://[::1]:5740/accounting
port
其中的参数含义如下：
host
需要连接的服务器主机名，默认为localhost。如果使用IPV6形式封装host参数，应该用方括号，例如 
jdbc:seaboxsql://[::1]:5740/accounting
port
数据库服务的侦听端口，默认为SeaboxSQL的标准端口(5432)。
database

数据库名，默认是连接与用户名相同的数据库

为了连接数据库，你需要从JDBC中获得Connection实例，可以调用DriverManager.getConnection()方法，例如：

Connection db = DriverManager.getConnection(url, username, password);

连接参数

除了标准的连接参数以外，JDBC驱动还支持一系列的可选属性(参数)，用以定义额外的驱动行为。这些属性可以在连接数据库的URL中定义，也可以放在传递给DriverManager.getConnection的Properties对象中。下面的例子展示了两种建立SSL连接的方法

如果URL和Properties对象中同时对某个属性进行了定义，则Properties中的会被忽略。

String url = "jdbc:seaboxsql://localhost/test";
Properties props = new Properties();
props.setProperty("user","fred");
props.setProperty("password","secret");
props.setProperty("ssl","true");
Connection conn = DriverManager.getConnection(url, props);

String url = "jdbc:seaboxsql://localhost/test?user=fred&password=secret&ssl=true";
Connection conn = DriverManager.getConnection(url);
user 字符串
用于与数据库建立连接的用户
password 字符串
数据库的用户密码
options 字符串

定义连接初始化的可选参数

该属性的值可以包含空格和其他特殊字符，在URL中该项需要适当的进行编码。空格会被用来分隔命令行参数，除非使用了转义字符''; \表示反斜杠字符

ssl 布尔
连接时使用SSL，驱动编译时必须带有SSL才可以使用该选项。这个属性并不需要带有具体数值的参数，他仅仅声明了一个SSL连接。为了跟将来的版本兼容，建议最好设为true。更多信息请参考第4章SSL的使用
sslfactory 字符串
该参数提供的信息用于建立SSL连接时作为SSLSocketFactory使用的类名。更多信息请参考定制SSLSocketFactory章节
sslfactoryarg 字符串
这个参数是可选的，主要用于上面sslfactory类的构造过程。更多信息参考定制SSLSocketFactory
sslmode 字符串

参数可选的值为disable、allow、prefer、require、verify-ca和verify-full。其中require、allow和prefer默认为无效的SSL factory并且不对主机名称或认证合法性进行检查。verify-ca对证书有效性进行查验，但不检查主机名。verify-full会检查证书有效，并检查主机名是否匹配。

这项配置需要客户端保存服务器的认证信息，请参考“客户端设置”部分

sslcert 字符串

认证文件的全路径，默认为 /defaultdir/seaboxsql.crt，可以是PEM编码的X509v3认证

注意： 默认*nix下默认的是${user.home}/.seaboxsql/，Windows下默认为%appdata%/seaboxsql/

sslkey 字符串

密钥文件的全路径，默认为/default/seaboxsql.pk8

*注意: * 密钥文件必须是PKCS-8 DER格式。PEM密钥可以通过如下命令转化为DER格式：openssl pkcs8 -topk8 -inform PEM -in my.key -outform DER -out my.key.der -v1 PBE-MD5-DES

sslrootcert 字符串
SSL根文件的名称，默认为defaultdir/root.crt，可以是PEM编码的X509v3认证
sslhostnameverifier 字符串
主机名认证的类名。默认使用com.seaboxsql.ssl.SDjdbcHostnameVerifier
sslpasswordcallback 字符串
提供SSL密码的类名，默认为com.seaboxsql.ssl.jdbc.LibPQFactory.ConsoleCallbackHandler
sslpassword 字符串
供ConsoleCallbackHandler使用
sendBufferSize 整型
连接数据流的SO_SNDBUF
recvBufferSize 整型
连接数据流的SO_RCVBUF
protocolVersion 整型
驱动支持的V3前后端协议版本。V3协议在7.4章节有介绍，驱动会默认尝试使用V3协议进行连接。
loggerLevel 字符串
驱动的日志级别，允许的值为OFF、DEBUG和TRACE。用于控制驱动中java.util.logging.Logger记录日志的级别，DEBUG详细记录，TRACE详尽记录。该选项通常用于驱动的调试和一般的SQL查询调试
loggerFile 字符串
输出的日志文件名。如果设置了改变量，日志模块会使用java.util.loggingFileHandler写指定的文件。如果没有指定文件或不能创建文件，则使用java.util.logging.ConsoleHandler替代。该参数应该配合loggerLevel来使用。
allowEncodingChanges 布尔
当使用V3协议时，驱动会监视服务端配置参数改变，这些参数终端用户时接触不到的。client_encoding设置由驱动来完成和修改。如果驱动觉察到了其发生变化，那么连接被终止。但有一种情况下例外，使用copy命令操作服务端文件系统内的某个文件。定义该文件的编码意味着改变client_encoding设置。JDBC团队认为这是COPY命令的一个缺陷，希望提供将来能提供一个可选编码的方式来解决，但现在只能用这个参数来控制。请你只在需要copy时覆盖客户端编码的情况下开启该参数。
logUnclosedConnections 布尔
客户端可能会调用close()失败，而导致连接对象残留(泄露)。如果使用者忽略了这个问题，最终这些对象会被进行垃圾回收，而且finalize()会被调用使连接关闭。使用中介函数finalize()仅仅是权宜之计。增加URL参数logUnclosedConnection就是为了帮助开发人员发现并正确的处理这种泄露问题。他会捕捉每个连接打开时的堆栈，如果finalize()被调用但连接没有正确被关闭，则会打印前面保存的堆栈到日志。
autosave
定义如果查询失败，驱动该如何处理。在autosave=always模式下，JDBC驱动为每个查询设置保存点，一旦失败则回滚到保存点。在autosave=never(默认)模式下，不会创建保存点。autosave=conservative模式下，会单独为每个查询创建保存点，但是只有在极特殊的情况下JDBC会回滚，例如缓存的声明不能更改返回类型，或非法的声明。
cleanupSavePoints
是否释放声明之前，自动保存模式下创建的SAVEPOINT。该操作为了避免超出共享缓存的承受能力，例如执行1千条查询后会占用很多共享缓存。该参数默认为false
binaryTransferEnable 字符串
逗号分隔的可以二级制传输的类型列表，使用OID数字或名称。
binaryTransferDisable 字符串
逗号分隔的不可以二级制传输的类型列表，使用OID数字或名称。覆盖驱动中的默认数值，以及binaryTransferEnable中设定的数值。
prepareThreshold 整型
设定使用Server端准备声明前PreparedStatement执行的数量。默认值为5，表示在第五个相同的PreparedStatement对象执行时开始使用服务端的声明。关于服务端准备声明的细节请参考Server Prepared Statements章节。
preparedStatementCacheQueries 整型
每个连接缓存查询的数量。默认是256，如果在prepareStatement()调用中有多余256个不同的查询，则最近使用的会被丢弃。缓存机制更有利于应用的执行，哪怕是执行结束后准备好的声明已经被关闭了。本参数设为0时不缓存任何相关记录。
preparedStatementCacheSizeMiB 整型
查询缓存(参考preparedStatementCacheQueries)的最大空间(MB)。默认时5MB，超过5MB时最近的内容会被丢弃掉。此项设置要避免出现OutofMemoryError错误。设定为0时不缓存任何信息。
preferQueryMode 字符串
定义用什么模式完成针对数据库的查询操作，simple | extended | extendedForPrepared | extenedCacheEverything。simple模式意味着没有参数，没有绑定，只使用文本模式。extended总是使用bind/execute消息，extendedForPrepared只为准备声明而扩展，extendedCacheEverything表示使用扩展协议并在查询缓存中尝试保留每一个声明(包含在Statement.execute(String sql))。 默认是extended
defaultRowFetchSize 整型
定义一次fetch操作从ResultSet中获得的结果行数。使用该参数对行数进行有效限制可以避免不必要的内存消耗，以免引发OutofMemoryExcepiton问题。
loginTimeout 整型
定义建立数据库连接的等待时间，单位是秒。
connectTimeout 整型
socket连接操作时的超时时间。如果建立连接花费时间超过该数值，那么不成功。这里时间单位是秒，等于0意味着该设置不生效。
socketTImeout 整型
socket读操作的超时时间。如果从服务器端读取数据超过该数值，则连接关闭。该参数可用于强制查询超时或者检查网络问题。单位是秒，等于零表示无效。
cancelSignalTimeout 整型
Cancel命令可以在自己的连接上额外外带数据，所以取消信息可能会让自己卡住。这个参数控制连接超时、socket超时，用于取消命令。该参数的单位是秒，默认10秒
tcpKeepAlive 整型
打开或关闭TCP keep-alive探测，默认关闭。
unknownLength 整型
某些seaboxsql数据类型，例如：TEXT，没有确定的长度。当使用ResultSetMetaData.getColumnDisplaySize和ResultSetMetaData.getPrecision这样的函数返回这些类型的meta-data时，必须提供一个数值，这样各种客户端能够知道他们将会看到什么样的数据。这个参数就是定义未知长度数据类型的长度信息。
stringtype 字符串
通过SetString绑定PrepareStatement参数集合时定义类型。如果stringtype设置为VARCHAR(默认)，该数值会当作vachar的参数发送到服务端。如果stringtype设置为unspecified，该数值将会作为未定义类型的值发送得到服务端，然后服务端尝试推断出适当的类型。这在某些场景下非常有用，假定已有使用setString()的应用，想要设置参数为其他明确的类型，例如整型，但无法修改应用到对应的类型函数setInt()。
kerberosServerName 字符串
使用GSSAPI认证时Kerberos服务名称。等价于libpq的SDKRBSRVNAME环境变量，默认为"seabox"
jaasApplicationName 字符串
JAAS系统或应用登录配置的名称
jaasLogin 布尔
定义在GSSAPI认证前是否进行JAAS登录。如果设置为true(默认)，驱动在进行认证前，会尝试通过配置指定的JAAS模式(例如Krb5LoginModule)登录，然后获得GSS证书。如果想跳过JAAS登录，例如使用内置GSS实现来获得证书，可以将该变量设置为false。
ApplicationName 字符串
定义使用该连接的应用名称。使用该设置可以让数据据管理员查看到是什么应用连接到了服务器，并可以通过sdstatactivity查看该应用对资源的使用情况。
gsslib 字符串

当服务端需要Kerberos或SSPI认证时，强制使用SSPI或GSSAPI。允许的字符串为auto(默认)、sspi和gssapi。

当参数设定为auto，如果服务器请求SSPI认证，JDBC客户端在Windows下运行，并且Waffle库在CLASSPATH路径中，那么会尝试SSPI过程。否则就会使用基于JSSE的Kerberos/GSSAPI。注意，该行为与libpq并不是完全对应。

gssapi模式强制使用JSSE的GSSAPI，那马是SSPI可用，这与9.4之前的行为相匹配。

如果是在非Windows平台上，或SSPI不可用，强制使用sspi模式会引发PSQLException异常 为了让SSPI和SdJDBC配合使用，必须确认waffle-jna library并且相应的依赖都包含在CLASSPATH中。SdJDBC的jar包中并不包含waffle-jna。

sspiServiceClass 字符串

定义Windows SSPI服务类名称，该类是SPN中服务类别的一部分，默认为SEABOX，采用默认值几乎总是有效的。

参见：SSPI认证(Sd文档) Service Principal Names(MSDN), DsMakeSpn(MSDN) Configuring SSPI(Sd wiki)

本参数在非windows平台中不生效

useSpnego 布尔
SSPI认证请求中是哟ingSPNEGO
sendBufferSize 整型
连接数据流的SO_SNDBUF大小
receiveBufferSize 整型
连接数据流的SO_RCVBUF大小
readOnly 布尔
将连接设定为只读模式
disableColumnSanitiser 布尔
控制是否开启列名的sanitiser优化，默认值为off。
assumeMinServerVersion 字符串
假定server的最小版本，该参数能够在连接时让一些优化起作用。
CurrentSchema 字符串
定义搜索路径中的一个或多个(逗号分隔)schema，该schema用于解决unqualified object names used in statements over this connection
targetServerType 字符串
要连接的服务器的类型，可选的数值为any、master、slave、secondary、preferSlave和preferSecondary。master和slave的区别在于如果server允许写，当前操作是否能被观察到。preferSecondary表示如果候选服务器可用，那么尝试进行连接，否则转为连接master。
hostRecheckSeconds 整型
JVM内主机状态缓存的保留时间，默认10秒。
loadBalanceHosts 布尔
默认模式（disabled）下，主机按照给定的顺序连接。enable状态下，从可选的主机集合中随机的选择进行连接。
socketFactory 字符串
改参数设定建立socket连接时SocketFactory使用的类名。可以使用unix socket来代替普通socket。由socketFactory声明的类名必须继承javax.net.SocketFactory，并对驱动的类加载器有效。这个类不能有实参构造器，或一个使用String实参的构造器。这个由socketFactoryArg提供的实参是可选的。
socketFactoryArg (deprecated) 字符串
上面socketFactory类构造器中的可选实参，
reWriteBatchedInserts 布尔
该参数改变批量insert操作的模式，将多条insert合并为单条批量插入语句会得到2-3倍的性能提升。
replication 字符串

连接参数包含在连接启动信息中进行传输。这个参数包括两个数值，"true"和database。前者通知服务端进入walsender模式，该情况下采用一个小的回复命令集合来代替SQL声明。只有简单的查询协议可以使用walsender模式。传递database能够让walsender连接到dbname参数中指定的数据库，进而在数据库进行回应时能够使用该连接。

该参数应该与assumeMinServerVersion >= 9.4时一同使用

连接错误恢复

可以通过逗号分隔符在URL中定义多个节点(主机或端口)实现简单的错误恢复，JDBC会逐个尝试进行连接直到成功。如果都失败了，则会抛出连接异常。例如

jdbc:seaboxsql://host1:port1,host2:port2/database

在单节点多实例的高可用环境下，这种连接错误恢复机制非常有用。例如，在基于流复制的seabox或者seaboxmpp集群上。应用可以创建两个连接池，一个数据原用于写操作，另一个用于读操作。写线连接池限制连接只能在master节点上：

jdbc:seaboxsql://node1,node2,node3/accounting?targetServerType=master

读连接池在均衡的连接到从节点上，如果从节点失效时也允许他连接到master上：

jdbc:seaboxsql://node1,node2,node3/accounting?targetServerType=preferSlave&loadBalanceHosts=true

当从节点失效，首先会尝试该列表中的从节点。如果没有从节点可以连接，那么会尝试连接master节点。一旦所有的从节点都是'无法连接'，那么就会尝试按照URL中给定的顺序尝试连接各节点。