org.apache.ignite

Class IgniteJdbcDriver

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.

Limitations

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.

SQL Notice

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.

Dependencies

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.

Configuration

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.

Configuration of Ignite client node based connection

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.

Configuration of Ignite Java client based connection

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

Example

 // Register JDBC driver.
 Class.forName("org.apache.ignite.IgniteJdbcDriver");

 // 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	PROP_CACHE Cache name property name.
static String	PROP_CFG Cache name property name.
static String	PROP_COLLOCATED Collocated property name.
static String	PROP_HOST Hostname property name.
static String	PROP_LOCAL Local property name.
static String	PROP_NODE_ID Node ID property name.
static String	PROP_PORT Port number property name.
static String	URL_PREFIX URL prefix.

Constructor Summary

Constructors

Constructor and Description
IgniteJdbcDriver()

Method Summary

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

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_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