You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by pp...@apache.org on 2025/11/27 14:30:45 UTC
(ignite-3) branch main updated: IGNITE-26150 Jdbc. Description of the new JDBC features has been added to the documentation (#7040)
This is an automated email from the ASF dual-hosted git repository.
ppa pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git
The following commit(s) were added to refs/heads/main by this push:
new c8851decef1 IGNITE-26150 Jdbc. Description of the new JDBC features has been added to the documentation (#7040)
c8851decef1 is described below
commit c8851decef171cece4183a803967031ff023a20e
Author: Pavel Pereslegin <xx...@gmail.com>
AuthorDate: Thu Nov 27 17:30:38 2025 +0300
IGNITE-26150 Jdbc. Description of the new JDBC features has been added to the documentation (#7040)
Co-authored-by: IgGusev <ig...@gridgain.com>
---
docs/_data/toc.yaml | 2 -
.../developers-guide/clients/jdbc-driver.adoc | 30 ++++--
docs/_docs/developers-guide/sql/jdbc-driver.adoc | 108 ---------------------
.../org/apache/ignite/jdbc/IgniteJdbcDriver.java | 6 ++
4 files changed, 27 insertions(+), 119 deletions(-)
diff --git a/docs/_data/toc.yaml b/docs/_data/toc.yaml
index 55f87815165..993bd6e2988 100644
--- a/docs/_data/toc.yaml
+++ b/docs/_data/toc.yaml
@@ -82,8 +82,6 @@
url: developers-guide/sql/calcite-based-sql-engine
- title: SQL API
url: developers-guide/sql/sql-api
- - title: JDBC Driver
- url: developers-guide/sql/jdbc-driver
- title: ODBC Driver
url: developers-guide/sql/odbc/odbc-driver
- title: ODBC Connection String
diff --git a/docs/_docs/developers-guide/clients/jdbc-driver.adoc b/docs/_docs/developers-guide/clients/jdbc-driver.adoc
index fec6ecb1f6b..ad6d88092e0 100644
--- a/docs/_docs/developers-guide/clients/jdbc-driver.adoc
+++ b/docs/_docs/developers-guide/clients/jdbc-driver.adoc
@@ -16,10 +16,14 @@
Apache Ignite is shipped with JDBC driver that allows processing of distributed data using standard SQL statements like `SELECT`, `INSERT`, `UPDATE`, or `DELETE` directly from the JDBC side. The name of the driver's class is `org.apache.ignite.jdbc.IgniteJdbcDriver`.
-This implementation of JDBC driver does not support:
+[NOTE]
+====
+The JDBC driver was completely reworked in Apache Ignite 3.2 and now supports multiple endpoints and link:developers-guide/clients/overview#partition-awareness[partition awareness].
-* Multiple endpoints
-* JDBC connection pools
+The new driver is not compatible with Apache Ignite 3.1 and 3.0. To connect to Ignite 3.1 (and 3.0), use the previous version of the driver that was shipped with Apache Ignite 3.1.
+
+The server part remains compatible with previous versions of the driver, so driver for Ignite 3.1 can successfully connect to the 3.2 cluster.
+====
See also:
@@ -38,7 +42,7 @@ The JDBC connector needs to be included from Maven:
<dependency>
<groupId>org.apache.ignite</groupId>
<artifactId>ignite-jdbc</artifactId>
- <version>3.1.0</version>
+ <version>3.2.0</version>
</dependency>
----
@@ -65,10 +69,9 @@ jdbc:ignite:thin://host[:port][,host[:port][/schema][[?parameter1=value1][;param
* `schema` is the schema name to access. PUBLIC is used by default. This name should correspond to the SQL ANSI-99 standard. Non-quoted identifiers are not case sensitive. Quoted identifiers are case sensitive. When semicolon format is used, the schema may be defined as a parameter with name schema.
* `parameters` are optional parameters. The following parameters are available:
** `connectionTimeZone` - Client connection time-zone ID. This property can be used by the client to change the time zone of the session on the server. Affects the interpretation of dates in queries that do not specify the time zone explicitly. If not set, system default on client timezone will be used.
+** `partitionAwarenessMetadataCacheSize` - Size of cache to store partition awareness metadata of queries, in number of entries. Default value: `1024`.
** `queryTimeout` - Number of seconds the driver will wait for a `Statement` object to execute. 0 means there is no limit. Default value: `0`.
** `connectionTimeout` - Number of milliseconds JDBC client will wait for server to respond. 0 means there is no limit. Default value: `0`.
-** `reconnectThrottlingPeriod` - Reconnect throttling period, in milliseconds. 0 means there is no limit. Default value: `30_000`.
-** `reconnectThrottlingRetries` - Reconnect throttling retries. 0 means there is no limit. Default value: `3`.
** `username` - username for basic authentication to the cluster.
** `password` - user password for basic authentication to the cluster.
** `sslEnabled` - Determines if SSL is enabled. Possible values: `true`, `false`. Default value: `false`
@@ -89,7 +92,9 @@ If the same parameters are passed by using different means, the JDBC driver prio
== Performing Transactions
-With the JDBC driver, you can perform `commit` and `rollback` transactions. For more information about transactions, see link:developers-guide/transactions[Performing Transactions].
+By default, a JDBC connection is in auto-commit mode, and in this mode all its SQL statements will be executed and committed as individual transactions.
+To be able to manage the transaction, you must switch connection to non-autocommit mode.
+In non-autocommit mode, you can perform `commit` and `rollback` transactions. For more information about transactions, see link:developers-guide/transactions[Performing Transactions].
Here is how you can commit a transaction:
@@ -98,12 +103,13 @@ Here is how you can commit a transaction:
// Open the JDBC connection.
Connection conn = DriverManager.getConnection("jdbc:ignite:thin://127.0.0.1:10800");
+// Disable auto-commit mode.
+conn.setAutoCommit(false);
+
// Commit a transaction
conn.commit();
----
-You can also configure Apache Ignite to automatically commit transactions by using the `setAutoCommit()` method.
-
Here is how you can rollback a transaction:
[source, java]
@@ -111,6 +117,12 @@ Here is how you can rollback a transaction:
conn.rollback();
----
+== Partition Awareness
+
+Partition awareness is supported by the JDBC driver.
+
+See link:developers-guide/clients/overview#partition-awareness[Partition Awareness Overview] for more details.
+
== Unsupported Mandatory JDBC Features
The following mandatory JDBC features are currently not supported (sorted alphabetically):
diff --git a/docs/_docs/developers-guide/sql/jdbc-driver.adoc b/docs/_docs/developers-guide/sql/jdbc-driver.adoc
deleted file mode 100644
index 382dc567e62..00000000000
--- a/docs/_docs/developers-guide/sql/jdbc-driver.adoc
+++ /dev/null
@@ -1,108 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one or more
-// contributor license agreements. See the NOTICE file distributed with
-// this work for additional information regarding copyright ownership.
-// The ASF licenses this file to You under the Apache License, Version 2.0
-// (the "License"); you may not use this file except in compliance with
-// the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-= JDBC Driver
-
-Ignite is shipped with JDBC driver that allows processing of distributed data using standard SQL statements like `SELECT`, `INSERT`, `UPDATE`, or `DELETE` directly from the JDBC side. The name of the driver’s class is `org.apache.ignite.jdbc.IgniteJdbcDriver`.
-
-This implementation of JDBC driver does not support the following functionality:
-
-* SSL/TLS connection;
-* Multiple Endpoints;
-* Multi-statement requests;
-* `CREATE TABLE`, `ALTER TABLE`, `WITH`, and `MERGE` commands.
-
-== Setting Up
-
-JDBC driver uses the client connector to work with the cluster. For more information on configuring client connector, see link:developers-guide/clients/overview#client-connector-configuration[Client Connector Configuration].
-
-The JDBC connector needs to be included from Maven:
-
-[source, xml, subs="attributes,specialchars"]
-----
-<dependency>
- <groupId>org.apache.ignite</groupId>
- <artifactId>ignite-jdbc</artifactId>
- <version>3.1.0</version>
-</dependency>
-----
-
-Here is how you can open a JDBC connection to the cluster node listening on IP address `127.0.0.1`:
-
-[source, java]
-----
-Connection conn = DriverManager.getConnection("jdbc:ignite:thin://127.0.0.1:10800");
-----
-
-The driver connects to one of the cluster nodes and forwards all the queries to it for final execution. The node handles the query distribution and the result’s aggregations. Then the result is sent back to the client application.
-
-The JDBC connection string can have an optional list of name-value pairs as parameters after the '?' delimiter. Name and value are separated by the '=' symbol and multiple properties are separated either by an '&' or a ';'.
-Separator signs cannot be mixed and should be either semicolon or ampersand.
-
-[source, java]
-----
-jdbc:ignite:thin://host[:port][,host[:port][/schema][[?parameter1=value1][¶meter2=value2],...]]
-jdbc:ignite:thin://host[:port][,host[:port][/schema][[?parameter1=value1][;parameter2=value2],...]]
-----
-
-* `host` is required and defines the host of the cluster node to connect to.
-* `port` is the port to use to open the connection. 10800 is used by default if this parameter is omitted.
-* `schema` is the schema name to access. PUBLIC is used by default. This name should correspond to the SQL ANSI-99 standard. Non-quoted identifiers are not case sensitive. Quoted identifiers are case sensitive. When semicolon format is used, the schema may be defined as a parameter with name schema.
-* `parameters` are optional parameters. The following parameters are available:
-** `connectionTimeZone` - Client connection time-zone ID. This property can be used by the client to change the time zone of the session on the server. Affects the interpretation of dates in queries that do not specify the time zone explicitly. If not set, system default on client timezone will be used.
-** `queryTimeout` - Number of seconds the driver will wait for a `Statement` object to execute. 0 means there is no limit. Default value: `0`.
-** `connectionTimeout` - Number of milliseconds JDBC client will wait for server to respond. 0 means there is no limit. Default value: `0`.
-** `reconnectThrottlingPeriod` - Reconnect throttling period, in milliseconds. 0 means there is no limit. Default value: `30_000`.
-** `reconnectThrottlingRetries` - Reconnect throttling retries. 0 means there is no limit. Default value: `3`.
-** `username` - username for basic authentication to the cluster.
-** `password` - user password for basic authentication to the cluster.
-** `sslEnabled` - Determines if SSL is enabled. Possible values: `true`, `false`. Default value: `false`
-*** `trustStorePath` - Path to trust store on client side.
-*** `trustStorePassword` - Trust store password.
-*** `keyStorePath` - Path to key store on client side.
-*** `keyStorePassword` - Key store password.
-*** `clientAuth` - SSL client authentication. Possible values: `NONE`, `OPTIONAL`, `REQUIRE`.
-*** `ciphers` - comma-separated SSL ciphers list.
-
-=== Parameter Precedence
-
-If the same parameters are passed by using different means, the JDBC driver prioritizes them in the following way:
-
-1. API arguments passed in the `Connection` objects;
-2. Last instance of the parameter in the connection string;
-3. Properties object passed during connection.
-
-== Performing Transactions
-
-With the JDBC driver, you can perform `commit` and `rollback` transactions. For more information about transactions, see link:developers-guide/transactions[Performing Transactions].
-
-Here is how you can commit a transaction:
-
-[source, java]
-----
-// Open the JDBC connection.
-Connection conn = DriverManager.getConnection("jdbc:ignite:thin://127.0.0.1:10800");
-
-// Commit a transaction
-conn.commit();
-----
-
-You can also configure Ignite to automatically commit transactions by using the `setAutoCommit()` method.
-
-Here is how you can rollback a transaction:
-
-[source, java]
-----
-conn.rollback();
-----
\ No newline at end of file
diff --git a/modules/jdbc/src/main/java/org/apache/ignite/jdbc/IgniteJdbcDriver.java b/modules/jdbc/src/main/java/org/apache/ignite/jdbc/IgniteJdbcDriver.java
index 37acfcb9f21..2a3ed145359 100644
--- a/modules/jdbc/src/main/java/org/apache/ignite/jdbc/IgniteJdbcDriver.java
+++ b/modules/jdbc/src/main/java/org/apache/ignite/jdbc/IgniteJdbcDriver.java
@@ -101,6 +101,12 @@ import org.jetbrains.annotations.Nullable;
* <br>By default no any timeout.</td>
* </tr>
* <tr>
+ * <td>partitionAwarenessMetadataCacheSize</td>
+ * <td>Size of cache to store partition awareness metadata of queries, in number of entries.
+ * <br>By default, the cache stores 1024 entries.
+ * <br>The value {@code 0} can be used to disable partition awareness.</td>
+ * </tr>
+ * <tr>
* <th colspan="2">Connection properties</th>
* </tr>
* <tr>