Get started with Cassandra drivers

You can use Cassandra drivers to interact with your Astra Managed Clusters databases through the Cassandra Query Language (CQL).

To use a driver, you need to add the driver dependency to your project, initialize a driver session, and then connect the driver to your database. Once connected, your scripts can execute CQL statements against your database through the driver instance.

This documentation provides general guidance on application development with Astra-compatible drivers, including version compatibility, best practices, connection methods, statement execution, error handling, and performance tuning. Use this documentation in conjunction with the documentation for your chosen driver and general Astra documentation.

Specific features and capabilities vary by driver language and version. Driver features designed for self-managed Cassandra clusters might not be supported or relevant to Astra database, which are a managed service. DataStax recommends, whenever possible, that you use the latest version of your chosen driver to access the most recent features and improvements.

Cassandra drivers and DataStax drivers

The terms drivers for Apache Cassandra® and Cassandra drivers refer to all drivers that can be used with Cassandra-based databases.

Due to the open source nature of the Apache Software Foundation (ASF), Cassandra drivers are developed by different contributors, depending on source code ownership or primary responsibility. Drivers can be donated to the ASF for ongoing community maintenance. Several drivers developed by DataStax have been donated to the ASF. When a donation happens, the documentation is split between the original maintainer (pre-donation versions) and the ASF (post-donation versions).

The Astra documentation uses any of the following terms to refer to all Astra-compatible Cassandra drivers:

Cassandra drivers
DataStax-compatible drivers
Cassandra-compatible drivers
Astra-compatible drivers

When referring to a specific driver version, this documentation might use the maintainer’s prefix for clarity, such as DataStax Java driver or Apache Cassandra Java driver.

Supported drivers

Astra databases are compatible with the following Cassandra drivers:

Supported drivers
Language	Driver	Documentation
C++	cpp-driver	Get started with the C++ driver
C#	csharp-driver	Get started with the C# driver
Go	gocql-astra (with cassandra-gocql-driver)	Get started with the Go driver
Java	cassandra-java-driver	Get started with the Java driver
Node.js	cassandra-driver	Get started with the Node.js driver
Python	cassandra-driver	Get started with the Python driver
Scala	cassandra-spark-connector	Get started with the Apache Cassandra Spark Connector

JDBC and ODBC drivers

A license is required to use the DataStax ODBC and JDBC drivers, which you can download from IBM Fix Central. For more information, visit IBM Support.

Other JDBC and ODBC drivers exist, such as cassandra-jdbc-wrapper, but compatibility isn’t verified.

Unverified drivers

DataStax strongly recommends using supported drivers whenever possible. Although other Apache Cassandra drivers might support the required CQL functionality, be aware of the following:

Unverified drivers aren’t tested by DataStax for compatibility with Astra databases.
Unverified drivers aren’t inherently covered by IBM Elite Support plans or other Astra support agreements. Connections using third-party open-source drivers over private links, with or without custom domains, aren’t supported by DataStax in any capacity.
Unverified drivers might not support important Astra features like certain authentication methods. If a maintainer claims support for a feature, there is no guarantee as to the robustness, security, or efficacy of the implementation.
Unverified drivers might not include features that harden the driver against coordinator IP address changes, which can cause frequent connection issues or failed connections.

`cql-proxy` for unverified drivers

If you want to use a Cassandra driver that isn’t compatible with Astra databases, including third-party JDBC drivers for integrations with Astra, consider using cql-proxy. This utility provides connectivity for incompatible drivers by securely forwarding your application’s CQL traffic to an appropriate database service.

cql-proxy isn’t required for supported driver versions, which are already compatible with Astra databases.

Unsupported drivers

Driver versions that are in end-of-life (EOL), maintenance mode, or older than one year receive no updates, including security patches, unless otherwise announced in the driver’s release notes. DataStax recommends that you upgrade to a supported driver as soon as possible.

Drivers become unsupported if they are declared deprecated or unmaintained by their maintainers, or if they no longer meet the requirements for compatibility with Astra databases. This can include individual driver versions, major version series, or all versions of a given driver.

DataStax officially supports the latest 12 months of releases for Astra-compatible drivers, and DataStax recommends using the latest driver version whenever possible. Compatibility isn’t guaranteed for earlier versions.

