Connect to a GemFire XD Server with the Thin Client JDBC Driver

The thin client driver class is packaged in com.pivotal.gemfirexd.jdbc.ClientDriver. In addition to the basic JDBC Connection URL, you specify the host and port number of a GemFire XD server or a locator to which the thin client driver will connect.

For example:

Code Example

This code sample shows a more complete example of connecting to a GemFire XD server in a Java application:
        try {
        // 1527 is the default port that a GemFire XD server uses to listen for thin client connections
        Connection conn =
        // do something with the connection

        } catch (SQLException ex) {
        // handle any errors
        System.out.println("SQLException: " + ex.getMessage());
        System.out.println("SQLState: " + ex.getSQLState());
        System.out.println("VendorError: " + ex.getErrorCode());

Thin Client Failover

When you use the thin client to connect to a GemFire XD locator member (rather than directly to a GemFire XD server), the thin client driver can provide automatic failover if the initial connection to the distributed system is lost. See locator. Note, however, that this assumes the initial connection to the specified GemFire XD locator succeeds. To improve the chances of establishing an initial connection to a GemFire XD system, use the secondary-locators property to specify the addresses of one or more secondary locators try if the primary locator cannot be reached. For example:

Enabling Single-Hop Data Access

By default, using the thin-client driver provides either one-hop or two-hop access to the data for executing queries or DML statements. One-hop access is available if the client's SQL statements work against data that happens to reside on the GemFire XD member to which the thin client has connected. All other cases result in one-hop or two-hop access to the data: the SQL statement is evaluated first on the GemFire XD member to which the client is connected, and if necessary, that server routes the query to other members in the cluster that host the actual data for the statement.

GemFire XD provides the option to provide single-hop access to data for certain queries when using a thin client connection. To use this option, set the single-hop-enabled connection property to true when connecting with the thin client driver. For example:
Or, from within the gfxd utility:
connect client 'myHostName:1527/;single-hop-enabled=true'
Note: Single-hop access for thin clients requires GemFire XD data store members in the distributed system to run a network server for direct client access. Configure each data store with network server functionality even if you use a locator for member discovery. See Starting a Network Server.

Single-hop access is provided only for prepared statements. When you enable single-hop access on a connection and then prepare a prepared statement, the local GemFire XD server adds data distribution information to other GemFire XD server members in the response of the prepare message. When the prepared statement is executed, the client uses the added parameter and information fetched from the connected server to determine the exact GemFire XD server on which it can find the data locally; it then directs the execution to that server.

The following types of queries are good candidates for single-hop access:
  • Queries that have a WHERE clause on the partitioning columns of a table.
  • Primary key-based SELECT statements where the primary key is also the partitioning key.
  • IN-based WHERE clauses on partitioning columns.

If the client cannot determine the location of the data based on the WHERE clause, then it defaults to standard two-hop execution. Single-hop execution is performed only when the client can be absolutely certain of the location of data that is touched by the query.

Internally, the client JVM maintains a pool of connections that is shared by all of the prepared statements that might execute statements with single-hop access. For each GemFire XD server, the client maintains a queue of connections that can grow to a maximum number of connection specified by the gemfirexd.client.single-hop-max-connections system property. After this maximum number of connections has been created for a particular server, further single-hop executions must wait for a connection to become available in the queue. If the number of connections created for a particular GemFire XD server has not reached the maximum, then the client creates a new connection on the fly, uses it, and then returns it back to the connection. The default value for gemfirexd.client.single-hop-max-connections is 5 connections per server. If you are developing a client that requires more concurrent connections per server for single-hop access, increase the maximum number of connections per server using the gemfirexd.client.single-hop-max-connections system property.

Note: To avoid degrading the performance of the network server, use the smallest number of concurrent single-hop threads that satisfy performance requirements.

Configuring TCP Keepalive Settings

By default, GemFire XD servers use a TCP keepalive probe to help determine when clients have gone offline. GemFire XD thin clients can also use these keepalive settings to accurately determine when a server has gone offline. The relevant configuration properties are:
Note: Windows platforms do not support per-socket configuration for keepalive-count. As an alternative, you can configure a system-wide keepalive-count value in some versions of Windows. See Windows Vista and later versions keep this value fixed at 10.
Note: On Solaris platforms prior to r10, system-wide TCP keepalive settings must be changed to larger values (approximately 30 seconds) in order to detect server failures by clients and vice versa. See This also applies to other non-Linux, non-Windows platforms. For example, see

Thin Client Driver Limitations

When the default batching mode is enabled for transactions, GemFire XD detects any conflicts in DML operations lazily. DML conflicts may be thrown by the system at some point later in the transaction (for example, even when executing queries or at commit time). You can configure GemFire XD to immediately detect conflicts at operation time by setting the gemfire.tx-disable-batching system property to "true" on all data store members in the distributed system.

Note: Enabling gemfire.tx-disable-batching can degrade performance significantly. Enable this option only after you have thoroughly tested the setting in your system and have determined that the performance tradeoff is necessary to provide immediate conflict detection with thin clients.

If you use the thin client driver to perform an insert to table that has no primary key, an automatic retry of the insert due to a failover (available when connecting via a locator member) can result in duplicate rows being added to the table.

The thin-client driver has the following limitations when the single-hop connection property is enabled:
  • Single-hop access is not provided when using transactions or WAN replication.
    Note: Do not enable single-hop access when using transactions or WAN configurations, as it can lead to unexpected behavior.
  • GemFire XD does not support single hop connections when used in combination with JDBC connection pooling options such dbcp and c3po.
  • Single-hop access is only supported for partitioned tables where the partitioning column(s) are of the basic data types: integer, long, double, decimal, char, varchar, and real. If a table is partitioned on a column having any other data type (like date, time, timestamp, blob, clob, and so forth), then queries on that tables are not considered for single-hop execution.
  • Single hop execution is attempted only for prepared statements, and not for simple statements.
  • Single hop execution is attempted only for SELECT, UPDATE and DELETE statements, but not for INSERT statements.
  • GemFire XD does not support single-hop access for queries that require data from multiple data stores to be merged together. Typically, queries having aggregates like MAX, MIN, AVG, ORDER BY, and so forth are executed as if single-hop were disabled. If an aggregate query can provide all results from a single data store, then GemFire XD provides single-hop access for the query.
  • Tables that have an expression resolver are not considered for single-hop access.