IgniteJdbcDriver (GridGain 8.9.14)

java.lang.Object
- org.apache.ignite.IgniteJdbcDriver

All Implemented Interfaces:: Driver

public class IgniteJdbcDriver
extends Object
implements Driver

JDBC driver implementation for In-Memory Data Grid.

Driver allows to get distributed data from Ignite cache using standard SQL queries and standard JDBC API. It will automatically get only fields that you actually need from objects stored in cache.

Data in Ignite cache is usually distributed across several nodes, so some queries may not work as expected since the query will be sent to each individual node and results will then be collected and returned as JDBC result set. Keep in mind following limitations (not applied if data is queried from one node only, or data is fully co-located or fully replicated on multiple nodes):

Joins will work correctly only if joined objects are stored in collocated mode. Refer to AffinityKey javadoc for more details.
Note that if you are connected to local or replicated cache, all data will be queried only on one node, not depending on what caches participate in the query (some data from partitioned cache can be lost). And visa versa, if you are connected to partitioned cache, data from replicated caches will be duplicated.

Driver allows to query data from several caches. Cache that driver is connected to is treated as default schema in this case. Other caches can be referenced by their names.

Note that cache name is case sensitive and you have to always specify it in quotes.

JDBC driver is located in main Ignite JAR and depends on all libraries located in IGNITE_HOME/libs folder. So if you are using JDBC driver in any external tool, you have to add main Ignite JAR will all dependencies to its classpath. JDBC driver can return two different types of connection: Ignite Java client based connection and Ignite client node based connection. Java client best connection is deprecated and left only for compatibility with previous version, so you should always use Ignite client node based mode. It is also preferable because it has much better performance. The type of returned connection depends on provided JDBC connection URL. JDBC connection URL has the following pattern: jdbc:ignite:cfg://[<params>@]<config_url>.
<config_url> represents any valid URL which points to Ignite configuration file. It is required.
<params> are optional and have the following format: param1=value1:param2=value2:...:paramN=valueN.
The following parameters are supported:

cache - cache name. If it is not defined than default cache will be used.
nodeId - ID of node where query will be executed. It can be useful for querying through local caches. If node with provided ID doesn't exist, exception is thrown.
local - query will be executed only on local node. Use this parameter with nodeId parameter. Default value is false.
collocated - flag that used for optimization purposes. Whenever Ignite executes a distributed query, it sends sub-queries to individual cluster members. If you know in advance that the elements of your query selection are collocated together on the same node, usually based on some affinity-key, Ignite can make significant performance and network optimizations. Default value is false.
distributedJoins - enables support of distributed joins feature. This flag does not make sense in combination with local and/or collocated flags with true value or in case of querying of local cache. Default value is false.
enforceJoinOrder - Sets flag to enforce join order of tables in the query. If set to true query optimizer will not reorder tables in join. By default is false.
lazy - Sets flag to enable lazy query execution. By default Ignite attempts to fetch the whole query result set to memory and send it to the client. For small and medium result sets this provides optimal performance and minimize duration of internal database locks, thus increasing concurrency.
If result set is too big to fit in available memory this could lead to excessive GC pauses and even OutOfMemoryError. Use this flag as a hint for Ignite to fetch result set lazily, thus minimizing memory consumption at the cost of moderate performance hit.
Defaults to false, meaning that the whole result set is fetched to memory eagerly.

All Ignite Java client configuration properties can be applied to JDBC connection of this type.

JDBC connection URL has the following pattern: jdbc:ignite://<hostname>:<port>/<cache_name>?nodeId=<UUID>
Note the following:

Hostname is required.
If port is not defined, 11211 is used (default for Ignite client).
Leave <cache_name> empty if you are connecting to default cache.
Provide nodeId parameter if you want to specify node where to execute your queries. Note that local and replicated caches will be queried locally on this node while partitioned cache is queried distributively. If node ID is not provided, random node is used. If node with provided ID doesn't exist, exception is thrown.

Other properties can be defined in Properties object passed to DriverManager.getConnection(String, Properties) method:

