Connect with legacy drivers

If the driver you are using isn’t a Native driver and you cannot upgrade, you can still connect to Astra DB with these additional steps. To connect, collect connection information from the secure connect bundle and set up the required SSL context for your driver to speak with Astra DB.

The following table offers a complete view of our Astra DB drivers, their supported versions, and specifications. For details about supported versions, see Version Compatibility.

Driver Options Drivers and their supported versions Specifications

Driver Options	Drivers and their supported versions	Specifications
Cloud (gRPC)	Go* Java* Node.js* Rust* * all versions	Interacts with Astra via CQL and gRPC APIs. Without driver updates, you can query CQL from any source. This API uses a token and endpoint to connect to Astra DB.
Native	C#, 3.17 or greater C++, 2.14 or greater Java, 3.8 or greater Node.js, 4.4 or greater Python, 3.25 or greater	Actively maintained by DataStax and has built-in support. Specify the secure connect bundle ZIP to connect to Astra DB.
Legacy	Java, 3.7 or earlier PHP Python, 3.23 or earlier Ruby	Legacy drivers were developed for Apache Cassandra™. To connect to Astra DB, specify your Secure Connect Bundle (SCB) details (token, userID, etc). Alternatively, you can use the SSL-related files (ca.cert, cert, and key) and the port from the `cqlshrc` file. Ruby and PHP are not actively maintained and are in maintenance mode.

Cloud (gRPC)

Go*
Java*
Node.js*
Rust*
* all versions

Interacts with Astra via CQL and gRPC APIs.
Without driver updates, you can query CQL from any source. This API uses a token and endpoint to connect to Astra DB.

Native

C#, 3.17 or greater
C++, 2.14 or greater
Java, 3.8 or greater
Node.js, 4.4 or greater
Python, 3.25 or greater

Actively maintained by DataStax and has built-in support.
Specify the secure connect bundle ZIP to connect to Astra DB.

Legacy

Java, 3.7 or earlier
PHP
Python, 3.23 or earlier
Ruby

Legacy drivers were developed for Apache Cassandra™.
To connect to Astra DB, specify your Secure Connect Bundle (SCB) details (token, userID, etc).

Alternatively, you can use the SSL-related files (ca.cert, cert, and key) and the port from the cqlshrc file.

Ruby and PHP are not actively maintained and are in maintenance mode.

Prerequisites

Working with secure connect bundle

Legacy drivers were developed for Apache Cassandra™. To connect to Astra DB, specify your Secure Connect Bundle (SCB) details (token, userID, etc).

Alternatively, you can use the SSL-related files (ca.cert, cert, and key) and the port from the cqlshrc file.

For new projects on Astra DB, use a Cloud or Native driver. Java and Python are available as Legacy and Native drivers.

Legacy drivers should be used only if migrating an existing Cassandra application developed with a Legacy driver to Astra DB.

If you’ve enabled VPC peering, you can also Download External Secure Connect Bundle for use within your VPC peering.

The secure-connect-database_name.zip file downloads, which contains the security certificates and credentials for your database.

VPC peering is only available on Classic databases.

Sharing secure connect bundle

Although teammates can access your Astra DB database, it will not display in their list of available databases under My Databases in Astra Portal.

After you create an Astra DB database, you can grant access to other members of your team by providing them with the database credentials and connection details for your database.

Be careful when sharing connection details. Providing this information to another user grants them access to your Astra DB database and ownership capabilities, such as making modifications to the database.

For security, delete downloaded connection credentials after sending them to your teammate.

Collect Astra DB connection information

From the secure connect bundle, collect the SSL related files:
- ca.cert
- cert
- key
From the cqlshrc file, collect the port.

Use only the port from cqlshrc. Other ports found in the secure connect bundle will not allow you to connect with this method.

From the config.json file, grab the hostname.

Java legacy driver

Connect to DataStax Astra DB from Java using a previous version of the DataStax Driver.

If possible, upgrade to a Java Native driver, which is version 3.8 or greater. For more, see Drivers for Astra.

However, if you cannot upgrade, or are using a Framework that doesn’t support Astra DB secure connect, the following instructions will help you get connected.

Prerequisites

Ensure the Java driver is installed. For more, see DataStax Java Driver.
Collect the required information for Connecting with legacy drivers.
Collect the trustStore.jks and identity.jks from the secure connect bundle.
From the config.json in the secure connect bundle collect the keyStorePassword and trustStorePassword.
Client ID and Client Secret correspond to username and password. They are created when you generate your application token.

Procedure