The following drivers are in EOL or maintenance mode:

GoCQL 1.x series
GoCQL Astra 1.x series
Java driver 3.x series
Java driver 2.x series
DataStax Ruby driver
DataStax PHP driver
All DSE-only drivers

Java driver 3.x series (Maintenance)

The 3.x series of the Java driver entered maintenance mode in 2023.

DataStax recommends that you upgrade to the 4.x series. When upgrading, be aware that the artifacts for the 3.x series use the naming convention cassandra-driver-*, which is distinct from the 4.x series naming convention java-driver-*.

Java driver 3.x series compatibility
Driver version	Astra compatibility	Comments
3.8 to 3.12	Partially compatible	Starting with version 3.12, this driver is maintained by the Apache Software Foundation (ASF). Doesn’t support the vector type.
3.0 to 3.7	Not compatible

Java driver 2.x series (EOL)

The 2.x series of the Java driver has reached EOL. It was superseded by the 3.x series in 2016 and the 4.x series in 2019.

The 2.x series isn’t compatible with Astra. DataStax recommends that you upgrade to the 4.x series.

DataStax Ruby and PHP drivers (Maintenance)

The DataStax Ruby driver and DataStax PHP driver (php-driver) are in maintenance mode and they aren’t actively maintained.

These drivers don’t support the vector type.

These drivers aren’t compatible with Astra databases.

Use these drivers only to support legacy Ruby and PHP applications until you can upgrade to a supported driver. To do this, you must manually provide the connection and SSL information from your database’s Secure Connect Bundle (SCB):

Download your database’s SCB, extract the files, and then get the following files and information from the bundle:
1. Get the SSL-related files: ca.cert, cert, and key.
2. Open the cqlshrc file, and then get the port.
  
  Use only the port from cqlshrc. Other ports in the SCB cannot support the legacy driver connection.
3. Open the config.json file, and then get the hostname.
Create an application token, and then get the token’s Client ID and Client Secret.
In your Ruby or PHP project where you have installed the Ruby or PHP driver, copy the certificate files from the SCB to /etc/ssl/certs/astra-secure-connect. This folder should contain the ca.cert, cert, and key files.

In your application code, configure the driver connection to use your application token and SCB information:

Legacy Ruby driver connection for Astra

require 'cassandra'

cluster = Cassandra.cluster(
            username: 'CLIENT_ID',
            password: 'CLIENT_SECRET',
            hosts: ['HOSTNAME'],
            port: PORT,
            server_cert: '/etc/ssl/certs/astra-secure-connect/ca.cert',
            client_cert: '/etc/ssl/certs/astra-secure-connect/cert',
            private_key: '/etc/ssl/certs/astra-secure-connect/key'
)

keyspace = 'system_schema'
session  = cluster.connect(keyspace) # create session, optionally scoped to a keyspace, to execute queries

future = session.execute_async('SELECT keyspace_name, table_name FROM tables') # fully asynchronous api
future.on_success do |rows|
  rows.each do |row|
    puts "The keyspace #{row['keyspace_name']} has a table #{row['table_name']}"
  end
end
future.join

Legacy PHP driver connection for Astra

<?php

$ssl     = Cassandra::ssl()
               \->withTrustedCerts('/etc/ssl/certs/astra-secure-connect/ca.cert')
               \->withClientCert('/etc/ssl/certs/astra-secure-connect/cert')
               \->withPrivateKey('/etc/ssl/certs/astra-secure-connect/key')
               \->build();


$cluster = Cassandra::cluster()
               \->withSSL($ssl)
               \->withCredentials("CLIENT_ID", "CLIENT_SECRET")
               \->withContactPoints('HOSTNAME')
               \->withPort(PORT)
               \->build();

$session = $cluster\->connect();

$result = $session\->execute('SELECT keyspace_name, table_name FROM system_schema.tables');

foreach ($result as $row) {
    printf("The keyspace "%s" has a table "%s".
    ", $row['keyspace_name'], $row['table_name']);
}"

Replace the following:

HOSTNAME: Your database’s hostname, such as DATABASE_ID-REGION.db.astra.datastax.com.
PORT: Your database’s port.
CLIENT_ID and CLIENT_SECRET: The details from your application token.