The SingleStore JDBC Driver
On this page
The SingleStore JDBC Driver can be used to connect your SingleStore databases to Java-based applications, like BI and ETL tools.
Driver Compatibility
The SingleStore JDBC Driver is compatible with:
-
Java 21, Java 17, Java 11, and Java 8
-
JDBC 4.
2 -
SingleStore v7.
5+. Refer to the following compatibility matrix for information on SingleStore database version supported for each SingleStore JDBC driver version.
Prerequisites
To build the SingleStore JDBC Driver from source, you'll need:
-
Java JDK
Note
Maven is not an absolute requirement for using the driver with other applications.
Download and Install the SingleStore JDBC Driver
You can install the SingleStore JDBC Driver with any of the following methods.
Note
To find the latest version of the driver, see SingleStore JDBC Driver Releases on GitHub.
Install with Maven
Include the following dependency in your pom.
file, to install the driver using Maven.<version></version>
with the version you want to use:
<dependency><groupId>com.singlestore</groupId><artifactId>singlestore-jdbc-client</artifactId><version>x.x.x</version></dependency>
Install without Maven
If your project does not use Maven, you can download the .
from GitHub or Maven Repository and include it in your project (install in your CLASSPATH
) to use it.
Build from Source
To build the SingleStore JDBC Driver from source, follow these steps:
-
Clone the S2-JDBC-Connector repository using the following command:
git clone https://github.com/memsql/S2-JDBC-Connector.git -
Execute the following command from the root of the repository:
mvn -Dmaven.test.skip -Dmaven.javadoc.skip packageThis command generates a
singlestore-jdbc-client-<version>.
file in thejar target
subdirectory.Install this file in a directory in your JAVA CLASSPATH
to use the driver.
Use the SingleStore JDBC Driver
There are two methods to connect using the SingleStore JDBC Driver: using the DriverManager class or using a connection pool.
Note
To use the SingleStore JDBC Driver in external applications, specify the JDBC Driver Class as com.
Connection String Format
The connection string must have the following format:
jdbc:singlestore:[loadbalance:|sequential:]//<hostDescription>[,<hostDescription>...]/[database][?<key1>=<value1>[&<key2>=<value2>]]hostDescription:<host>[:port] | address=(host=<host>)[(port=<port>)][(type=(master|slave))]
-
The default for port is
3306
.The default host type is master
. -
The host must be an IP address or DNS name.
If the host is an IPv6 address, then it must be enclosed within square brackets.
See Connection String Parameters for more information.
"jdbc:singlestore://localhost:3306/test?user=root&password=myPassword"
Connect using the DriverManager
Class
The DriverManager class automatically configures the application and loads the SingleStore JDBC Driver.DriverManager
class:
Connection connection = DriverManager.getConnection("jdbc:singlestore://localhost:3306/test?user=root&password=myPassword");Statement stmt = connection.createStatement();ResultSet rs = stmt.executeQuery("SELECT NOW()");rs.next();System.out.println(rs.getTimestamp(1));
Connect using the Connection Pool
You can also get a connection with SingleStore JDBC Driver via a connection pool.
-
The
SingleStoreDataSource
is a basic implementation that returns a new connection each time thegetConnection()
method is called. -
The
SingleStorePoolDataSource
is a connection pool implementation that maintains a pool of connections.A connection is borrowed from the pool each time a new connection is requested.
Failover and Load-Balancing Modes
The SingleStore JDBC Driver supports the following failover/load-balancing modes:
Mode |
Description |
---|---|
|
In this mode, the driver tries to connect with the hosts in the order in which they are declared in the connection string. |
|
The driver randomly selects a host from the connection string, for each connection, to perform load-balancing on all the queries. |
Connection String Parameters
The SingleStore JDBC Driver supports the following parameters in the connection string.
Essential Parameters
Parameter |
Description |
Default Value |
Supported Driver Version |
---|---|---|---|
|
Username for the database. |
1. |
|
|
The password of the database user. |
1. |
|
|
The connection timeout value (in ms). |
30000 |
1. |
|
Enables using PrepareStatements. |
|
1. |
|
Allows users to load data from the local filesystem. |
|
1. |
TLS Parameters
Parameter |
Description |
Default Value |
Supported Driver Version |
---|---|---|---|
|
Specifies the SSL/TLS mode.
The following parameters can override the behavior of
Refer to |
|
1. |
|
Specifies a comma-separated list of TLS ciphers. For example, |
1. |
|
|
Specifies a comma-separated list of TLS versions. For example, |
1. |
|
|
Specifies the path of the |
1. |
|
|
Specifies the password for the |
1. |
|
|
Specifies the key store type, for example, JKS and PKCS12. |
1. |
|
|
Specifies the password for the private key in the client certificate |
1. |
|
|
Use this parameter to specify the server's certificate in DER format or specify the server's CA certificate. You can specify the server certificate in one of the following formats:
|
1. |
|
|
Specifies the path of the |
1. |
|
|
Specifies the password for the trusted root certificate file. |
1. |
|
|
Specifies the trust store type, for example, JKS and PKCS12. |
|
1. |
|
Disables hostname verification against the server's identity as specified in the server's certificate to prevent man-in-the-middle attacks. Refer to |
|
1. |
|
Enable this parameter to skip checking the server's certificate when used in conjunction with SSL/TLS. Refer to |
|
1. |
|
Force enables SSL/TLS on the connection. Refer to |
|
1. |
sslMode
and useSsl
Behavior
The sslMode
and useSsl
parameters can both be used to enable SSL/TLS on the connection.useSsl
parameter can override the value of sslMode
parameter when used in conjunction with the disableSslHostnameVerification
and trustServerCertificate
parameters.
The following table shows the equivalent sslMode
for different combinations of useSsl
, disableSslHostnameVerification
, and trustServerCertificate
|
|
|
Equivalent |
---|---|---|---|
|
Ignored |
Ignored |
|
|
|
Ignored |
|
|
|
|
|
|
|
|
|
Pool Parameters
Parameter |
Description |
Default Value |
Supported Driver Version |
---|---|---|---|
|
Specifies that the connection uses a connection pool. |
|
1. |
|
Specifies the pool name that allows identifying threads. |
SingleStore-pool-<pool-index> |
1. |
|
Specifies the maximum number of physical connections for a connection pool. |
8 |
1. |
|
Specifies the minimum number of physical connections that must always be available in a connection pool. |
|
1. |
|
Disables connection state validation for connections that request a new connection within the time limit specified through |
1000 |
1. |
|
Specifies the maximum amount of time (in |
600 |
1. |
|
When enabled, resets the connection state, deletes the prepare command, resets the session variables, and removes the user variables. |
|
1. |
Log Parameters
Parameter |
Description |
Default Value |
Supported Driver Version |
---|---|---|---|
|
Enables information logging. |
|
|
|
Specifies the size of the query statement to include in the log. |
1024 |
1. |
|
Logs queries with execution time greater than the value specified using this parameter. |
1024 |
|
|
Enables logging the query execution time. |
|
Other Parameters
Parameter |
Description |
Default Value |
Supported Driver Version |
---|---|---|---|
|
Enables multi-query statements. |
|
1. |
|
Sets the |
|
1. |
|
Returns a blank value for table name in the |
|
1. |
|
If |
|
1. |
|
Set client information in |
1. |
|
|
Specifies the path of the console log file. |
|
1. |
|
Specifies the console log level. |
|
1. |
|
When enabled, the database specified in the connection string is created if it doesn't already exist. |
|
1. |
|
Specifies the credential plugin type. |
1. |
|
|
Calls the |
0 |
1. |
|
Enables logging the query string when an exception is thrown during query execution. |
|
1. |
|
Adds thread dump to exception trace log in case of a deadlock exception. |
|
1. |
|
Specifies the commands to run when a new connection is created. |
1. |
|
|
Enables connecting to a database socket via a UNIX domain socket (if allowed by the server). |
1. |
|
|
Binds the specified hostname or IP address to a local (UNIX domain) socket. |
1. |
|
|
If enabled, allows the driver to avoid sending commands with packet size greater than max_ |
1. |
|
|
Limits the number of stack trace lines to log. |
|
1. |
|
If |
250 |
1. |
|
When enabled, it prints the stack trace for the |
|
1. |
|
Specifies a comma-separated list of client authentication plugins to allow. For example, the following connection string only allows the
|
|
1. |
|
If enabled, sends multiple rows in a single query. |
|
1. |
|
Sets SingleStore session variables specified as <var_ |
||
|
Specifies the name of the custom socket factory to use. |
1. |
|
|
Specifies the network socket timeout (in ms). |
0 |
1. |
|
Resets TCP connections (through abort or hard close) instead of orderly closing connections. |
1. |
|
|
Enables |
|
1. |
|
Specifies the number of keepalive probes (checks) sent to check if the connection is active before the connection is considered closed if no response is received. This parameter is only supported in Java version 11+. |
|
1. |
|
Specifies the timeout (in seconds) the connection can remain idle before sending keepalive probes (checks). This parameter is only supported in Java version 11+. |
|
1. |
|
Specifies the interval (in seconds) between each keepalive probe (check) sent if a response is not received for a previous probe. This parameter is only supported in Java version 11+. |
|
1. |
|
Maps MySQL Tiny data type to BIT (boolean) data type. |
|
1. |
|
Uses the TLS |
1. |
|
|
Maps the |
|
1. |
|
Enables using a buffered |
|
1. |
|
Converts year values from numerical to |
|
1. |
Failover and Load Balancing Parameters
Parameter |
Description |
Default Value |
Supported Driver Version |
---|---|---|---|
|
Specifies the maximum time until the driver retries connection attempts before throwing an exception, when the driver is performing a failover and all hosts are down. |
120 |
1. |
|
Specifies the time duration a failed host remains in the denied list when the connector is performing a failover. |
60 |
1. |
|
Specifies if the current transaction can have a completely transparent failover. |
|
1. |
|
Specifies the maximum size limit for the replay cache buffer. |
|
1. |
Last modified: December 4, 2024