Name	Description	Default	Optional
ignite.client.protocol	Communication protocol (`TCP` or `HTTP`).	`TCP`	Yes
ignite.client.connectTimeout	Socket connection timeout.	`0` (infinite timeout)	Yes
ignite.client.tcp.noDelay	Flag indicating whether TCP_NODELAY flag should be enabled for outgoing connections.	`true`	Yes
ignite.client.ssl.enabled	Flag indicating that `SSL` is needed for connection.	`false`	Yes
ignite.client.ssl.protocol	SSL protocol (`SSL` or `TLS`).	`TLS`	Yes
ignite.client.ssl.key.algorithm	Key manager algorithm.	`SunX509`	Yes
ignite.client.ssl.keystore.location	Key store to be used by client to connect with Ignite topology.		No (if `SSL` is enabled)
ignite.client.ssl.keystore.password	Key store password.		Yes
ignite.client.ssl.keystore.type	Key store type.	`jks`	Yes
ignite.client.ssl.truststore.location	Trust store to be used by client to connect with Ignite topology.		No (if `SSL` is enabled)
ignite.client.ssl.truststore.password	Trust store password.		Yes
ignite.client.ssl.truststore.type	Trust store type.	`jks`	Yes
ignite.client.credentials	Client credentials used in authentication process.		Yes
ignite.client.cache.top	Flag indicating that topology is cached internally. Cache will be refreshed in the background with interval defined by `ignite.client.topology.refresh` property (see below).	`false`	Yes
ignite.client.topology.refresh	Topology cache refresh frequency (ms).	`2000`	Yes
ignite.client.idleTimeout	Maximum amount of time that connection can be idle before it is closed (ms).	`30000`	Yes

 // Open JDBC connection.
 Connection conn = DriverManager.getConnection("jdbc:ignite:cfg//cache=persons@file:///etc/configs/ignite-jdbc.xml");

 // Query persons' names
 ResultSet rs = conn.createStatement().executeQuery("select name from Person");

 while (rs.next()) {
     String name = rs.getString(1);

     ...
 }

 // Query persons with specific age
 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");

     ...
 }

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`CFG_URL_PREFIX` Config URL prefix.
`static int`	`DFLT_PORT` Default port.
`static String`	`PARAM_ENFORCE_JOIN_ORDER` Parameter: enforce join order flag (SQL hint).
`static String`	`PARAM_LAZY` Parameter: replicated only flag (SQL hint).
`static String`	`PARAM_QRY_MAX_MEMORY` Parameter: query max memory.
`static String`	`PARAM_SCHEMA` Parameter: schema name.
`static String`	`PROP_CACHE` Cache name property name.
`static String`	`PROP_CFG` Cache name property name.
`static String`	`PROP_COLLOCATED` Collocated property name.
`static String`	`PROP_DISTRIBUTED_JOINS` Distributed joins property name.
`static String`	`PROP_ENFORCE_JOIN_ORDER` Transactions allowed property name.
`static String`	`PROP_HOST` Hostname property name.
`static String`	`PROP_LAZY` Lazy property name.
`static String`	`PROP_LOCAL` Local property name.
`static String`	`PROP_MULTIPLE_STMTS` Allow query with multiple statements.
`static String`	`PROP_NODE_ID` Node ID property name.
`static String`	`PROP_PORT` Port number property name.
`static String`	`PROP_QRY_MAX_MEMORY` Query max memory property name.
`static String`	`PROP_SCHEMA` Schema property name.
`static String`	`PROP_SKIP_REDUCER_ON_UPDATE` Skip reducer on update update property name.
`static String`	`PROP_STREAMING` DML streaming property name.
`static String`	`PROP_STREAMING_ALLOW_OVERWRITE` Whether DML streaming will overwrite existing cache entries.
`static String`	`PROP_STREAMING_FLUSH_FREQ` DML stream auto flush frequency property name.
`static String`	`PROP_STREAMING_PER_NODE_BUF_SIZE` DML stream node buffer size property name.
`static String`	`PROP_STREAMING_PER_NODE_PAR_OPS` DML stream parallel operations per node property name.
`static String`	`PROP_TX_ALLOWED` Transactions allowed property name.
`static String`	`URL_PREFIX` URL prefix.

