• Glossary
  • Support
  • Downloads
  • DataStax Home
Get Live Help
Expand All
Collapse All

DataStax Astra DB Classic Documentation

    • Overview
      • Release notes
      • Astra DB FAQs
      • Astra DB glossary
      • Get support
    • Getting Started
      • Grant a user access
      • Load and retrieve data
        • Use DSBulk to load data
        • Use Data Loader in Astra Portal
      • Connect a driver
      • Build sample apps
      • Use integrations
        • Connect with DataGrip
        • Connect with DBSchema
        • Connect with JanusGraph
        • Connect with Strapi
    • Planning
      • Plan options
      • Database regions
    • Securing
      • Security highlights
      • Security guidelines
      • Default user permissions
      • Change your password
      • Reset your password
      • Authentication and Authorization
      • Astra DB Plugin for HashiCorp Vault
    • Connecting
      • Connecting to a VPC
      • Connecting Change Data Capture (CDC)
      • Connecting CQL console
      • Connect the Spark Cassandra Connector to Astra
      • Drivers for Astra DB
        • Connecting C++ driver
        • Connecting C# driver
        • Connecting Java driver
        • Connecting Node.js driver
        • Connecting Python driver
        • Drivers retry policies
      • Connecting Legacy drivers
      • Get Secure Connect Bundle
    • Migrating
      • FAQs
      • Preliminary steps
        • Feasibility checks
        • Deployment and infrastructure considerations
        • Create target environment for migration
        • Understand rollback options
      • Phase 1: Deploy ZDM Proxy and connect client applications
        • Set up the ZDM Automation with ZDM Utility
        • Deploy the ZDM Proxy and monitoring
          • Configure Transport Layer Security
        • Connect client applications to ZDM Proxy
        • Manage your ZDM Proxy instances
      • Phase 2: Migrate and validate data
      • Phase 3: Enable asynchronous dual reads
      • Phase 4: Change read routing to Target
      • Phase 5: Connect client applications directly to Target
      • Additional resources
        • Glossary
        • Troubleshooting
          • Troubleshooting tips
          • Troubleshooting scenarios
        • Contribution guidelines
        • Release Notes
    • Managing
      • Managing your organization
        • User permissions
        • Pricing and billing
        • Audit Logs
        • Configuring SSO
          • Configure SSO for Microsoft Azure AD
          • Configure SSO for Okta
          • Configure SSO for OneLogin
      • Managing your database
        • Create your database
        • View your databases
        • Database statuses
        • Use DSBulk to load data
        • Use Data Loader in Astra Portal
        • Monitor your databases
        • Manage multiple keyspaces
        • Using multiple regions
        • Terminate your database
        • Resize your classic database
        • Park your classic database
        • Unpark your classic database
      • Managing with DevOps API
        • Managing database lifecycle
        • Managing roles
        • Managing users
        • Managing tokens
        • Managing multiple regions
        • Get private endpoints
        • AWS PrivateLink
        • Azure PrivateLink
        • GCP Private Service
    • Astra CLI
    • Developing with Stargate APIs
      • Develop with REST
      • Develop with Document
      • Develop with GraphQL
        • Develop with GraphQL (CQL-first)
        • Develop with GraphQL (Schema-first)
      • Develop with gRPC
        • gRPC Rust client
        • gRPC Go client
        • gRPC Node.js client
        • gRPC Java client
      • Develop with CQL
      • Tooling Resources
      • Node.js Document API client
      • Node.js REST API client
    • Stargate QuickStarts
      • Document API QuickStart
      • REST API QuickStart
      • GraphQL API CQL-first QuickStart
    • API References
      • DevOps REST API v2
      • Stargate Document API v2
      • Stargate REST API v2
  • DataStax Astra DB Classic Documentation
  • Connecting
  • Connecting Legacy drivers

Connect with legacy drivers

If the driver you are using doesn’t support the DataStax Astra DB secure connect bundle and you are unable to upgrade, you can still connect to Astra DB with 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.

Prerequisites

Working with secure connect bundle

Downloading secure connect bundle

To connect to your Astra DB database using the drivers, download the secure database bundle from the DataStax Astra Portal that contains the connection credentials.

  1. Open a browser, navigate to Astra DB, and log in.

  1. From your Dashboard page, select your database.

  1. On the Overview page, select Connect.

  1. In the Select a Method section, select Drivers and then Legacy from the dropdown menu to select your driver type from the list to load language-specific instructions.

    Java and Node.js are available as legacy and cloud native drivers.

    If you have multiple regions, select the region you want to connect to from the dropdown menu for instructions.

    The bundle URL is the same for all languages.

  1. Click Download Bundle.

    If you have multiple regions, you will have the option to download a bundle for each region from the expanded Download Bundle drop-down menu.

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

  1. From the secure connect bundle, collect the SSL related files:

    • ca.cert

    • cert

    • key

  2. 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.

  1. From the config.json file, grab the hostname.

Java legacy driver versions

Connect to DataStax Astra DB from Java using a previous version of the DataStax Driver. Before proceeding please consider upgrading to the most current driver if possible. 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.

  • include::manage:partial$collect_legacy_driver_info.adoc[]

  • Also 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

  1. 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.

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

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

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

  5. 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 drivers

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

  1. 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.

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

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

  4. 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 versions

Connect to Astra DB from Python using a previous version of the DataStax Driver. Before proceeding please consider upgrading to the most current driver if possible. 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.

  • Collect the required information for Connecting with legacy drivers.

Procedure

  1. 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.

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

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

  4. 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 drivers

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

  1. 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.

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

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

  1. 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

Drivers retry policies Get Secure Connect Bundle

General Inquiries: +1 (650) 389-6000 info@datastax.com

© DataStax | Privacy policy | Terms of use

DataStax, Titan, and TitanDB are registered trademarks of DataStax, Inc. and its subsidiaries in the United States and/or other countries.

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries.

Kubernetes is the registered trademark of the Linux Foundation.

landing_page landingpage