Skip to main content
Version: 3.12

ScalarDB JDBC Guide

The usage of ScalarDB JDBC basically follows Java JDBC API. This guide describes several important topics that are specific to ScalarDB JDBC.

Add ScalarDB JDBC driver to your project

You need to add dependencies for ScalarDB JDBC driver and the connection mode you want to use to your project to use ScalarDB JDBC.

Direct mode

To add the dependencies on ScalarDB JDBC driver with Direct mode using Gradle, use the following:

dependencies {
implementation 'com.scalar-labs:scalardb-sql-jdbc:<version>'
implementation 'com.scalar-labs:scalardb-sql-direct-mode:<version>'

To add the dependencies using Maven:


Server mode

To add the dependencies on ScalarDB JDBC driver with Server mode using Gradle, use the following:

dependencies {
implementation 'com.scalar-labs:scalardb-sql-jdbc:<version>'
implementation 'com.scalar-labs:scalardb-sql-server-mode:<version>'

To add the dependencies using Maven:


Please see ScalarDB SQL Server for the details of the ScalarDB SQL Server.

JDBC connection URL

The JDBC connection URL format of ScalarDB JDBC is as follows:

jdbc:scalardb:<configuration file path>?<property name>=<property value>&<property name>=<property value>&...

For example:

Only specify configuration file path:


Only specify properties:


Specify configuration file path and properties:


Configurations for ScalarDB JDBC

The configurations for ScalarDB JDBC are as follows:

scalar.db.sql.jdbc.default_auto_commitThe default connection's auto-commit mode.true
scalar.db.sql.jdbc.sql_session_factory_cache.expiration_time_millisThe expiration time in milliseconds for the cache of SQL session factories.10000

Data type mapping between ScalarDB and JDBC

Since ScalarDB doesn't support all the data types defined in JDBC, the following explains the data type mapping between ScalarDB and JDBC.

The data type mapping between ScalarDB and JDBC is as follows:

ScalarDB TypeJDBC (Java) Type
Booleanboolean or Boolean
Intint or Integer
BigIntlong or Long
Floatfloat or Float
Doubledouble or Double

How to get the data from a java.sql.ResultSet object for each data type is as follows:

try (ResultSet resultSet = ...) {;

// Get a Boolean value of a column
boolean booleanValue = resultSet.getBoolean("<column name>");

// Get an Int value of a column
int intValue = resultSet.getInt("<column name>");

// Get a BigInt value of a column
long bigIntValue = resultSet.getLong("<column name>");

// Get a Float value of a column
float floatValue = resultSet.getFloat("<column name>");

// Get a Double value of a column
double doubleValue = resultSet.getDouble("<column name>");

// Get a Text value of a column
String textValue = resultSet.getString("<column name>");

// Get a Blob value of a column
byte[] blobValue = resultSet.getBytes("<column name>");

How to set the data as a parameter for each data type for a java.sql.PreparedStatement object is as follows:

try (PreparedStatement preparedStatement = ...) {
// Set a Boolean value as parameter
preparedStatement.setBoolean(1, <Boolean value>);

// Set an Int value as parameter
preparedStatement.setInt(2, <Int value>);

// Set a BigInt value as parameter
preparedStatement.setLong(3, <BigInt value>);

// Set a Float value as parameter
preparedStatement.setFloat(4, <Float value>);

// Set a Double value as parameter
preparedStatement.setDouble(5, <Double value>);

// Set a Text value as parameter
preparedStatement.setString(7, "<Text value>");

// Set a Blob value as parameter
preparedStatement.setBytes(8, <Blob value>);


Handle SQLException

The exception handling is basically the same as ScalarDB SQL API as follows:

// If you execute multiple statements in a transaction, you need to set auto-commit to false.

try {
// Execute statements (SELECT/INSERT/UPDATE/DELETE) in the transaction

// Commit the transaction
} catch (SQLException e) {
if (e.getErrorCode() == 301) {
// The error code 301 indicates that you catch `UnknownTransactionStatusException`.
// If you catch `UnknownTransactionStatusException`, it indicates that the status of the
// transaction, whether it has succeeded or not, is unknown. In such a case, you need to check
// if the transaction is committed successfully or not and retry it if it failed. How to
// identify a transaction status is delegated to users
} else {
// For other cases, you can try retrying the transaction

// Rollback the transaction

// The cause of the exception can be `TransactionRetryableException` or the other
// exceptions. For `TransactionRetryableException`, you can basically retry the transaction.
// However, for the other exceptions, the transaction may still fail if the cause of the
// exception is nontransient. For such a case, you need to limit the number of retries and
// give up retrying

Please see also ScalarDB SQL API Guide for more details on exception handling.