Constructor Summary

Constructors
Constructor and Description

IgniteJdbcDriver()

Constructors
Constructor and Description
`IgniteJdbcDriver()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`acceptsURL(String url)`
`Connection`	`connect(String url, Properties props)`
`int`	`getMajorVersion()`
`int`	`getMinorVersion()`
`Logger`	`getParentLogger()`
`DriverPropertyInfo[]`	`getPropertyInfo(String url, Properties info)`
`boolean`	`jdbcCompliant()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - PARAM_ENFORCE_JOIN_ORDER
```
public static final String PARAM_ENFORCE_JOIN_ORDER
```
    Parameter: enforce join order flag (SQL hint).
    
    See Also:
    
    Constant Field Values
  - PARAM_LAZY
```
public static final String PARAM_LAZY
```
    Parameter: replicated only flag (SQL hint).
    
    See Also:
    
    Constant Field Values
  - PARAM_SCHEMA
```
public static final String PARAM_SCHEMA
```
    Parameter: schema name.
    
    See Also:
    
    Constant Field Values
  - PARAM_QRY_MAX_MEMORY
```
public static final String PARAM_QRY_MAX_MEMORY
```
    Parameter: query max memory.
    
    See Also:
    
    Constant Field Values
  - PROP_HOST
```
public static final String PROP_HOST
```
    Hostname property name.
    
    See Also:
    
    Constant Field Values
  - PROP_PORT
```
public static final String PROP_PORT
```
    Port number property name.
    
    See Also:
    
    Constant Field Values
  - PROP_CACHE
```
public static final String PROP_CACHE
```
    Cache name property name.
    
    See Also:
    
    Constant Field Values
  - PROP_NODE_ID
```
public static final String PROP_NODE_ID
```
    Node ID property name.
    
    See Also:
    
    Constant Field Values
  - PROP_LOCAL
```
public static final String PROP_LOCAL
```
    Local property name.
    
    See Also:
    
    Constant Field Values
  - PROP_COLLOCATED
```
public static final String PROP_COLLOCATED
```
    Collocated property name.
    
    See Also:
    
    Constant Field Values
  - PROP_DISTRIBUTED_JOINS
```
public static final String PROP_DISTRIBUTED_JOINS
```
    Distributed joins property name.
    
    See Also:
    
    Constant Field Values
  - PROP_TX_ALLOWED
```
public static final String PROP_TX_ALLOWED
```
    Transactions allowed property name.
    
    See Also:
    
    Constant Field Values
  - PROP_STREAMING
```
public static final String PROP_STREAMING
```
    DML streaming property name.
    
    See Also:
    
    Constant Field Values
  - PROP_STREAMING_FLUSH_FREQ
```
public static final String PROP_STREAMING_FLUSH_FREQ
```
    DML stream auto flush frequency property name.
    
    See Also:
    
    Constant Field Values
  - PROP_STREAMING_PER_NODE_BUF_SIZE
```
public static final String PROP_STREAMING_PER_NODE_BUF_SIZE
```
    DML stream node buffer size property name.
    
    See Also:
    
    Constant Field Values
  - PROP_STREAMING_PER_NODE_PAR_OPS
```
public static final String PROP_STREAMING_PER_NODE_PAR_OPS
```
    DML stream parallel operations per node property name.
    
    See Also:
    
    Constant Field Values
  - PROP_STREAMING_ALLOW_OVERWRITE
```
public static final String PROP_STREAMING_ALLOW_OVERWRITE
```
    Whether DML streaming will overwrite existing cache entries.
    
    See Also:
    
    Constant Field Values
  - PROP_MULTIPLE_STMTS
```
public static final String PROP_MULTIPLE_STMTS
```
    Allow query with multiple statements.
    
    See Also:
    
    Constant Field Values
  - PROP_SKIP_REDUCER_ON_UPDATE
