Apache-Ignite-2.3.0-中文开发手册

4.JDBC

4.1.JDBC Thin模式驱动

Ignite提供了一个JDBC驱动，它可以通过标准的SQL语句处理分布式数据，比如从JDBC端直接进行SELECT、INSERT、UPDATE和DELETE。
目前，Ignite支持两种类型的驱动，轻量易用的JDBC Thin模式驱动以及以客户端节点形式直接接入集群。

4.1.1.JDBC Thin模式驱动

JDBC Thin模式驱动是默认的，是一个轻量级驱动，要使用这种驱动，只需要将`ignite-core-{version}.jar`放入应用的类路径即可。
驱动会接入集群节点然后将所有的请求转发给它进行处理。节点会处理分布式的查询以及结果集的汇总，然后将结果集反馈给客户端应用。
JDBC连接串如下所示：

jdbc:ignite:thin://host[:port][/schema][?<params>]

• host是必需的，它定义了要接入的集群节点主机地址；
• port是接入的端口，如果不指定默认为10800；
• schema是要访问的模式名，默认是PUBLIC，这个名字对应于SQL的ANSI-99标准，不加引号是大小写不敏感的，加引号是大小写敏感的；
• <params>是可选的，形式如下：

param1=value1?param2=value2?...:paramN=valueN

驱动类名为org.apache.ignite.IgniteJdbcThinDriver，比如，下面就是如何打开到集群节点的连接，监听地址为192.168.0.50：

// Register JDBC driver.
Class.forName("org.apache.ignite.IgniteJdbcThinDriver");
// Open the JDBC connection.
Connection conn = DriverManager.getConnection("jdbc:ignite:thin://192.168.0.50");

下表列出了JDBC连接串支持的所有参数：

连接串示例

• jdbc:ignite:thin://myHost：接入myHost,其它比如端口为10800等都是默认值；
• jdbc:ignite:thin://myHost:11900：接入myHost,自定义端口为11900，其它为默认值；
• jdbc:ignite:thin://myHost:11900?distributedJoins=true&autoCloseServerCursor=true：接入myHost,自定义端口为11900，开启了分布式关联和autoCloseServerCursor优化；
• jdbc:ignite:thin://myHost:11900/myschema?lazy=true：接入myHost，自定义端口为11900，模式为MYSCHEMA，并且开启了查询的延迟执行；
• jdbc:ignite:thin://myHost:11900/"MySchema"?lazy=true：接入myHost，自定义端口为11900，模式为MySchema（模式名区分大小写），并且开启了查询的延迟执行。

集群配置
为了接收和处理来自JDBC Thin驱动转发过来的请求，一个节点需要绑定到一个本地网络端口10800，然后监听入站请求。
通过IgniteConfiguration配置SqlConnectorConfiguration，可以对参数进行修改：
Java：

IgniteConfiguration cfg = new IgniteConfiguration()
    .setSqlConnectorConfiguration(new SqlConnectorConfiguration());

XML：

<bean id="ignite.cfg" class="org.apache.ignite.configuration.IgniteConfiguration">
  <property name="sqlConnectorConfiguration">
    <bean class="org.apache.ignite.configuration.SqlConnectorConfiguration" />
  </property>
</bean>

其支持如下的参数：

4.1.2.示例

要处理集群中的数据，需要使用下面的一种方式来创建一个JDBCConnection对象：

// Register JDBC driver.
Class.forName("org.apache.ignite.IgniteJdbcThinDriver");
// Open the JDBC connection.
Connection conn = DriverManager.getConnection("`jdbc:ignite:thin://192.168.0.50");

之后就可以执行SELECTSQL查询了：

// Query names of all people.
ResultSet rs = conn.createStatement().executeQuery("select name from Person");
while (rs.next()) {
    String name = rs.getString(1);
    ...
}
// Query people with specific age using prepared statement.
PreparedStatement stmt = conn.prepareStatement("select name, age from Person where age = ?");
stmt.setInt(1, 30);
ResultSet rs = stmt.executeQuery();
while (rs.next()) {
    String name = rs.getString("name");
    int age = rs.getInt("age");
    ...
}

