JDBC 连接器

在支持 JDBC 连接的应用中，需要配置如下 JDBC 信息：

• Driver Class Name: 驱动名称 DolphinDB JDBC 驱动名称是： com.dolphindb.jdbc.Driver。

• url: 连接字符串 连接字符串提供连接数据库的一些关键信息。一个 DolphinDB JDBC url 示例如下：

  jdbc:dolphindb://localhost:8848?user=admin&password=123456

  URL 支持的参数如下：

  参数	作用
  user	数据库用户名。用于连接数据库。
  password	用户密码。用于连接数据库。
  waitingTime	测试连接的超时时间，单位为秒，默认值为3。
  initialScript	传入函数定义脚本。
  allowMultiQueries	是否支持多条语句查询。布尔类型，默认为 false。在一条语句中，允许使用“;”来分隔多条查询。
  databasePath	分布式数据库路径。指定该参数可以在初始化时将分布式表加载到内存。
  tableName	分布式表的表名。指定该参数可以加载指定的分布式表。
  enableHighAvailability 或 highAvailability	高可用参数，布尔类型，默认为 false。指定该参数可以开启或关闭高可用模式。
  sqlStd	枚举类型，用于指定传入 SQL 脚本的解析语法。支持三种解析语法：DolphinDB、Oracle、MySQL，其中默认为 DolphinDB 解析。
  tableAlias	数据库表别名，用于在建立连接时传入一个或多个别名与数据库的组合。用户可通过别名访问数据库表。
  enableLoadBalance	布尔类型，支持开启或关闭高可用模式下的负载均衡功能。

  注：

  • 自1.30.21.1版本起，JDBC 支持高可用参数 enableHighAvailability，其作用与 highAvailability 相同。使用时只需设置其中一个参数即可（推荐使用 enableHighAvailability），若配置冲突则会报错。

  • 若需要创建 JDBCCallableStatement 对象，则连接字符串须指定 allowMultiQueries=true。

  • 自1.30.22.1版本起，JDBC 支持参数 sqlStd 。用户可通过 url 直接传参，见示例1；也可通过 JDBCConnection 构造方法的 Properties 进行传参，见示例2。注意：须使用2.00.10版本以上的 DolphinDB。

    示例1

    通过 url 直接传参。

    Properties prop = new Properties();
    prop.setProperty("user","admin");
     prop.setProperty("password","123456");
    String url = "jdbc:dolphindb://" + HOST + ":" + PORT + "sqlStd:" + SqlStdEnum.MySQL.getName();
    conn = new JDBCConnection(url,prop);

    示例2

    JDBCConnection 构造方法的 Properties 参数支持 sqlStd 属性。用户通过 Properties 设置属性 key 为 sqlStd，值为字符串，即用户通过 SqlStdEnum 指定传入 SQL 脚本的解析语法。使用示例如下：

     Properties prop = new Properties();
     prop.setProperty("user","admin");
    prop.setProperty("password","123456");
    prop.setProperty("sqlStd", SqlStdEnum.DolphinDB.getName());
    String url = "jdbc:dolphindb://"+JDBCTestUtil.HOST+":"+JDBCTestUtil.PORT;
     conn = new JDBCConnection(url,prop);