```
public static final String PROP_SKIP_REDUCER_ON_UPDATE
```
    Skip reducer on update update property name.
    
    See Also:
    
    Constant Field Values
  - PROP_ENFORCE_JOIN_ORDER
```
public static final String PROP_ENFORCE_JOIN_ORDER
```
    Transactions allowed property name.
    
    See Also:
    
    Constant Field Values
  - PROP_LAZY
```
public static final String PROP_LAZY
```
    Lazy property name.
    
    See Also:
    
    Constant Field Values
  - PROP_SCHEMA
```
public static final String PROP_SCHEMA
```
    Schema property name.
    
    See Also:
    
    Constant Field Values
  - PROP_QRY_MAX_MEMORY
```
public static final String PROP_QRY_MAX_MEMORY
```
    Query max memory property name.
    
    See Also:
    
    Constant Field Values
  - PROP_CFG
```
public static final String PROP_CFG
```
    Cache name property name.
    
    See Also:
    
    Constant Field Values
  - URL_PREFIX
```
public static final String URL_PREFIX
```
    URL prefix.
    
    See Also:
    
    Constant Field Values
  - CFG_URL_PREFIX
```
public static final String CFG_URL_PREFIX
```
    Config URL prefix.
    
    See Also:
    
    Constant Field Values
  - DFLT_PORT
```
public static final int DFLT_PORT
```
    Default port.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - IgniteJdbcDriver
```
public IgniteJdbcDriver()
```
- Method Detail
  - connect
```
public Connection connect(String url,
                          Properties props)
                   throws SQLException
```
    Specified by:
    
    connect in interface Driver
    
    Throws:
    
    SQLException
  - acceptsURL
```
public boolean acceptsURL(String url)
                   throws SQLException
```
    Specified by:
    
    acceptsURL in interface Driver
    
    Throws:
    
    SQLException
  - getPropertyInfo
```
public DriverPropertyInfo[] getPropertyInfo(String url,
                                            Properties info)
                                     throws SQLException
```
    Specified by:
    
    getPropertyInfo in interface Driver
    
    Throws:
    
    SQLException
  - getMajorVersion
```
public int getMajorVersion()
```
    Specified by:
    
    getMajorVersion in interface Driver
  - getMinorVersion
```
public int getMinorVersion()
```
    Specified by:
    
    getMinorVersion in interface Driver
  - jdbcCompliant
```
public boolean jdbcCompliant()
```
    Specified by:
    
    jdbcCompliant in interface Driver
  - getParentLogger
```
public Logger getParentLogger()
                       throws SQLFeatureNotSupportedException
```
    Specified by:
    
    getParentLogger in interface Driver
    
    Throws:
    
    SQLFeatureNotSupportedException

Class IgniteJdbcDriver

Description

Limitations

SQL Notice

Dependencies

Configuration

Configuration of Ignite client node based connection

Configuration of Ignite Java client based connection

Example

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PARAM_ENFORCE_JOIN_ORDER

PARAM_LAZY

PARAM_SCHEMA

PARAM_QRY_MAX_MEMORY

PROP_HOST

PROP_PORT

PROP_CACHE

PROP_NODE_ID

PROP_LOCAL

PROP_COLLOCATED

PROP_DISTRIBUTED_JOINS

PROP_TX_ALLOWED

PROP_STREAMING

PROP_STREAMING_FLUSH_FREQ

PROP_STREAMING_PER_NODE_BUF_SIZE

PROP_STREAMING_PER_NODE_PAR_OPS

PROP_STREAMING_ALLOW_OVERWRITE

PROP_MULTIPLE_STMTS

PROP_SKIP_REDUCER_ON_UPDATE

PROP_ENFORCE_JOIN_ORDER

PROP_LAZY

PROP_SCHEMA

PROP_QRY_MAX_MEMORY

PROP_CFG

URL_PREFIX

CFG_URL_PREFIX

DFLT_PORT

Constructor Detail

IgniteJdbcDriver

Method Detail

connect

acceptsURL

getPropertyInfo

getMajorVersion

getMinorVersion

jdbcCompliant

getParentLogger