此外，可以使用DML语句对数据进行修改。
INSERT

// Insert a Person with a Long key.
PreparedStatement stmt = conn.prepareStatement("INSERT INTO Person(_key, name, age) VALUES(CAST(? as BIGINT), ?, ?)");
stmt.setInt(1, 1);
stmt.setString(2, "John Smith");
stmt.setInt(3, 25);
stmt.execute();

MERGE

// Merge a Person with a Long key.
PreparedStatement stmt = conn.prepareStatement("MERGE INTO Person(_key, name, age) VALUES(CAST(? as BIGINT), ?, ?)");
stmt.setInt(1, 1);
stmt.setString(2, "John Smith");
stmt.setInt(3, 25);
stmt.executeUpdate();

UPDATE

// Update a Person.
conn.createStatement().
  executeUpdate("UPDATE Person SET age = age + 1 WHERE age = 25");

DELETE

conn.createStatement().execute("DELETE FROM Person WHERE age = 25");

4.2.JDBC客户端模式驱动

4.2.1.JDBC客户端模式驱动

JDBC客户端节点模式驱动使用自己的完整功能的客户端节点连接接入集群，这要求开发者提供一个完整的Spring XML配置作为JDBC连接串的一部分，然后拷贝下面所有的jar文件到应用或者SQL工具的类路径中：

• {apache_ignite_release}\libs目录下的所有jar文件；
• {apache_ignite_release}\ignite-indexing和{apache_ignite_release}\ignite-spring目录下的所有jar文件；

这个驱动很重，而且可能不支持Ignite的最新SQL特性，但是因为它底层使用客户端节点连接，它可以执行分布式查询，然后在应用端直接对结果进行汇总。
JDBC连接URL的规则如下：

jdbc:ignite:cfg://[<params>@]<config_url>

• <config_url>是必需的，表示指向Ignite客户端节点配置文件的任意合法URL，当驱动试图建立到集群的连接时，这个节点会在Ignite JDBC客户端节点驱动中启动；
  
  • <params>是可选的，格式如下：

param1=value1:param2=value2:...:paramN=valueN

驱动类名为org.apache.ignite.IgniteJdbcDriver，比如下面的代码，展示了如何打开一个到集群的连接：

// Register JDBC driver.
Class.forName("org.apache.ignite.IgniteJdbcDriver");
// Open JDBC connection (cache name is not specified, which means that we use default cache).
Connection conn = DriverManager.getConnection("jdbc:ignite:cfg://file:///etc/config/ignite-jdbc.xml");

它支持如下的参数：

跨缓存查询
驱动连接到的缓存会被视为默认的模式，要跨越多个缓存进行查询，可以参照3.6.缓存查询章节。

流模式
使用JDBC驱动，可以以流模式（批处理模式）将数据注入Ignite集群。这时驱动会在内部实例化IgniteDataStreamer然后将数据传给它。要激活这个模式，可以在JDBC连接串中增加streaming参数并且设置为true：

// Register JDBC driver.
Class.forName("org.apache.ignite.IgniteJdbcDriver");
// Opening connection in the streaming mode.
Connection conn = DriverManager.getConnection("jdbc:ignite:cfg://streaming=true@file:///etc/config/ignite-jdbc.xml");

目前，流模式只支持INSERT操作，对于想更快地将数据预加载进缓存的场景非常有用。JDBC驱动定义了多个连接参数来影响流模式的行为，这些参数已经在上述的参数表中列出。
这些参数几乎覆盖了IgniteDataStreamer的所有常规配置，这样就可以根据需要更好地调整流处理器。关于如何配置流处理器可以参考流处理器的相关文档来了解更多的信息。