Copy the certificate files from the Astra DB secure connect bundle to ../secure-connect/. This folder should contain the trustStore.jks and identity.jks files.
Replace the <hostname> with your Astra DB database hostname.
Replace the <port> with your Astra DB database port.
Replace <username> and <password> with the Astra DB database Client ID and Client Secret.
Replace <keyStore pass> and <trustStore pass> with the values from the config.json.

Java 11

import com.datastax.driver.core.RemoteEndpointAwareJdkSSLOptions;
import com.datastax.driver.core.SSLOptions;
import org.springframework.data.cassandra.config.CassandraClusterFactoryBean;

import javax.net.ssl.*;
import java.io.File;
import java.security.KeyStore;
import java.security.SecureRandom;

public class Test {
    private static final String KEYSTORE_PATH = "../secure-connect/identity.jks";
    private static final char[] KEYSTORE_PASSWORD = "<keystore pass>".toCharArray();
    private static final String TRUSTSTORE_PATH = "../secure-connect/trustStore.jks";
    private static final char[] TRUSTSTORE_PASSWORD ="<trustStore pass>".toCharArray();
    private static final String contactPoints = "<hostname>";
    private static final int port = <port>;
    private static final boolean sslEnabled = true;
    private static final String username = "<clientId>";
    private static final String password = "<clientSecret>";

    @Override
    public CassandraClusterFactoryBean cluster(){

        CassandraClusterFactoryBean cluster = new CassandraClusterFactoryBean();

        cluster.setJmxReportingEnabled(false);
        cluster.setContactPoints(contactPoints);
        cluster.setPort(port);
        cluster.setSslEnabled(sslEnabled);
        cluster.setContactPoints(contactPoints);
        cluster.setUsername(username);
        cluster.setPassword(password);
        cluster.setSslOptions(generateSSLConf());

        return cluster;
    }
    public SSLOptions generateSSLConf() {
        try {
            KeyManagerFactory kmf;
            try {
                kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
                kmf.init(KeyStore.getInstance(KEYSTORE_PATH), KEYSTORE_PASSWORD);
            } catch (Exception e) {
                throw new RuntimeException("Unable to init KeyManagerFactory. Please check password and location.", e);
            }

            KeyStore truststore;
            try {
                truststore = KeyStore.getInstance(new File(TRUSTSTORE_PATH),TRUSTSTORE_PASSWORD);
            } catch (Exception e) {
                throw new RuntimeException("Unable to load the truststore. Check path and password.", e);
            }
            TrustManagerFactory tmf;
            try {
                tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
                tmf.init(truststore);
            } catch (Exception e) {
                throw new RuntimeException("Unable to init TrustManagerFactory.", e);
            }

            try {
                SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
                sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), new SecureRandom());
                return RemoteEndpointAwareJdkSSLOptions.builder()
                        .withSSLContext(sslContext)
                        .build();
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        } catch (Throwable th) {
            throw new RuntimeException("Failed to load truststore for casandra", th);
        }
    }
}

Example

import com.datastax.driver.core.RemoteEndpointAwareJdkSSLOptions;
import com.datastax.driver.core.SSLOptions;
import org.springframework.data.cassandra.config.CassandraClusterFactoryBean;

import javax.net.ssl.*;
import java.io.File;
import java.security.KeyStore;
import java.security.SecureRandom;

public class Test {
    private static final String KEYSTORE_PATH = "../secure-connect/identity.jks";
    private static final char[] KEYSTORE_PASSWORD = "7cU6YS5jHbh8a".toCharArray();
    private static final String TRUSTSTORE_PATH = "../secure-connect/trustStore.jks";
    private static final char[] TRUSTSTORE_PASSWORD = "Dwp6KMa2lRd01".toCharArray();
    private static final String contactPoints = "7bb9cd7a-e49d-49a6-aa3d-be4878f974ef-us-east1.db.astra.datastax.com";
    private static final int port = 31575;
    private static final boolean sslEnabled = true;
    private static final String username = "john.smith";
    private static final String password = "jsP@ssw0rd";

