JDBC-драйвер#

DataGrid поставляется с JDBC-драйверами, которые позволяют обрабатывать распределенные данные непосредственно через JDBC с помощью стандартных SQL-запросов, например SELECT, INSERT, UPDATE или DELETE.

В настоящее время DataGrid поддерживает два драйвера:

• легковесный тонкий JDBC-драйвер, который описан в данном разделе;

• клиентский JDBC-драйвер, который взаимодействует с кластером с помощью клиентского узла и описан в разделе «Клиентский JDBC-драйвер».

Тонкий JDBC-драйвер#

Тонкий JDBC-драйвер — легковесный драйвер по умолчанию, который предоставляет DataGrid. Чтобы начать использовать драйвер, добавьте ignite-core-2.16.0.jar в classpath приложения.

Драйвер подключается к одному из узлов кластера и перенаправляет все запросы на него для окончательного выполнения. Узел обрабатывает распределение запросов и агрегацию результатов. Затем результат отправляется обратно в клиентское приложение.

Строка подключения JDBC может быть отформатирована с использованием одного из двух шаблонов — URL query или semicolon.

Синтаксис строки подключения:

// Шаблон `URL query`.
jdbc:ignite:thin://<hostAndPortRange0>[,<hostAndPortRange1>]...[,<hostAndPortRangeN>][/schema][?<params>]

hostAndPortRange := host[:port_from[..port_to]]

params := param1=value1[&param2=value2]...[&paramN=valueN]

// Шаблон `semicolon`.
jdbc:ignite:thin://<hostAndPortRange0>[,<hostAndPortRange1>]...[,<hostAndPortRangeN>][;schema=<schema_name>][;param1=value1]...[;paramN=valueN]

где:

• host — обязательный параметр, который определяет хост узла кластера для подключения.

• port_from — начало диапазона портов для открытия подключения. Если значение параметра не указано, по умолчанию используется 10800.

• port_to — необязательный параметр. Если значение не указано, по умолчанию используется значение параметра port_from.

• schema — имя схемы для доступа, по умолчанию используется PUBLIC. Это имя должно соответствовать стандарту SQL ANSI-99. Необрамленные идентификаторы (non-quoted identifiers) не чувствительны к регистру. Обрамленные идентификаторы (quoted identifiers) чувствительны к регистру. При использовании формата с точкой с запятой (semicolon) схема может быть определена как параметр с именем schema.

• <params> — необязательные параметры.

Имя класса драйвера — org.apache.ignite.IgniteJdbcThinDriver.

// Регистрация JDBC-драйвера.
Class.forName("org.apache.ignite.IgniteJdbcThinDriver");

// Открытие JDBC-подключения.
Connection conn = DriverManager.getConnection("jdbc:ignite:thin://xxx.x.x.x");

Параметры#

В таблице перечислены все параметры, которые поддерживает строка подключения JDBC:

Примеры строк подключения:

• jdbc:ignite:thin://myHost — подключение к myHost на порту 10800 со всеми настройками по умолчанию.

• jdbc:ignite:thin://myHost:11900 — подключение к myHost на пользовательском порту 11900 со всеми настройками по умолчанию.

• jdbc:ignite:thin://myHost:11900;user=*****;password=***** — подключение к myHost на порту 11900 с учетными данными пользователя для аутентификации.

• jdbc:ignite:thin://myHost:11900;distributedJoins=true&autoCloseServerCursor=true — подключение к myHost на порту 11900 с включенными распределенными соединениями и оптимизацией autoCloseServerCursor.

• jdbc:ignite:thin://myHost:11900/myschema; — подключение к myHost на порту 11900 и доступ к схеме MYSCHEMA.

• jdbc:ignite:thin://myHost:11900/"MySchema";lazy=false — подключение к myHost на порту 11900 с отключенным ленивым выполнением запроса (lazy=false) и доступом к MySchema (учитывается регистр букв в названии схемы).

Несколько конечных точек (endpoints)#

