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 |
---|---|---|---|
|
Force enables SSL/TLS on the connection. |
|
1. |
|
Enable this parameter to skip checking the server's certificate when used in conjunction with SSL/TLS. |
|
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 keyStore file that contains the client private keys and associated certificates. |
1. |
|
|
Specifies the password for the |
1. |
|
|
Specifies the password for the private key in the client certificate |
1. |
|
|
Specifies the path of the |
1. |
|
|
Specifies the password for the trusted root certificate file. |
1. |
|
|
Disables hostname verification against the server's identity as specified in the server's certificate to prevent man-in-the-middle attacks. |
|
1. |
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. |
|
Enables logging the query string when an exception is thrown during query execution. |
|
1. |
|
Specifies the name of the custom socket factory to use. |
1. |
|
|
Enables |
1. |
|
|
Resets TCP connections (through abort or hard close) instead of orderly closing connections. |
1. |
|
|
Maps MySQL Tiny data type to BIT (boolean) data type. |
|
1. |
|
Maps the |
|
1. |
|
Converts year values from numerical to |
|
1. |
|
Sets SingleStore session variables specified as <var_ |
||
|
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. |
|
|
Specifies the network socket timeout (in ms). |
0 |
1. |
|
If |
|
1. |
|
If |
250 |
1. |
|
Set client information in |
1. |
|
|
Sets the |
|
1. |
|
Adds thread dump to exception trace log in case of a deadlock exception. |
|
1. |
|
Enables using a buffered |
|
1. |
|
Calls the |
0 |
1. |
|
Returns a blank value for table name in the |
|
1. |
|
Uses the TLS |
1. |
|
|
Specifies the credential plugin type. |
1. |
|
|
If enabled, sends multiple rows in a single query. |
|
1. |
|
When enabled, the database specified in the connection string is created if it doesn't already exist. |
|
1. |
|
Specifies the commands to run when a new connection is created. |
1. |
|
|
Specifies the console log level. |
|
1. |
|
Specifies the path of the console log file. |
|
1. |
|
When enabled, it prints the stack trace for the |
|
1. |
|
Limits the number of stack trace lines to log. |
|
1. |
|
If enabled, allows the driver to avoid sending commands with packet size greater than max_ |
1. |
|
|
Specifies if the current transaction can have a completely transparent failover. |
|
1. |
|
Specifies the maximum size limit for the replay cache buffer. |
|
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. |
Last modified: October 4, 2024