基于时间的刷新
默认情况下，当要么连接关闭，要么达到了streamingPerNodeBufferSize，数据才会被刷新，如果希望按照时间的方式来刷新，那么可以调整streamingFlushFrequency参数。

// Register JDBC driver.
Class.forName("org.apache.ignite.IgniteJdbcDriver");
// Opening a connection in the streaming mode and time based flushing set.
Connection conn = DriverManager.getConnection("jdbc:ignite:cfg://streaming=true@streamingFlushFrequency=1000@file:///etc/config/ignite-jdbc.xml");
PreparedStatement stmt = conn.prepareStatement(
  "INSERT INTO Person(_key, name, age) VALUES(CAST(? as BIGINT), ?, ?)");
// Adding the data.
for (int i = 1; i < 100000; i++) {
      // Inserting a Person object with a Long key.
      stmt.setInt(1, i);
      stmt.setString(2, "John Smith");
      stmt.setInt(3, 25);
      stmt.execute();
}
conn.close();
// Beyond this point, all data is guaranteed to be flushed into the cache.

4.2.2.示例

要处理集群中的数据，需要使用下面的一种方式来创建一个JDBCConnection对象：

// Register JDBC driver.
Class.forName("org.apache.ignite.IgniteJdbcDriver");
// Open JDBC connection (cache name is not specified, which means that we use default cache).
Connection conn = DriverManager.getConnection("jdbc:ignite:cfg://file:///etc/config/ignite-jdbc.xml");

之后就可以执行SELECTSQL查询了：

// Query names of all people.
ResultSet rs = conn.createStatement().executeQuery("select name from Person");
while (rs.next()) {
    String name = rs.getString(1);
    ...
}
// Query people with specific age using prepared statement.
PreparedStatement stmt = conn.prepareStatement("select name, age from Person where age = ?");
stmt.setInt(1, 30);
ResultSet rs = stmt.executeQuery();
while (rs.next()) {
    String name = rs.getString("name");
    int age = rs.getInt("age");
    ...
}

此外，可以使用DML语句对数据进行修改。
INSERT

// Insert a Person with a Long key.
PreparedStatement stmt = conn.prepareStatement("INSERT INTO Person(_key, name, age) VALUES(CAST(? as BIGINT), ?, ?)");
stmt.setInt(1, 1);
stmt.setString(2, "John Smith");
stmt.setInt(3, 25);
stmt.execute();

MERGE

// Merge a Person with a Long key.
PreparedStatement stmt = conn.prepareStatement("MERGE INTO Person(_key, name, age) VALUES(CAST(? as BIGINT), ?, ?)");
stmt.setInt(1, 1);
stmt.setString(2, "John Smith");
stmt.setInt(3, 25);
stmt.executeUpdate();

UPDATE

// Update a Person.
conn.createStatement().
  executeUpdate("UPDATE Person SET age = age + 1 WHERE age = 25");

DELETE

conn.createStatement().execute("DELETE FROM Person WHERE age = 25");

4.3.错误码

Ignite的JDBC驱动将错误码封装进了java.sql.SQLException类，它简化了应用端的错误处理。要获得错误码，可以使用java.sql.SQLException.getSQLState()方法，它会返回一个字符串：

// Register JDBC driver.
Class.forName("org.apache.ignite.IgniteJdbcThinDriver");
// Open JDBC connection.
Connection conn = DriverManager.getConnection("jdbc:ignite:thin://127.0.0.1");
PreparedStatement ps;
try {
  ps = conn.prepareStatement("INSERT INTO Person(id, name, age) values (1," +
                             "'John', 'unparseableString')");
}
catch (SQLException e) {
    switch (e.getSQLState()) {
      case "0700B":
        System.out.println("Conversion failure");
        break;
      case "42000":
        System.out.println("Parsing error");
        break;
      default:
        System.out.println("Unprocessed error: " + e.getSQLState());
        break;
    }
}

下表中列出了Ignite目前支持的所有错误码，未来这个列表可能还会扩展：