Можно включить автоматическое переключение при разрыве соединения — для этого укажите несколько конечных точек (endpoints) в строке подключения. JDBC-драйвер случайным образом выбирает один из указанных адресов для подключения. Если соединение разрывается, драйвер выбирает другой адрес из списка, пока соединение не будет восстановлено. Если все конечные точки недоступны, драйвер прекращает попытки и генерирует исключение.

// Регистрация JDBC-драйвера.
Class.forName("org.apache.ignite.IgniteJdbcThinDriver");

// Открытие JDBC-соединения с несколькими конечными точками.
Connection conn = DriverManager
        .getConnection("jdbc:ignite:thin://xxx.xxx.x.xx:xxx,yyy.yyy.y.yy:yyy,zzz.zzz.zz.zzz:zzz");

Partition Awareness#

Функция Partition Awareness делает JDBC-драйвер «осведомленным» о распределении данных по партициям внутри кластера. Это позволяет драйверу определять узлы, которые хранят запрашиваемые данные, и отправлять запрос непосредственно на эти узлы (если их адреса указаны в конфигурации драйвера). Такая оптимизация может повысить производительность запросов, которые используют affinity-ключи.

Без функции Partition Awareness JDBC-драйвер подключается только к одному узлу, и все запросы выполняются через него. Если данные хранятся на другом узле, запрос перенаправляется внутри кластера, что создает дополнительную сетевую нагрузку. Функция Partition Awareness устраняет промежуточный шаг с помощью отправки запроса сразу на нужный узел.

Чтобы использовать Partition Awareness, укажите адреса всех серверных узлов в свойствах соединения. Драйвер будет направлять запросы на узлы, где хранятся запрашиваемые данные.

Для включения функции Partition Awareness добавьте параметр partitionAwareness=true в строку подключения и укажите несколько конечных точек (endpoints):

Class.forName("org.apache.ignite.IgniteJdbcThinDriver");

Connection conn = DriverManager
        .getConnection("jdbc:ignite:thin://xxx.xxx.x.xx,yyy.yyy.y.yy,zzz.zzz.zz.zzz?partitionAwareness=true");

Подробнее о связанных параметрах partitionAwarenessSQLCacheSize и partitionAwarenessPartitionDistributionsCacheSize написано выше в таблице в разделе «Параметры».

Конфигурация кластера#

Чтобы принимать и обрабатывать запросы от тонкого JDBC-драйвера, узел кластера привязывается к локальному сетевому интерфейсу на порту 10800 и слушает входящие запросы. Чтобы изменить параметры подключения, используйте экземпляр ClientConnectorConfiguration:

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

IgniteConfiguration cfg = new IgniteConfiguration()
    .setClientConnectorConfiguration(new ClientConnectorConfiguration());

Поддерживаемые параметры:

"Concurrent access to JDBC connection is not allowed
[ownThread=<guard_owner_thread_name>, curThread=<current_thread_name>]",
SQLSTATE="08006"

Использование SSL#

Тонкий JDBC-драйвер можно настроить для использования SSL для защиты связи с кластером. SSL должен быть настроен и на стороне кластера, и в JDBC-драйвере.

Чтобы включить SSL в JDBC-драйвере, передайте параметр sslMode=require в строке подключения и укажите параметры хранилищ ключей (keystore) и доверенных сертификатов (truststore):

Class.forName("org.apache.ignite.IgniteJdbcThinDriver");

String keyStore = "keystore/node.jks";
String keyStorePassword = "123456";

String trustStore = "keystore/trust.jks";
String trustStorePassword = "123456";

try (Connection conn = DriverManager.getConnection("jdbc:ignite:thin://127.0.0.1?sslMode=require"
        + "&sslClientCertificateKeyStoreUrl=" + keyStore + "&sslClientCertificateKeyStorePassword="
        + keyStorePassword + "&sslTrustCertificateKeyStoreUrl=" + trustStore
        + "&sslTrustCertificateKeyStorePassword=" + trustStorePassword)) {

    ResultSet rs = conn.createStatement().executeQuery("select 10");
    rs.next();
    System.out.println(rs.getInt(1));
} catch (Exception e) {
    e.printStackTrace();
}

