VastbaseG100

基于openGauss内核开发的企业级关系型数据库。

Menu

连接数据库

本章主要介绍使用 JDBC 连接数据库的方法,并提供代码示例。

配置 JDBC 驱动

在使用 JDBC 连接 Vastbase G100 数据库前,需要配置 JDBC 驱动。

设置类路径

  • 配置本地 JDBC 驱动:

    要使用驱动, 必须将驱动 jar 包含在类路径里,可以将jar包路径添加到CLASSPATH 环境变量中,或者使用 java 命令行标记的方式将驱动jar包引入。比如,有一个使用 Vastbase G100 JDBC 驱动的应用安装在 /usr/local/lib/myapp.jar,而 Vastbase G100 JDBC驱动安装在 /usr/local/vastbase/java/Vastbase-G100-2.0_2021072214.jar.可以用以下方式运行应用∶

    export
    CLASSPATH=/usr/local/lib/MyApp.jar:/usr/local/vastbase/java/Vastbase-G100-2.0_2021072214.jar:.
    java MyApp
    
  • 在集成开发环境中配置 JDBC 驱动:

    本节以在 IDEAJ Community 中配置为例。

    1、配置 SDK。

    在 IDEAJ 中配置工程的 JDK 1.8,如下图所示。

    配置IDEAJ_SDK

    2、导入 Vastbase JDBC 包。

    在 IDEAJ 中导入 jar 包,如下图所示。

    导入jar包

配置为可接受 TCP/IP 连接

由于 java 只支持使用 TCP/IP 连接,所以 Vastbase G100 必须配置为可接受 TCP/IP 连接。可以通过修改 listen_addresses 来进行配置。

vi postgresql.conf 

修改 listen_address 参数。

listen_address = '*'

配置认证文件

需要配置 Vastbase G100 的主机认证文件,保证客户端程序可以访问数据库。

vi pg_hba.conf

添加以下内容。

host all all 0.0.0.0/0 md5

连接数据库

导入 java.sql 包

任何使用JDBC的程序都需要导入java.sql包:

import java.sql.*

加载驱动

在试图与数据库建立连接之前,首先需要加载驱动,加载驱动有两种方法:

  • 在代码中,用Class.forName(Driver)方法加载驱动,例如:

    Class.forName("org.postgresql.Driver");
    
  • 在 JVM 启动时作为参数传递,例如:

    java -Djdbc.drivers=org.postgresql.Driver  
    

连接 URL格式

使用Vastbase G100 JDBC驱动访问Vastbase G100 的URL格式如下:

  • jdbc:postgresql://host:port/database

  • jdbc:postgresql://host:port/

  • jdbc:postgresql://host/database

  • jdbc:postgresql://host/

  • jdbc:postgresql:/

  • jdbc:postgresql://host:port/database?param1=value1&param2=value2

URL中各参数的含义如下:

  • host

    服务端的主机名,默认为localhost,如果要指定IPV6的地址,必须用方括号括起主机参数,例如:jdbc:postgresql://[::1]:5432/atlas。

  • port

    服务端监听的端口,默认为5432.

  • database

    数据库名称,默认连接的数据库是与用户同名的数据库。比如连接用户为vbuser,如果不指定database参数,则默认连接到vbuser这个数据库。

  • param1

    连接串参数,可参考连接参数中的表格。

  • value

    连接串参数的取值,可参考连接参数中的表格,未指定时使用默认值。

获取JDBC连接

使用DriverManager.getConnection()获取连接:

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

关闭JDBC连接

关闭连接时调用Connection的close()方法即可:

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

示例代码

通过 Vastbase G100 JDBC 连接数据库的示例代码如下所示。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;

public class testConn{
    static Connection conn = null;
    static String cname = "org.postgresql.Driver";
    static String url = "jdbc:vastbase://172.16.105.55:5432/vastbase?loggerLevel=OFF";
    static String username = "vastbase";
    static String passwd = "Vbase@admin";

