JDBC wrapper of the Java Driver for Apache Cassandra®

This is a JDBC wrapper of the Java Driver for Apache Cassandra®, which offers a simple JDBC compliant API to work with CQL3.

This JDBC wrapper is based on a fork of the project adejanovski/cassandra-jdbc-wrapper, which is no longer maintained. We would especially like to thank its author.

Features

The JDBC wrapper offers access to most of the core module features:

• Asynchronous: the driver uses the new CQL binary protocol asynchronous capabilities. Only a relatively low number of connections per nodes needs to be maintained open to achieve good performance.
• Nodes discovery: the driver automatically discovers and uses all nodes of the C* cluster, including newly bootstrapped ones.
• Transparent fail-over: if C* nodes fail or become unreachable, the driver automatically and transparently tries other nodes and schedules reconnection to the dead nodes in the background.
• Convenient schema access: the driver exposes a C* schema in a usable way.

Getting Started

Prerequisites

The wrapper uses Java Driver for Apache Cassandra® 4.x. This driver is designed for Apache Cassandra® 2.1+ and DataStax Enterprise (5.0+). So, it will throw "unsupported feature" exceptions if used against an older version of Cassandra cluster. For more information, please check the compatibility table.

If you meet issues connecting to the cluster (seeing NoHostAvailableConnection exceptions) please check if your configuration is correct, and you specified a valid local datacenter if you use the default load-balancing policy.

This project requires Java 17 (minimum).

Installing

This section is mainly aimed at the code contributors.

Clone the repository:

git clone https://github.com/ing-bank/cassandra-jdbc-wrapper.git

To compile and run tests, execute the following Maven command:

./mvnw clean package

Note that running tests requires to install Docker first.

To build a bundled version of the JDBC wrapper, run the following command:

./mvnw clean package -Pbundle

Some considerations about running tests

If for some reason the tests using DataStax Enterprise server (*DseContainerTest) fail in your local environment, you might disable them using the Maven profile disableDseTests:

./mvnw clean package -PdisableDseTests

The test suite also includes integration tests with:

• AstraDB (DbaasAstraIntegrationTest). These tests require an AstraDB token configured in the environment variable ASTRA_DB_APPLICATION_TOKEN, otherwise they are skipped.
• Amazon Keyspaces (AmazonKeyspacesIntegrationTest). These tests require an instance of Amazon Keyspaces and to define several environment variables in a .env file (see test class for further information), otherwise they are skipped.

Integration in Maven projects

You can install the JDBC driver in your application using the following Maven dependency:

<dependency>
    <groupId>com.ing.data</groupId>
    <artifactId>cassandra-jdbc-wrapper</artifactId>
    <version>${cassandra-jdbc-wrapper.version}</version>
</dependency>

Integration in Gradle projects

You can install the JDBC driver in your application using the following Gradle dependency:

implementation 'com.ing.data:cassandra-jdbc-wrapper:${cassandra-jdbc-wrapper.version}'

Other integrations

To use this JDBC wrapper for Apache Cassandra® in database administration tools such as DBeaver Community Edition or JetBrains DataGrip, you can have a look to the following links:

• connecting DBeaver to Cassandra cluster
• connecting DataGrip to Cassandra cluster; note this example uses Astra JDBC driver (based on this project), so refer to the "Usage" section below to adapt driver class and JDBC URL values.

This JDBC wrapper for Apache Cassandra® is also used to run Liquibase for Cassandra databases (from Liquibase 4.25.0.1). To execute Liquibase scripts on your Cassandra database, specify the following properties in your Liquibase properties file:

driver: com.ing.data.cassandra.jdbc.CassandraDriver
url: jdbc:cassandra://<host>:<port>/<keyspaceName>?compliancemode=Liquibase

See the documentation about JDBC connection string for further details about the allowed parameters in the JDBC URL. For further details about Liquibase usage, please check the official documentation.

Usage

Connect to a Cassandra cluster using the following arguments:

• JDBC driver class: com.ing.data.cassandra.jdbc.CassandraDriver
• JDBC URL: jdbc:cassandra://host1--host2--host3:9042/keyspace?localdatacenter=DC1

You can give the driver any number of hosts you want separated by --. You can optionally specify a port for each host. If only one port is specified after all the listed hosts, it applies to all hosts. If no port is specified at all, the default Cassandra port (9042) is used. They will be used as contact points for the driver to discover the entire cluster. Give enough hosts taking into account that some nodes may be unavailable upon establishing the JDBC connection.

Find below a basic Java example to establish a connection to a Cassandra database using this driver:

public class HelloCassandra {
    public static void main(final String[] args) {
        // Used driver: com.ing.data.cassandra.cassandra.jdbc.CassandraDriver
        final String url = "jdbc:cassandra://host1--host2--host3:9042/keyspace?localdatacenter=DC1";
        final Connection connection = DriverManager.getConnection(url);
    }
}

Alternatively, you can also obtain a connection using a CassandraDataSource instance:

public class HelloCassandra {
    public static void main(final String[] args) {
        final List<ContactPoint> contactPoints = Arrays.asList(
                ContactPoint.of("host1", 9042),
                ContactPoint.of("host2", 9042),
                ContactPoint.of("host3", 9042));
        final CassandraDataSource dataSource = new CassandraDataSource(contactPoints, "keyspace");
        dataSource.setLocalDataCenter("DC1");
        // Use setters on dataSource instance to specify additional properties of the connection.
        final Connection connection = dataSource.getConnection();
    }
}

For further details about configuration and usage of the driver, please refer to the full documentation.

Contributing

Please read our contributing guide and feel free to improve this library!

Versioning

We use SemVer for versioning.

Authors and contributors

• Maxime Wiewiora - @maximevw
• Sualeh Fatehi - @sualeh
• Stefano Fornari - @stefanofornari
• Marius Jokubauskas - @mjok
• Liudmila Kornilova - @kornilova203
• Cedrick Lunven - @clun
• Madhavan Sridharan - @msmygit
• Lik Dan - @LikDan
• Muskan Maheshwari - @Muskan02
• Filipe Lautert - @filipelautert

And special thanks to the developer of the original project on which is based this one:

• Alexander Dejanovski - @adejanovski

Acknowledgments

• README Template gist for the redaction of what you're reading.