Параметры, которые влияют на соединение SSL/TLS:

Реализация SSL в тонком JDBC-драйвере основана на JSSE и использует два файла хранилища ключей (keystore) Java:

• sslClientCertificateKeyStoreUrl — хранилище клиентских сертификатов, которое содержит ключи и сертификат клиента.

• sslTrustCertificateKeyStoreUrl — хранилище доверенных сертификатов, которое содержит сертификаты для проверки подлинности сервера.

Хранилище доверенных сертификатов — необязательный параметр, но должен быть настроен один из двух параметров: sslTrustCertificateKeyStoreUrl или sslTrustAll.

Если нет возможности использовать собственную реализацию или метод настройки SSLSocketFactory, можно использовать параметр sslFactory JDBC-драйвера. Этот параметр должен содержать имя класса, который реализует интерфейс Factory<SSLSocketFactory>. Класс должен быть доступен загрузчику классов JDBC-драйвера.

DataSource#

Объект DataSource используется как развертываемый объект, который можно найти по логическому имени через сервис именования JNDI. JDBC-драйвер реализует класс org.apache.ignite.IgniteJdbcThinDataSource, который поддерживает интерфейс DataSource и позволяет использовать его вместо стандартного JDBC-подключения.

Помимо общих свойств DataSource, IgniteJdbcThinDataSource поддерживает все специфические параметры DataGrid, которые можно передавать в строке подключения JDBC. Например, свойство distributedJoins можно установить и переустановить с помощью метода IgniteJdbcThinDataSource#setDistributedJoins().

Подробнее о IgniteJdbcThinDataSource написано в официальной документации Apache Ignite.

Примеры использования#

Чтобы начать обработку данных в кластере, создайте объект JDBC-соединения одним из способов:

// Открытие JDBC-соединения с помощью `DriverManager`.
Connection conn = DriverManager.getConnection("jdbc:ignite:thin://xxx.xxx.x.xx");

или

// Открытие JDBC-соединения с помощью `DataSource`.
IgniteJdbcThinDataSource ids = new IgniteJdbcThinDataSource();
ids.setUrl("jdbc:ignite:thin://xxx.x.x.x");
ids.setDistributedJoins(true);

Connection conn = ids.getConnection();

После этого можно выполнять стандартные SQL-запросы (SELECT, INSERT, MERGE, UPDATE, DELETE) и использовать DML-операторы для изменения данных.

SELECT#

// Запрос людей определенного возраста с помощью подготовленного выражения (`PreparedStatement`).
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#

// Вставка новой записи в таблицу `Person` с ключом типа `long`.
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) записи в таблицу `Person` с ключом типа `long`.
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#

// Обновление данных в таблице `Person`.
conn.createStatement().
  executeUpdate("UPDATE Person SET age = age + 1 WHERE age = 25");

DELETE#

// Удаление записей из таблицы `Person`.
conn.createStatement().execute("DELETE FROM Person WHERE age = 25");

Потоковая передача данных#

JDBC-драйвер поддерживает потоковую передачу (bulk streaming) данных с помощью команды SET. Подробнее о ней написано в подразделе «SET STREAMING» раздела «Управляющие команды».

Коды ошибок#

JDBC-драйвер передает коды ошибок в классе java.sql.SQLException, что облегчает обработку исключений на стороне приложения. Чтобы получить код ошибки, используйте метод java.sql.SQLException.getSQLState(). Он возвращает строку, которая содержит код ошибки SQLSTATE, определенный стандартами ANSI SQL.

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;
    }
}

В таблице ниже описаны все коды ошибок ANSI SQLSTATE, которые поддерживаются в JDBC-драйвере DataGrid. В будущем этот список может быть расширен.

Коды ошибок: