JDBC driver implementation for In-Memory Data Grid.
Driver allows to get distributed data from GridGain 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 GridGain 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):
-
Group by and sort by statements are applied separately
on each node, so result set will likely be incorrectly grouped or sorted
after results from multiple remote nodes are grouped together.
-
Aggregation functions like
sum, max, avg, etc.
are also applied on each node. Therefore you will get several results
containing aggregated values, one for each node.
-
Joins will work correctly only if joined objects are stored in
collocated mode. Refer to
GridCacheAffinityKey
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 GridGain JAR and depends on all libraries located in
GRIDGAIN_HOME/libs folder. So if you are using JDBC driver in any external tool,
you have to add main GridGain JAR will all dependencies to its classpath.
Internally JDBC driver
is based on GridGain Java client. Therefore, all client
configuration properties can be applied to JDBC connection.
JDBC connection URL has the following pattern:
jdbc:gridgain://<hostname>:<port>/<cache_name>?nodeId=<UUID>
Note the following:
- Hostname is required.
- If port is not defined,
11211 is used (default for GridGain 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 |
| gg.client.protocol |
Communication protocol (TCP or HTTP). |
TCP |
Yes |
| gg.client.connectTimeout |
Socket connection timeout. |
0 (infinite timeout) |
Yes |
| gg.client.tcp.noDelay |
Flag indicating whether TCP_NODELAY flag should be enabled for outgoing connections. |
true |
Yes |
| gg.client.ssl.enabled |
Flag indicating that SSL is needed for connection. |
false |
Yes |
| gg.client.ssl.protocol |
SSL protocol (SSL or TLS). |
TLS |
Yes |
| gg.client.ssl.key.algorithm |
Key manager algorithm. |
SunX509 |
Yes |
| gg.client.ssl.keystore.location |
Key store to be used by client to connect with GridGain topology. |
|
No (if SSL is enabled) |
| gg.client.ssl.keystore.password |
Key store password. |
|
Yes |
| gg.client.ssl.keystore.type |
Key store type. |
jks |
Yes |
| gg.client.ssl.truststore.location |
Trust store to be used by client to connect with GridGain topology. |
|
No (if SSL is enabled) |
| gg.client.ssl.truststore.password |
Trust store password. |
|
Yes |
| gg.client.ssl.truststore.type |
Trust store type. |
jks |
Yes |
| gg.client.credentials |
Client credentials used in authentication process. |
|
Yes |
| gg.client.cache.top |
Flag indicating that topology is cached internally. Cache will be refreshed in
the background with interval defined by gg.client.topology.refresh
property (see below).
|
false |
Yes |
| gg.client.topology.refresh |
Topology cache refresh frequency (ms). |
2000 |
Yes |
| gg.client.idleTimeout |
Maximum amount of time that connection can be idle before it is closed (ms). |
30000 |
Yes |
// Register JDBC driver.
Class.forName("org.gridgain.jdbc.GridJdbcDriver");
// Open JDBC connection.
Connection conn = DriverManager.getConnection("jdbc:gridgain://localhost/cache");
// 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");
...
}