    @Override
    public CassandraClusterFactoryBean cluster(){

        CassandraClusterFactoryBean cluster = new CassandraClusterFactoryBean();

        cluster.setJmxReportingEnabled(false);
        cluster.setContactPoints(contactPoints);
        cluster.setPort(port);
        cluster.setSslEnabled(sslEnabled);
        cluster.setContactPoints(contactPoints);
        cluster.setUsername(username);
        cluster.setPassword(password);
        cluster.setSslOptions(generateSSLConf());

        return cluster;
    }
    public SSLOptions generateSSLConf() {
        try {
            KeyManagerFactory kmf;
            try {
                kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
                kmf.init(KeyStore.getInstance(KEYSTORE_PATH), KEYSTORE_PASSWORD);
            } catch (Exception e) {
                throw new RuntimeException("Unable to init KeyManagerFactory. Please check password and location.", e);
            }

            KeyStore truststore;
            try {
                truststore = KeyStore.getInstance(new File(TRUSTSTORE_PATH),TRUSTSTORE_PASSWORD);
            } catch (Exception e) {
                throw new RuntimeException("Unable to load the truststore. Check path and password.", e);
            }
            TrustManagerFactory tmf;
            try {
                tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
                tmf.init(truststore);
            } catch (Exception e) {
                throw new RuntimeException("Unable to init TrustManagerFactory.", e);
            }

            try {
                SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
                sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), new SecureRandom());
                return RemoteEndpointAwareJdkSSLOptions.builder()
                        .withSSLContext(sslContext)
                        .build();
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        } catch (Throwable th) {
            throw new RuntimeException("Failed to load truststore for casandra", th);
        }
    }
}

In the example above, the following variables are used:

hostname is 7bb9cd7a-e49d-49a6-aa3d-be4878f974ef-us-east1.db.astra.datastax.com
port is 31575
username is john.smith
password is jsP@ssw0rd
trustStore pass is Dwp6KMa2lRd01
keystore pass is 7cU6YS5jHbh8a

PHP legacy driver

This example can be used to attach to Astra DB from PHP using the DataStax Driver. Before proceeding you might also consider using the REST, GraphQL or Document APIs to connect to Astra DB without the need for a custom driver.

Prerequisites

Ensure the Python driver is installed. For more, see DataStax PHP Driver for Apache Cassandra.
Collect the required information for Connecting with legacy drivers.
Get your Client ID and Client Secret by creating your application token for your username and password.

Procedure

Copy the certificate files from the Astra DB secure connect bundle to /etc/ssl/certs/astra-secure-connect. This folder should contain the ca.cert, cert, and key files.
Replace the <hostname> with your Astra DB database hostname.
Replace the <port> with your Astra DB database port.
Replace <username> and <password> with the Astra DB database Client ID and Client Secret.

<?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("dbadmin", "my_awesome_password")
               \->withContactPoints('602c8f3c-ea96-41b0-a7c1-6c6c5bdd1f34-us-east1.db.astra.datastax.com')
               \->withPort(31575)
               \->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']);
}"

Example

<?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("john.smith", "jsP@ssw0rd")
               \->withContactPoints('602c8f3c-ea96-41b0-a7c1-6c6c5bdd1f34-us-east1.db.astra.datastax.com')
               \->withPort(31575)
               \->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']);
    }"

In the example above, the following variables are used:

<hostname> is 602c8f3c-ea96-41b0-a7c1-6c6c5bdd1f34-us-east1.db.astra.datastax.com
<port> is 31575
<username> is john.smith
<password> is jsP@ssw0rd

Python legacy driver

Connect to Astra DB from Python using a previous version of the DataStax Driver.

If possible, upgrade to a Python Native driver, which is version 3.24 or greater. For more, see Drivers for Astra.

However, if you cannot upgrade, or are using a Framework that doesn’t support Astra DB secure connect, the following instructions will help you get connected.

Prerequisites

Ensure the Python driver is installed. For more, see DataStax Python Driver Installation.
Collect the required information for Connecting with legacy drivers.

Procedure

Copy the certificate files from the Astra DB secure connect bundle to ../secure-connect/.

This folder should contain the ca.cert, cert, and key files.
Replace the <hostname> with your Astra DB database hostname.
Replace the <port> with your Astra DB database port.
Replace <username> and <password> with the Astra DB database Client ID and Client Secret.

from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
from ssl import SSLContext, PROTOCOL_TLSv1, CERT_REQUIRED

ssl_context = SSLContext(PROTOCOL_TLSv1)
ssl_context.load_verify_locations('../secure-connect/ca.crt')
ssl_context.verify_mode = CERT_REQUIRED
ssl_context.load_cert_chain(
    certfile='../secure-connect/cert',
    keyfile='../secure-connect/key')


auth_provider = PlainTextAuthProvider('<username>', '<password>')
cluster = Cluster(['<hostname>'], port=<port>, ssl_context=ssl_context, auth_provider=auth_provider)
session = cluster.connect()

row = session.execute("select release_version from system.local").one()
if row:
  print(row[0])
else:
  print("An error occurred.")


print(cluster.metadata.keyspaces)

Example

from cassandra.cluster import Cluster
from cassandra.auth import PlainTextAuthProvider
from ssl import SSLContext, PROTOCOL_TLSv1, CERT_REQUIRED