• 自1.30.22.2版本起，JDBC 支持参数 tableAlias。用户可通过 url 直接传参，见示例3-示例5；也可通过 JDBCConnection 构造方法的 Properties 进行传参，见示例6。

  示例3 DFS 表使用别名

  1. 使用默认别名。下例中以表名 pt 做为别名。

     tableAlias=dfs://valuedb/pt

  2. 指定别名。别名写在开头，别名与库表路径之间用冒号连接。下例中表的别名为 ttt。

     tableAlias=ttt:dfs://valuedb/pt

  3. 同时设置多个库表的别名。值与值之间通过逗号“,”进行分隔。

     tableAlias=t1:dfs://valuedb/pt,dfs://valuedb/dt,dfs://valuedb/Order_tmp,dfs://testValue/nt

  示例4 MVCC 表使用别名

  使用默认别名。下例中以 MVCC 表的名字 mvcc13 做为别名。

  tableAlias=mvcc://work_dir/mvcc13

  指定别名。下例中以 mvcc13 做为别名。

  tableAlias=mvcc3:mvcc://work_dir/mvcc13

  linux server 中使用绝对路径指定别名。下例中使用 “/// ”表示绝对路径，表的别名为 mvcc2。

  tableAlias=mvcc2:mvcc:///home/username/Adolphindb/2.00.6/server/work_dir/mvcc12；

  linux server 中使用相对路径指定别名。下例中使用“//” 表示相对路径，表的别名为 mvcc3。

  tableAlias=mvcc3:mvcc://work_dir/mvcc13

  windows server 中指定别名。下例中表的别名为 mvcc14。

  tableAlias=mvcc14:mvcc://C://DolphinDB/Data1/db12/mvcc14
  
  tableAlias=mvcc14:mvcc://C:\\DolphinDB\\Data1\\db12\\mvcc14；

  示例5 共享内存表使用别名

  指定别名。下例中以 tb8 做为表的别名。

  tableAlias=tb8:memTb2

  示例6 通过 Properties 指定别名

  下例中指定表的别名为 t1。

  Properties info = new Properties();
  info.put("tableAlias","t1:dfs://valuedb/pt");

• 自1.30.22.2版本起，JDBC 的高可用参数 highAvailabilitySites 支持通过逗号“,”分隔输入值。

  示例7 多个值之间通过逗号“,”分割（推荐写法）

  highAvailabilitySites=192.168.1.111:8841,192.168.1.111:8842,192.168.1.111:8843,192.168.1.111:8844

  示例8 多个值之间通过空格分割（不推荐）

  highAvailabilitySites=192.168.1.111:8841 192.168.1.111:8842 192.168.1.111:8843 192.168.1.111:8844

• 自 2.00.11.0 版本起，JDBC 连接提供配置参数 enableLoadBalance。

高可用与负载均衡

JDBC 提供高可用模式与负载均衡功能，用户可通过相关参数进行配置。

版本号说明：1.30.22.5 为 JDBC 在 130 系列的最后一个版本，130 系列后即为 200 系列，2.00.11.0 为 JDBC 在 200 系列的第一个版本。

在 130 系列版本中，JDBC 开启高可用后即自动开启负载均衡。其中高可用与负载均衡的处理逻辑如下：

• 若使用 1.30.22.2 之前的版本，JDBC 将选择最低负载节点进行连接；用户也可通过 highAvailabilitySites 指定可连接的节点组，此时 JDBC 将从 highAvailabilitySites 中随机进行连接。示例如下：

  public void test_enableHighAvailability() throws SQLException {
  	    String SITES = "192.168.0.69:18921 192.168.1.167:18922 192.168.0.69:18923 192.168.0.69:18924";
  	    String url = "jdbc:dolphindb://" + HOST + ":" + PORT + "?user=admin&password=123456&enableHighAvailability=true&highAvailabilitySites=" + SITES;
  	    Connection connection = DriverManager.getConnection(url);
  }

• 在 1.30.22.2 版本中，JDBC 新增“低负载节点”概念（判断标准为：内存占用小于80%、连接数小于90% 且节点负载小于80%）。

• 若使用 1.30.22.2 及之后的版本，开启高可用后，JDBC 将优先随机选择一个低负载节点进行连接，若没有低负载节点，则将随机连接一个可用节点。若用户通过 highAvailabilitySites 指定了可连接的节点组，此时 JDBC 将仍优先从 highAvailabilitySites 中随机连接一个低负载节点，若无，则随机选择一个 highAvailabilitySites 中的可用节点。

在 200 系列版本中，从 2.00.11.0 起，JDBC 支持将高可用与负载均衡进行逻辑分离。用户可以通过 url 或 prop 属性设置配置参数 enableLoadBalance，以关闭或开启高可用模式下的负载均衡。详细逻辑如下：