    public static void main(String[] args){
        try{
            Class.forName(cname);
            conn = DriverManager.getConnection(url,username,passwd);
            System.out.println("[SUCCESS] conn database success.");
        }catch (Exception e){
            System.out.println("[FAIL] conn database fail." + e.getMessage());
        }
    }

    public void disConn(Connection conn) throws SQLException{
        if(conn != null){
            conn.close();
        }
    }
}

执行示例代码,返回结果如下所示,表示数据库连接成功。

[SUCCESS] conn database success.

Process finished with exit code 0

连接参数

参数名称 参数类型 参数说明
PGDBNAME String 指定用于连接的数据库名称(可直接在JDBC URL中指定),默认值为空。
PGHOST String 指定数据库服务的主机名称(可直接在JDBC URL中指定),默认值为空。
PGPORT String 指定数据库服务的端口号(可直接在JDBC URL中指定),默认值为空。
user String 连接数据库的用户。
password String 数据库用户的密码。
protocolVersion String 连接协议版本号,目前仅支持3。注意:设置该参数时将采用md5加密方式,需要同步修改数据库的加密方式:vb_guc set -N all -I all -c "password_encryption_type=1" ,重启Vastbase生效后需要创建用md5方式加密口令的用户。同时修改pg_hba.conf,将客户端连接方式修改为md5。用新建用户进行登录(不推荐)。默认值为空。
enable_ce String 指定是否开启客户端加密特性,取值为1时用于打开此特性,默认值为空。
loggerLevel String 指定驱动的日志级别,默认值为空,目前支持4种级别:OFF、INFO、DEBUG、TRACE。设置为OFF关闭日志,设置为INFO、DEBUG和TRACE记录的日志信息详细程度不同。默认值为INFO。该参数设置值不区分大小写。
loggerFile String 指定驱动的日志输出的文件名称,默认值为空。
logger String 指定第三方程序使用的日志,默认为空。
prepareThreshold Integer 指定使用PreparedStatement构造的SQL语句在重复执行多少次后会缓存在数据库服务端,默认值为5,即执行5次后会把查询计划等信息缓存到数据库端,随后的请求指挥发送该语句缓存后的句柄,建议使用默认值。
preparedStatementCacheQueries Integer 确定每个连接中缓存的查询数,默认情况下是256。若在prepareStatement()调用中使用超过256个不同的查询,则最近最少使用的查询缓存将被丢弃。0表示禁用缓存。建议使用默认值。
preparedStatementCacheSizeMiB Integer 确定每个连接可缓存的最大值(以兆字节为单位),默认情况下是5。若缓存了超过5MB的查询,则最近最少使用的查询缓存将被丢弃。0表示禁用缓存。建议使用默认值。
databaseMetadataCacheFields Integer 指定每个连接要缓存的最大字段数,当取值为0会禁用该缓存,默认值为65536。
databaseMetadataCacheFieldsMiB Integer 指定每个连接要缓存的字段的最大值(MB),当取值为0会禁用该缓存,默认值为5。
defaultRowFetchSize Integer 确定一次fetch在ResultSet中读取的行数。限制每次访问数据库时读取的行数可以避免不必要的内存消耗,从而避免OutOfMemoryException。默认值是0,这意味着ResultSet中将一次获取所有行,没有负数。
binaryTransfer Boolean 使用二进制格式发送和接收数据,默认值为false。
readOnly Boolean 将连接设置为只读模式。
binaryTransferEnable String 指定以逗号分隔的二进制传输启用的类型列表,可以是OID编号或名称,默认值为空。
binaryTransferDisable String 指定以逗号分隔的二进制传输禁用的类型列表,可以是OID编号或名称,设置本参数取值后可以覆盖驱动程序默认设置中的值和通过参数binaryTransferEnable设置的值,默认值为空。
Stringtype String 设置通过setString()方法使用的PreparedStatement参数的类型,可选字段为:false、 "unspecified"、 "varchar"。
  • 如果Stringtype设置为VARCHAR(默认值),则这些参数将作为varchar参数发送给服务器。
  • 若Stringtype设置为unspecified,则参数将作为untyped值发送到服务器,服务器将尝试推断适当的类型。
  • unknownLength Integer 默认为Integereger.MAX_VALUE。某些postgresql类型(例如TEXT)没有明确定义的长度,当通过ResultSetMetaData.getColumnDisplaySize和ResultSetMetaData.getPrecision等函数返回关于这些类型的数据时,此参数指定未知长度类型的长度。
    logUnclosedConnections Boolean 客户端可能由于未调用Connection对象的close()方法而泄漏Connection对象。最终这些对象将被垃圾回收,并且调用finalize()方法。如果调用者自己忽略了此操作,该方法将关闭Connection。
    disableColumnSanitiser Boolean 指定是否启用禁用列名净化的优化器,默认值为false。
    ssl Boolean 以SSL方式连接。ssl=true可支持NonValidatingFactory通道和使用证书的方式:
    1、NonValidatingFactory通道需要配置用户名和密码,同时将SSL设置为true。
    2、配置客户端证书、密钥、根证书,将SSL设置为true。
    sslmode Boolean SSL认证方式。取值范围为:disable、allow、prefer、require、verify-ca、verify-full。
  • disable:不使用SSL安全连接。
  • allow:如果数据库服务器要求使用,则可以使用SSL安全加密连接,但不验证数据库服务器的真实性。
  • prefer:如果数据库支持,那么首选使用SSL连接,但不验证数据库服务器的真实性。
  • require:只尝试SSL连接,如果存在CA文件,则应设置成verify-ca的方式验证。
  • verify-ca:只尝试SSL连接,并且验证服务器是否具有由可信任的证书机构签发的证书。
  • verify-full:只尝试SSL连接,并且验证服务器是否具有由可信任的证书机构签发的证书,以及验证服务器主机名是否与证书中的一致。
  • sslfactory String 提供的值是SSLSocketFactory在建立SSL连接时用的类名。
    sslfactoryarg String 此值是上面提供的sslfactory类的构造函数的可选参数(不推荐使用)。
    sslhostnameverifier String 主机名验证程序的类名。
    sslcert String 提供证书文件的完整路径。客户端和服务端证书的类型为End Entity。
    sslkey String 提供密钥文件的完整路径。使用时将客户端证书转换为DER格式:"openssl pkcs8 -topk8 -outform DER -in client.key -out client.key.pk8 -nocrypt"
    sslrootcert String SSL根证书的文件名。根证书的类型为CA。
    sslpassword String sslpassword:String类型。提供给ConsoleCallbackHandler使用。
    sslprivatekeyfactory String 客户端密钥ssl的factory,默认值为空。
    sslpasswordcallback String SSL密码提供者的类名。
    tcpKeepAlive Boolean 启用或禁用TCP保活探测功能。默认为false。
    logIntegerimeout Integer 指建立数据库连接的等待时间。超时时间单位为秒。
    connectionTimeout Integer 使用的超时值或套接字连接操作,如果连接到服务器的时间超过该值,则连接断开。
    socketTimeout Integer类 用于套接字读取操作的超时值。如果从服务器读取的时间超过此值,则连接将关闭。这既可以用作强力全局查询超时,也可以用作检测网络问题的方法。超时以秒为单位指定,值为零表示禁用。
    cancelSignalTimeout Integer 发送取消消息本身可能会阻塞,此属性控制用于取消命令的"connectionTimeout"和"socketTimeout"。超时时间单位为秒,默认值为10秒。
    socketFactory String 用于创建与服务器socket连接的类的名称。该类必须实现了接口"javax.net.SocketFactory",并定义无参或单String参数的构造函数。
    socketFactoryArg String 此值是上面提供的socketFactory类的构造函数的可选参数,不推荐使用。
    sendBufferSize Integer 该值用于设置连接流上的SO_SNDBUF。
    receiveBufferSize Integer 在连接流上设置SO_RCVBUF。
    assumeMinServerVersion String 客户端会发送请求进行float精度设置。该参数设置要连接的服务器版本,如assumeMinServerVersion=9.0,可以在建立时减少相关包的发送。
    ApplicationName String 设置正在使用连接的JDBC驱动的名称。通过在数据库主节点上查询pg_stat_activity表可以看到正在连接的客户端信息,JDBC驱动名称显示在application_name列。默认值为PostgreSQL JDBC Driver。
    ApplicationType String 设置正在使用连接的JDBC驱动的类型。
    jaasLogin Boolean 用于启用/禁用在进行身份验证之前通过JAAS登录获取Gss凭据的标志。 如果设置系统属性javax.security.auth.useSubjectCredsOnly=false,则有效 或使用系统属性为sun.security.jgss.native-true的本机GSS。
    jaasApplicationName String 指定JAAS系统或应用程序登录配置的名称。
    kerberosServerName String 使用GSSAPl进行身份验证时要使用的kerberos服务名称。这相当于libpq的PGKRBSRVNAME环境变量。
    useSpnego Boolean 指定是否在SSPI身份验证请求中使用spnego,默认值为false,表示不使用。
    gsslib String 指定强制SSPI或GSSAPI,取值可以为auto、sspi、gssapi,默认值为auto。
    sspiServiceClass String 指定用于SPN的Windows SSPI服务类,默认值为空。
    allowEncodingChanges Boolean 设置该参数值为“true”时进行字符集类型更改,配合characterEncoding设置字符集。
    currentSchema String 指定设置到search-path中的schema。
    targetServerType String 指定要连接的服务器类型,取值可以为any、master、slave、preferSlave,默认值为any。
  • any:连接到任意一个可用的数据库节点。
  • master:连接到任意一个可写的数据库节点。
  • slave:连接到任意一个只读的数据库节点。
  • secondary:连接到任意一个只读的数据库节点。
  • preferSlave:连接到任意一个只读的数据库节点,如果没有可用的只读节点,则连接到可读可写节点。
  • preferSecondary :连接到任意一个只读的数据库节点,如果没有可用的只读节点,则连接到可读可写节点。
  • priorityServers Integer 此值用于指定url上配置的前n个节点作为主集群被优先连接。默认值为null。该值为数字,大于0,且小于url上配置的DN数量。
    usingeip Boolean 负载平衡时使用弹性IP地址,默认值为true。
    loadBalanceHosts Boolean 配合targetServerType使用,若为true,则随机分配节点,若为false,则按顺序分配节。
    hostRecheckSeconds Integer 指定检查主机状态的周期,以防它们发生更改,单位是毫秒,默认值为10。
    forceTargetServerSlave Boolean 此值用于控制是否开启强制连接备机功能,并在集群发生主备切换时,禁止已存在的连接在升主备机上继续使用。
  • 默认值为false,表示不开启强制连接备机功能。
  • true表示开启强制连接备机功能。
  • preferQueryMode String 用于指定执行查询的模式,共有4种取值:“extended”、“extendedForPrepared”、“extendedCacheEverything”和“simple”。
  • simple模式会excute,不parse和bind;
  • extended模式会bind和excute;
  • extendedForPrepared模式为prepared statement扩展使用;
  • extendedCacheEverything模式会缓存每个statement。
  • autosave String 如果查询失败,指定驱动程序应该执行的操作。共有3种取值:“always”、 “never”、 “conservative”。
  • 在autosave=always模式下,JDBC驱动程序在每次查询之前设置一个保存点,并在失败时回滚到该保存点。
  • 说明
    将autosave设置为always可能会导致数据库内存溢出,不建议设置为always。
  • 在autosave=never模式(默认)下,无保存点。
  • 在autosave=conservative模式下,每次查询都会设置保存点,但是只会在“statement XXX无效”等情况下回滚并重试。
  • autoBalance String jdbc可以通过URL中设置多个数据库节点,实现对主备集群的访问。通过设置负载均衡算法,jdbc可以在建立连接时,依照特定规则将客户端与主备集群的连接依次建立在URL中配置的各个节点上,以此实现连接的负载均衡。默认值为"false",此时jdbc始终与URL中配置的同一个满足建连条件的节点建立连接。连接主备集群时,使用此参数需要保证业务中没有写操作,或者与targetServerType=slave搭配,限制客户端只连接备机。目前,jdbc提供了roundrobin、priority roundrobin、leastconn、shuffle四种负载均衡模式,具体说明如下:
  • (暂不支持)roundrobin:轮询模式,即与各候选节点轮流建立连接。取值:"roundrobin"、"true"、"balance"。
  • priority roundrobin:带优先级的轮询模式,优先对前n个候选节点做轮询建连,取值:"proprity[n]",n为非负整数。
  • leastconn:最小连接模式,对候选节点依照各节点的有效连接数做优先级排序,优先与连接数少的节点建立连接,该方法只会统计通过当前驱动在当前集群内使用leastconn模式建立的连接。取值:"leastconn"。
  • shuffle:随机模式,即随机选择候选节点建立连接,取值:"shuffle"。
  • loadBalanceHosts设置为"true"等同于autoBalance设置为"shuffle"。
  • 如果loadBalanceHosts设置为"true"的同时,autoBalance设置为以上四种负载均衡模式,优先使autoBalance生效;如果同时配置了autoBalance和targetServerType,jdbc会在满足targetServerType的前提下负载均衡;如果客户端使用多个指定了相同节点集合的URL分别通过同一驱动建立连接,jdbc会将其视为同一集群上的连接,并整体进行负载均衡。
    reWriteBatchedInserts Boolean 批量导入时,该参数设置为on,可将N条插入语句合并为一条:insert Integero TABLE_NAME values(values1, ..., valuesN), ..., (values1, ..., valuesN);使用该参数时,需设置batchMode=off。
    replication String 指定启动报文的连接参数replication的值(true,database)。布尔值 true 告诉后端进入 walsender 模式,其中可以发出一小组复制命令而不是SQL语句。在 walsender 模式下只能使用简单查询协议。将数据库作为值传递指示walsender连接到dbname参数中指定的数据库,这将允许连接用于从该数据库进行逻辑复制。(后端>=9.4)
    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。
    xmlFactoryFactort String 指定用于进行实例化Factory以进行xml处理的Factory类。
    db_compatibility String 指定兼容模式,默认值为postgresql,可设置有postgresql和oracle,该参数设置从数据库返回的对象名大小写。
  • 设置为postgresql时,返回对象名的字母大小写与数据库中一致。
  • 设置为oracle时,使用ResultSetMetaData获取对象名时,对象名的字母将以大写返回,并且disableColumnSanitiser=fasle设置无效。
  • 注意:当对象名是使用双引号引住的小写名称(没有大写字母),也会转换成全大写字母返回,因此使用此参数时需要注意对象名的大小写。
    bulkloadCtlFile String 指定bulkload控制文件的路径。
    resultCaseMode String 指定结果的大小写,默认值为lower,表示小写。本参数session级生效。
    timeTextMode Boolean 指定是否使用text类型绑定时间参数,为了方式JDBC对时间的处理导致服务器收到的数据失真。默认值为OFF。
    exitCommit Boolean 指定是否在session关闭时提交事务,默认值为OFF,表示不在会话关闭时提交事务。本功能仅在内部功能Debug调试需要,对实际开发、生产使用无相关意义。且不推荐用户使用该参数。
    extraFloatDigits Integer 对GUC参数进行修改,为sessio级别,默认值为3,表示指定额外的浮动数字为3。
    zzkk String 内部测试表现行为调试参数,不用于实际业务中,即用户不可使用。
    oraBlobMode Boolean 针对Blob的新类型oraBlob进行相关逻辑改动。
    userVastbaseProductName Boolean 指定是否使用Vastbase作为productName的返回。
    quoteReturningIdentifiers Boolean 指定是否引用返回列,默认值为false,表示不引用。
    loginWithHostname Boolean 指定是否在系统视图v$session中查询中带有操作系统用户名称和主机名称。默认值为false,表示不在系统视图中添加上述信息。