ssl_context = SSLContext(PROTOCOL_TLSv1)
ssl_context.load_verify_locations('../secure-connect/ca.crt')
ssl_context.verify_mode = CERT_REQUIRED
ssl_context.load_cert_chain(
    certfile='../secure-connect/cert',
    keyfile='../secure-connect/key')


auth_provider = PlainTextAuthProvider('john.smith', 'jsP@ssw0rd')
cluster = Cluster(['7bb9cd7a-e49d-49a6-aa3d-be4878f974ef-us-east1.db.astra.datastax.com'], port=31575, ssl_context=ssl_context, auth_provider=auth_provider)
session = cluster.connect()

row = session.execute("select release_version from system.local").one()
if row:
  print(row[0])
else:
  print("An error occurred.")


print(cluster.metadata.keyspaces)

In the example above, the following variables are used:

hostname is 7bb9cd7a-e49d-49a6-aa3d-be4878f974ef-us-east1.db.astra.datastax.com
port is 31575
username is john.smith
password is jsP@ssw0rd

Flask CQLAlchemy framework

Following the procedure above this code allows CQLAlchemy to utilize Astra DB.

import uuid
from flask import Flask
from flask_cqlalchemy import CQLAlchemy
from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED
from cassandra.auth import PlainTextAuthProvider


auth_provider = PlainTextAuthProvider(username='<username>', password='<password>')
ssl_context = SSLContext(PROTOCOL_TLSv1)
ssl_context.load_verify_locations("../secure-connect/ca.crt")
ssl_context.verify_mode = CERT_REQUIRED
ssl_context.load_cert_chain(
  certfile="../secure-connect/cert",
  keyfile="secure-connect/key")

app = Flask(__name__)
app.config['CASSANDRA_HOSTS'] = ['<hostname>']
app.config['CASSANDRA_SETUP_KWARGS'] = dict(ssl_context=ssl_context, port="<port>", auth_provider=auth_provider)
app.config['CASSANDRA_KEYSPACE'] = "cqlengine"
db = CQLAlchemy(app)


class User(db.Model):
    uid = db.columns.UUID(primary_key=True, default=uuid.uuid4)
    username = db.columns.Text(required=False)

Example

import uuid
from flask import Flask
from flask_cqlalchemy import CQLAlchemy
from ssl import SSLContext, PROTOCOL_TLS, CERT_REQUIRED
from cassandra.auth import PlainTextAuthProvider


auth_provider = PlainTextAuthProvider(username='jane.smith', password='jsP@ssw0rd')
ssl_context = SSLContext(PROTOCOL_TLSv1)
ssl_context.load_verify_locations("../secure-connect/ca.crt")
ssl_context.verify_mode = CERT_REQUIRED
ssl_context.load_cert_chain(
  certfile="../secure-connect/cert",
  keyfile="secure-connect/key")

app = Flask(__name__)
app.config['CASSANDRA_HOSTS'] = ['7bb9cd7a-e49d-49a6-aa3d-be4878f974ef-us-east1.db.astra.datastax.com']
app.config['CASSANDRA_SETUP_KWARGS'] = dict(ssl_context=ssl_context, port="31575", auth_provider=auth_provider)
app.config['CASSANDRA_KEYSPACE'] = "cqlengine"
db = CQLAlchemy(app)


class User(db.Model):
    uid = db.columns.UUID(primary_key=True, default=uuid.uuid4)
    username = db.columns.Text(required=False)

Ruby legacy driver

This example can be used to attach to DataStax Astra DB from Ruby using the DataStax Driver. Before proceeding you might also consider using the REST, GraphQL or Document APIs to connect to Astra DB without the need for a custom driver.

Prerequisites

Ensure the Ruby driver is installed. For more, see DataStax Ruby Driver for Apache Cassandra.
Collect the required information for Connecting with legacy drivers.

Procedure

Copy the certificate files from the Astra DB secure connect bundle to /etc/ssl/certs/astra-secure-connect. This folder should contain the ca.cert, cert, and key files.

Replace the <hostname> with your Astra DB database hostname.

Replace the <port> with your Astra DB database port.

Replace <username> and <password> with the Astra DB database Client ID and Client Secret.

require 'cassandra'

cluster = Cassandra.cluster(
            username: '<username>',
            password: '<password>',
            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

Example

require 'cassandra'

cluster = Cassandra.cluster(
            username: 'john.smith',
            password: 'jsP@ssw0rd',
            hosts: ['602c8f3c-ea96-41b0-a7c1-6c6c5bdd1f34-us-east1.db.astra.datastax.com'],
            port: 31575,
            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

In the example above, the following variables are used:

hostname is 602c8f3c-ea96-41b0-a7c1-6c6c5bdd1f34-us-east1.db.astra.datastax.com
port is 31575
username is john.smith
password is jsP@ssw0rd