• 若仅开启高可用，不填写 enableLoadBalance，则为了兼容先前版本，此时将遵循 1.30.22.2 及之后的 130 系列版本的描述逻辑。

• 若同时开启高可用和负载均衡（enableLoadBalance = true），遵循 1.30.22.2 及之后的 130 系列版本的描述逻辑。

• 若开启高可用，不开启负载均衡功能（enableLoadBalance = false），则将连接 url 中HOST与PORT 组成的节点或 Properties 中 hostName, localhost 与 port 组成的节点。

  // 开启高可用、不开启负载均衡使用示例
  public void test_enableHighAvailability_and_enableLoadBalance() throws SQLException {
  	    String SITES = "192.168.0.69:18921 192.168.1.167:18922 192.168.0.69:18923 192.168.0.69:18924";
  	    String url = "jdbc:dolphindb://" + HOST + ":" + PORT + "?user=admin&password=123456&enableHighAvailability=true&highAvailabilitySites=" + SITES + "&enableLoadBalance=false";
  	    Connection connection = DriverManager.getConnection(url);
  }

• 注意：不支持仅开启负载均衡的情况。

使用 Java API 将 demo 需要的模板表保存到磁盘。在 demo 中通过 loadTable 可以快速创建内存表。请注意，变量名及表名不可与 DolphinDB 的关键字同名。脚本代码如下：

public static boolean CreateTable(String database, String tableName, String host, int port) {
    boolean success = false;
    DBConnection db = null;
    try {
        String sb = "bool = [1b, 0b];\n" +
            "char = [97c,'A'];\n" +
            "short = [122h, 123h];\n" +
            "int = [21, 22];\n" +
            "long = [22l, 23l];\n" +
            "float  = [2.1f, 2.2f];\n" +
            "double = [2.1, 2.2];\n" +
            "string= [`Hello, `world];\n" +
            "date = [2013.06.13, 2013.06.14];\n" +
            "month = [2016.06M, 2016.07M];\n" +
            "time = [13:30:10.008, 13:30:10.009];\n" +
            "minute = [13:30m, 13:31m];\n" +
            "second = [13:30:10, 13:30:11];\n" +
            "datetime = [2012.06.13 13:30:10, 2012.06.13 13:30:10];\n" +
            "timestamp = [2012.06.13 13:30:10.008, 2012.06.13 13:30:10.009];\n" +
            "nanotime = [13:30:10.008007006, 13:30:10.008007007];\n" +
            "nanotimestamp = [2012.06.13 13:30:10.008007006, 2012.06.13 13:30:10.008007007];\n" +
            "tb1= table(bool,char,short,int,long,float,double,string,date,month,time,minute,second,datetime,timestamp,nanotime,nanotimestamp);\n" +
            "db=database(\"" + database + "\");\n" +
            "saveTable(db, tb1, `" + tableName + ");\n";
        db = new DBConnection();
        db.connect(host, port);
        db.run(sb);
        success = true;
    } catch (Exception e) {
        e.printStackTrace();
        success = false;
    } finally {
        if (db != null)
            db.close();
        return success;
    }
}

DolphinDB 支持分布式数据表。本例子演示通过 JDBC 来进行分布式表的新增和查询。要操作分布式表，连接的时候需在 URL 中加入 databasePath。getConnection() 时会预先加载分区表的元数据。

示例如下：

jdbc:dolphindb://localhost:8848?databasePath=dfs://valuedb

• 在 JDBC 接口中，可以使用 execute 方法执行所有的 DolphinDB SQL 语句，具体语法参考 DolphinDB SQL 语法。
• JDBC 中 executeUpdate(sql) 返回 SQL 语句更新的记录数，而在 DolphinDB JDBC 连接器中 executeUpdate(sql) 不支持返回 delete, update 和调用 append 的语句所影响的记录数。
• 由于 DolphinDB 不支持更高精度的 BigDecimal 类型，故 DolphinDB JDBC 连接器将 BigDecimal 类型转换为 DOUBLE 类型。
• 下载 示例所有代码。