SingleStore JDBC Driver

Version: 1.2.7-beta0

SingleStore JDBC Driver is a JDBC 4.2 compatible driver, used to connect applications developed in Java to SingleStore and MySQL databases. SingleStore JDBC Driver is LGPL licensed.

Status

Obtaining the driver

The driver (jar) can be downloaded from maven :

<dependency>
	<groupId>com.singlestore</groupId>
	<artifactId>singlestore-jdbc-client</artifactId>
	<version>1.2.6</version>
</dependency>

Usage

To get a connection using SingleStore JDBC Driver, you need a connection string of the following format:

jdbc:singlestore:[loadbalance:|sequential:]//<hostDescription>[,<hostDescription>...]/[database][?<key1>=<value1>[&<key2>=<value2>]] 

Example:

"jdbc:singlestore://localhost:3306/test?user=root&password=myPassword"

You can then get a connection by using the Driver manager 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));

Another way to get a connection with SingleStore JDBC Driver is to use a connection pool.

• SingleStorePoolDataSource is an implementation that maintains a pool of connections. When a new connection is requested, one is borrowed from the pool.
• SingleStoreDataSource is a basic implementation that just returns a new connection each time the getConnection() method is called.

Example:

SingleStorePoolDataSource pool = new SingleStorePoolDataSource("jdbc:singlestore://server/db?user=myUser&maxPoolSize=10");

    try (Connection connection = pool.getConnection()) {
        try (Statement stmt = connection.createStatement()) {
            ResultSet rs = stmt.executeQuery("SELECT NOW()");
            rs.next();
            System.out.println(rs.getTimestamp(1));
        }
    }

Extended types support

SingleStore supports extended types metadata starting from database version 8.7.1. Enable the enable_extended_types_metadata session engine variable to use extended types in SingleStore. By default, support for extended types is disabled for backward compatibility and the database uses the standard data type format.

To correctly handle the extended type metadata with the SingleStore JDBC driver, set the enableExtendedDataTypes parameter to true. This parameter is only supported in SingleStore JDBC driver version 1.2.6 and later. By default, enableExtendedDataTypes is set to false. Note: Based on the value of the enableExtendedDataTypes parameter, the driver automatically configures the value of enable_extended_types_metadata engine variable while initializing the connection, which overrides the current value of this engine variable.

Extended types:

Data Type	Updates
Vector	Added com.singlestore.jdbc.type.Vector type to read/write Vector data. Updated metadata methods.
BSON	Updated metadata methods.

Example

Connection connection = DriverManager.getConnection("jdbc:singlestore://localhost:3306/test?user=root&password=myPassword&enableExtendedDataTypes=true&vectorTypeOutputFormat=JSON");
Statement stmt = connection.createStatement();

stmt.execute("CREATE TABLE extended_types (a1 VECTOR(3, I16), a2 BSON)");

PreparedStatement pstmt = connection.prepareStatement("INSERT INTO extended_types VALUES(?, '{\"a1\":\"test\"}' :> BSON)");

pstmt.setObject(1, Vector.ofInt16Values(new short[]{1, 2, 3}));
pstmt.execute();

ResultSet rs = stmt.executeQuery("SELECT * FROM extended_types");
rs.next();
Vector vector = (Vector) rs.getObject(1);
SingleStoreBlob bson = (SingleStoreBlob) rs.getObject(2);
System.out.println(vector);

Building from source

Requirements

• Maven
• JDK 11

Clone the respository:

git clone https://github.com/memsql/S2-JDBC-Connector.git

Execute the following from the repository root to build SingleStore JDBC Driver from source:

mvn -Dmaven.test.skip -Dmaven.javadoc.skip package

This generates a singlestore-jdbc-client-<version>.jar file in target/ directory. Install this file to a directory in your CLASSPATH to use the driver.

Documentation

For the documentation and a getting started guide refer to SingleStore Documentation

User agreement

SINGLESTORE, INC. ("SINGLESTORE") AGREES TO GRANT YOU AND YOUR COMPANY ACCESS TO THIS OPEN SOURCE SOFTWARE CONNECTOR ONLY IF (A) YOU AND YOUR COMPANY REPRESENT AND WARRANT THAT YOU, ON BEHALF OF YOUR COMPANY, HAVE THE AUTHORITY TO LEGALLY BIND YOUR COMPANY AND (B) YOU, ON BEHALF OF YOUR COMPANY ACCEPT AND AGREE TO BE BOUND BY ALL OF THE OPEN SOURCE TERMS AND CONDITIONS APPLICABLE TO THIS OPEN SOURCE CONNECTOR AS SET FORTH BELOW (THIS “AGREEMENT”), WHICH SHALL BE DEFINITIVELY EVIDENCED BY ANY ONE OF THE FOLLOWING MEANS: YOU, ON BEHALF OF YOUR COMPANY, CLICKING THE “DOWNLOAD, “ACCEPTANCE” OR “CONTINUE” BUTTON, AS APPLICABLE OR COMPANY’S INSTALLATION, ACCESS OR USE OF THE OPEN SOURCE CONNECTOR AND SHALL BE EFFECTIVE ON THE EARLIER OF THE DATE ON WHICH THE DOWNLOAD, ACCESS, COPY OR INSTALL OF THE CONNECTOR OR USE ANY SERVICES (INCLUDING ANY UPDATES OR UPGRADES) PROVIDED BY SINGLESTORE.

NOTWITHSTANDING ANYTHING TO THE CONTRARY IN ANY DOCUMENTATION, AGREEMENT OR IN ANY ORDER DOCUMENT, SINGLESTORE WILL HAVE NO WARRANTY, INDEMNITY, SUPPORT, OR SERVICE LEVEL, OBLIGATIONS WITH RESPECT TO THIS SOFTWARE CONNECTOR (INCLUDING TOOLS AND UTILITIES).

APPLICABLE OPEN SOURCE LICENSE: GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999

IF YOU OR YOUR COMPANY DO NOT AGREE TO THESE TERMS AND CONDITIONS, DO NOT DOWNLOAD, ACCESS, COPY, INSTALL OR USE THE SOFTWARE OR THE SERVICES.