Connect Cassandra drivers to your databases
The DataStax-compatible drivers can connect to Astra DB, DataStax Enterprise (DSE), Hyper-Converged Database (HCD), and open-source Apache Cassandra® clusters.
Select a compatible driver
DataStax considers the following drivers to be compatible with Cassandra, DSE, HCD, and Astra DB. These drivers are developed and maintained by either DataStax or the Apache Software Foundation. The following table provides links to source code, version compatibility, download links, and documentation for each DataStax-compatible driver.
| Language | Source code | Compatibility | Install | Reference |
|---|---|---|---|---|
C++ |
||||
C# |
||||
Go |
||||
Java |
Java 4.18 and later (with DSE Graph extension) documentation Java 4.17 and earlier (with DSE Graph extension) documentation |
|||
Node.js |
||||
Python |
||||
For more information about driver compatibility and other driver downloads, see Cassandra drivers supported by DataStax.
Configure authentication
The DataStax-compatible drivers ship with built-in authentication providers that provide the necessary utilities to connect to secure Cassandra-based clusters.
You must prepare your preferred authentication method in your clusters before attempting to use that authentication method through a driver. The required credentials for the driver connection depend on your cluster and authentication method.
-
Cassandra
-
DSE
-
HCD
-
Astra DB
Before you connect your driver, you must configure authentication in your open-source Cassandra clusters, as explained in the Apache Cassandra security documentation.
For information about specifying authentication credentials and methods in your driver configuration, see your driver’s documentation.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
Use PlainTextAuthProvider.
For more information, see C# driver authentication and authorization.
See the documentation for your version of the Java driver:
Use PlainTextAuthProvider.
For more information, see Node.js driver authentication.
DSE clusters have no authentication service enabled by default. This simplifies initial setup, but it isn’t intended for production deployments.
Before you connect your driver, you must enable the desired security schemes within your clusters and create users and roles in the database.
DSE unified authentication gives operators and developers a single, flexible security model. One DSE server can accept multiple forms of authentication, and clients with different levels of access can use varying authentication schemes to connect to the same server. Supported authentication methods include internal usernames and password, LDAP/Active Directory usernames and passwords, and Kerberos authentication, as well as authorization through proxy roles.
About internal authentication with drivers
The drivers use a plain text authentication provider to perform internal username and password authentication.
For DSE, the driver sends a plain text username and password to the server that authenticates to the underlying Authentication scheme.
Always use this mechanism in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.
About LDAP/Active Directory authentication with drivers
The drivers use a plain text authentication provider to perform LDAP/Active Directory username and password authentication.
For DSE, the driver sends a plain text username and password to the server that authenticates to the underlying LDAP scheme.
Always use this mechanism in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.
About Kerberos authentication with drivers
Most DataStax-compatible drivers extend authentication providers to support Kerberos authentication for DSE. See your driver’s documentation for information about support for custom authenticators or Kerberos.
- Kerberos configuration file
-
Driver authentication against a Kerberos-enabled DSE cluster requires a
krb5.conffile containing the Kerberos configuration settings. This file can be in the node’s/etcdirectory. If it isn’t, contact your Kerberos system administrator to locate the file.To reference a
krb5.conffile in a non-default location, set theKRB5_CONFIGenvironment variable to the location of yourkrb5.conf. Kerberos command line tools such askinit,klist, andkdestroyrespect this variable.All drivers except the Java and C# drivers respect this environment variable.
For the Java driver, you must set the
java.security.krb5.confsystem property to the path to thekrb5.conffile at startup.The C# driver uses the Microsoft security framework SSPI, which supports Kerberos but doesn’t use
krb5.conf. - Kerberos ticket cache
-
To use the Kerberos ticket cache, use the
kinitcommand to authenticate with the Kerberos server and obtain a ticket. Then, verify the ticket cache contains a ticket for the successful authentication with theklistcommand.Once you verify there is a ticket in the ticket cache, an application that has been configured to use the Kerberos authentication provider is ready to run.
If multiple principals have valid tickets in the ticket cache, and no principal was specified in the application, then the driver arbitrarily chooses one and uses that ticket.
This doesn’t apply to the C# driver, which uses the Microsoft security framework SSPI for Kerberos support. When using the C# driver, a Kerberos ticket is obtained during system login and the driver uses that ticket to authenticate.
- Kerberos keytabs
-
A keytab can be used to authenticate with Kerberos without requiring any additional credentials or a password. Keytab files must have their permissions set properly to restrict access. The permissions must be set to allow the application user to access the keytab.
This doesn’t apply to the C# driver, which uses the Microsoft security framework SSPI for Kerberos support.
Clients with different levels of access can use varying authentication schemes to connect to the same server.
Unified authentication provides the ability to assign users to roles and to tie access to database resources based on that role. DSE also supports proxy roles. Proxy login allows users and applications to authenticate using a fixed set of authentication credentials that allow authorization of resources based on another user role. Similarly, proxy execute allows users to authenticate using a fixed set of authentication credentials but execute requests based on another user role.
All of these features are enabled directly in most DataStax-compatible drivers, with built-in classes to enable the desired security configuration. For information about how to use these authentication options with your driver, see your driver’s documentation.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
For plain-text and custom authentication implementations, see C/C++ driver security.
For Kerberos, proxy, and DSE-specific plain-text options, see C/C++ driver DSE authentication features.
By default, the GoCQL driver only supports username and password authentication. For more information, see GoCQL driver authentication.
See the documentation for your version of the Java driver:
The DataStax PHP driver is in maintenance mode (not actively developed), and the DSE-only PHP driver is EOL. DataStax recommends using an actively supported driver if possible.
If you must use a PHP driver to support a legacy application or database, see DataStax PHP driver for Apache Cassandra®.
The DataStax Ruby driver is in maintenance mode (not actively developed), and the DSE-only Ruby driver is EOL. DataStax recommends using an actively supported driver if possible.
If you must use a Ruby driver to support a legacy application or database, see DataStax Ruby driver for Apache Cassandra®.
HCD clusters have no authentication service enabled by default. This simplifies initial setup, but it isn’t intended for production deployments.
Before you connect your driver, you must enable the desired security schemes within your clusters and create users and roles in the database.
HCD unified authentication gives operators and developers a single, flexible security model. One HCD server can accept multiple forms of authentication, and clients with different levels of access can use varying authentication schemes to connect to the same server. Supported authentication methods include internal usernames and password, LDAP/Active Directory usernames and passwords, and Kerberos authentication, as well as authorization through proxy roles.
About internal authentication with drivers
The drivers use a plain text authentication provider to perform internal username and password authentication.
For HCD, the driver sends a plain text username and password to the server that authenticates to the underlying Authentication scheme.
Always use this mechanism in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.
About LDAP/Active Directory authentication with drivers
The drivers use a plain text authentication provider to perform LDAP/Active Directory username and password authentication.
For HCD, the driver sends a plain text username and password to the server that authenticates to the underlying LDAP scheme.
Always use this mechanism in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.
About Kerberos authentication with drivers
Most DataStax-compatible drivers extend authentication providers to support Kerberos authentication for HCD. See your driver’s documentation for information about support for custom authenticators or Kerberos.
- Kerberos configuration file
-
Driver authentication against a Kerberos-enabled HCD cluster requires a
krb5.conffile containing the Kerberos configuration settings. This file can be in the node’s/etcdirectory. If it isn’t, contact your Kerberos system administrator to locate the file.To reference a
krb5.conffile in a non-default location, set theKRB5_CONFIGenvironment variable to the location of yourkrb5.conf. Kerberos command line tools such askinit,klist, andkdestroyrespect this variable.All drivers except the Java and C# drivers respect this environment variable.
For the Java driver, you must set the
java.security.krb5.confsystem property to the path to thekrb5.conffile at startup.The C# driver uses the Microsoft security framework SSPI, which supports Kerberos but doesn’t use
krb5.conf. - Kerberos ticket cache
-
To use the Kerberos ticket cache, use the
kinitcommand to authenticate with the Kerberos server and obtain a ticket. Then, verify the ticket cache contains a ticket for the successful authentication with theklistcommand.Once you verify there is a ticket in the ticket cache, an application that has been configured to use the Kerberos authentication provider is ready to run.
If multiple principals have valid tickets in the ticket cache, and no principal was specified in the application, then the driver arbitrarily chooses one and uses that ticket.
This doesn’t apply to the C# driver, which uses the Microsoft security framework SSPI for Kerberos support. When using the C# driver, a Kerberos ticket is obtained during system login and the driver uses that ticket to authenticate.
- Kerberos keytabs
-
A keytab can be used to authenticate with Kerberos without requiring any additional credentials or a password. Keytab files must have their permissions set properly to restrict access. The permissions must be set to allow the application user to access the keytab.
This doesn’t apply to the C# driver, which uses the Microsoft security framework SSPI for Kerberos support.
Unified authentication provides the ability to assign users to roles and to tie access to database resources based on that role. HCD also supports proxy roles, such as application roles. Proxy login allows users and applications to authenticate using a fixed set of authentication credentials that allow authorization of resources based on another user role. Similarly, proxy execute allows users to authenticate using a fixed set of authentication credentials but execute requests based on another user role.
All of these features are enabled directly in most DataStax-compatible drivers, with built-in classes to enable the desired security configuration. For information about how to use these authentication options with your driver, see your driver’s documentation.
|
HCD isn’t mentioned explicitly in most driver documentation because it was released in 2024. However, you can use the information about DSE authentication in your driver’s documentation for your driver’s connection to HCD. |
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
For plain-text and custom authentication implementations, see C/C++ driver security.
For Kerberos, proxy, and HCD-specific plain-text options, see C/C++ driver DSE authentication features.
By default, the GoCQL driver only supports username and password authentication. For more information, see GoCQL driver authentication.
See the documentation for your version of the Java driver:
The DataStax PHP driver isn’t compatible with HCD.
The DataStax Ruby driver isn’t compatible with HCD.
Driver authentication to an Astra DB database is handled through an application token and the database’s Secure Connect Bundle (SCB):
-
Application token: This determines the authorized actions that the driver can perform on the database.
The application token is used for the database username and password in the driver connection string. DataStax recommends that you set the username to the literal string
tokenand the password to the actual application token value (AstraCS:…). -
Secure Connect Bundle (SCB): This is a zip file that contains the security credentials and certificates required to establish a secure mutual TLS (mTLS) connection to your database. For multi-region databases, you need the region-specific SCB for each region that your application will connect to.
All DataStax-compatible drivers have configuration file attributes, builder methods, or constructor parameters to use the SCB. In your driver connection string, provide the path to the SCB zip file. Don’t extract the SCB; provide it to the driver as an archive.
With SCB authentication, you don’t provide contact points or local datacenters. The driver automatically gets this information from the SCB. After establishing a connection the resulting session is optimally configured for interacting with your Astra DB database.
DataStax recommends that you use a driver version that supports SCB authentication.
However, if you must support a legacy application with an earlier driver, you can use cql-proxy, extract the SCB, and then manually provide the required certificates to the driver.
Additionally, you must use the token’s clientId and secret for the username and password, respectively.
After you have gathered these credentials, see Connect your driver.
Use SSL
Cassandra drivers support SSL-encrypted connections between the driver and server. SSL isn’t required, but it is recommended for production deployments, especially those with clients communicating over the public internet.
About SSL workflows
A typical SSL workflow consists of the following stages:
-
The client opens a TCP connection to the server on the configured SSL port.
-
An SSL handshake is initialized by the server, sending its public key (or certificate) to the client.
-
The client uses that public key certificate to generate an encrypted session key and sends it back to the server.
-
The server decrypts the message using its private key and retrieves the session key.
-
All communication from that point on is encrypted using that session key.
Identity verification levels
|
As a best practice for secure driver communication, never use SSL without identity verification. Always use either client-to-server or server-to-client identity verification. |
There are three levels of SSL identity verification:
No identity verification (not recommended)
While most drivers support creating SSL connections to the server without identity verification, DataStax doesn’t recommend this for production deployments.
When a secure browser contacts a web server, the browser verifies the identity of the server before sending it requests in case an attacker is masquerading as the web server. A secure communication to a bad actor defeats the purpose of configuring secure communication between the browser and web server in the first place.
Client verifies server
To verify the identity of a server, the driver must be configured with a list of trusted certificate authorities (CAs). When the driver receives the server’s SSL certificate during the SSL handshake, it checks that the certificate was signed by one of the registered CAs. If the certificate wasn’t signed by a registered CA, the client checks that the signer was signed by one of the registered CAs. It continues through the signers until it finds one that is in the client’s list of trusted CAs.
If the client doesn’t find a registered CA, then identity verification fails.
Drivers use this option by default when connecting to Astra DB with SCB authentication.
Server verifies client
To configure a server to verify the identity of a client, edit cassandra.yaml, find client_encryption_options, and then set require_client_auth to true.
This scenario requires that clients have their own certificates to send to the server upon request during the SSL handshake.
For more information, see the following documentation:
Configure SSL
To use SSL-encrypted connections, you must configure SSL in both your cluster and driver.
-
Cassandra
-
DSE
-
HCD
-
Astra DB
By default Cassandra clusters are configured to communicate with clients using an unencrypted binary protocol. This is convenient for getting started but it isn’t suitable for production environments.
To enable SSL, you need access to your cluster’s cassandra.yaml file.
The location of the cassandra.yaml file depends on your database platform and the installation method.
For information about editing cassandra.yaml and configuring SSL, see the Apache Cassandra security documentation.
Then, configure your driver to use the SSL certificates and the SSL-encrypted connection.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
See C/C++ driver SSL and CassSsl.
See C# driver TLS/SSL.
See the documentation for your version of the Java driver:
By default DSE clusters are configured to communicate with clients using an unencrypted binary protocol. This is convenient for getting started but it isn’t suitable for production environments.
To enable SSL, you need access to your cluster’s cassandra.yaml file.
The location of the cassandra.yaml file depends on your database platform and the installation method.
For information about editing cassandra.yaml and configuring SSL, see Configure SSL for DataStax Enterprise.
Then, configure your driver to use the SSL certificates and the SSL-encrypted connection.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
See C/C++ driver SSL and CassSsl.
See C# driver TLS/SSL.
See the documentation for your version of the Java driver:
The DataStax PHP driver is in maintenance mode (not actively developed), and the DSE-only PHP driver is EOL. DataStax recommends using an actively supported driver if possible.
If you must use a PHP driver to support a legacy application or database, see DataStax PHP driver for Apache Cassandra®.
The DataStax Ruby driver is in maintenance mode (not actively developed), and the DSE-only Ruby driver is EOL. DataStax recommends using an actively supported driver if possible.
If you must use a Ruby driver to support a legacy application or database, see DataStax Ruby driver for Apache Cassandra®.
By default HCD clusters are configured to communicate with clients using an unencrypted binary protocol. This is convenient for getting started but it isn’t suitable for production environments.
To enable SSL, you need access to your cluster’s cassandra.yaml file.
The location of the cassandra.yaml file depends on your database platform and the installation method.
For information about editing cassandra.yaml and configuring SSL, see Configure SSL for HCD.
Then, configure your driver to use the SSL certificates and the SSL-encrypted connection.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
See C/C++ driver SSL and CassSsl.
See C# driver TLS/SSL.
See GoCQL driver transport layer security and the Go driver connection guide in Mission Control.
See the documentation for your version of the Java driver:
The DataStax PHP driver isn’t compatible with HCD.
The DataStax Ruby driver isn’t compatible with HCD.
Drivers that support Astra DB automatically establish SSL encrypted connections between your database and drivers through the Secure Connect Bundle (SCB).
When connecting to Astra DB, if your driver supports SCB authentication, you don’t need to do any additional configuration to enable SSL.
If you must use an earlier driver version to support a legacy application, you can extract the SCB and manually provide the certificates to the driver. However, DataStax recommends using a newer driver version whenever possible. For more information about this option, see the Astra DB guidance in Configure authentication.
Connect your driver
After you configure authentication, you can configure your driver to connect to your databases. Driver connection strings vary by driver language and database platform.
-
Cassandra
-
DSE
-
HCD
-
Astra DB
See your driver’s documentation for examples and information about connecting the driver to your Cassandra clusters. The following information is for DataStax-compatible Cassandra drivers. For all Cassandra drivers, see the list of Cassandra client drivers in the Apache Cassandra documentation.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
See the documentation for your version of the Java driver:
See the following:
The DataStax PHP driver is in maintenance mode, and it isn’t actively developed. DataStax recommends using an actively supported driver if possible.
If you must use the DataStax PHP driver to support a legacy application or database, you can find connection information at DataStax PHP driver usage.
The DataStax Ruby driver is in maintenance mode, and it isn’t actively developed. DataStax recommends using an actively supported driver if possible.
If you must use the DataStax Ruby driver to support a legacy application or database, you can find connection information at DataStax Ruby driver usage.
The authentication methods that your DSE cluster supports determines which credentials you need for your driver’s connection. See your driver’s documentation for connection details and examples of DSE connections.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
If you have enabled DSE advanced workloads, you must configure your driver to connect to compatible nodes when sending DSE Search queries. For more information, see DSE advanced workloads in Cassandra drivers.
If you have enabled DSE advanced workloads, you must configure your driver to connect to compatible nodes when sending DSE Search or Graph queries. For more information, see DSE advanced workloads in Cassandra drivers.
The GoCQL driver doesn’t support DSE advanced workloads. For more information, see DSE advanced workloads in Cassandra drivers.
See Java driver quickstart for DSE and the documentation for your version of the Java driver:
If you have enabled DSE advanced workloads, you must configure your driver to connect to compatible nodes when sending DSE Search or Graph queries. For more information, see DSE advanced workloads in Cassandra drivers.
See Node.js driver quickstart for DSE and the following:
If you have enabled DSE advanced workloads, you must configure your driver to connect to compatible nodes when sending DSE Search or Graph queries. For more information, see DSE advanced workloads in Cassandra drivers.
The DataStax PHP driver is in maintenance mode (not actively developed), and the DSE-only PHP driver is EOL. DataStax recommends using an actively supported driver if possible.
If you must use a PHP driver to support a legacy application or database, see DataStax PHP driver for Apache Cassandra®.
If you have enabled DSE advanced workloads, you must configure your driver to connect to compatible nodes when sending DSE Search or Graph queries. For more information, see DSE advanced workloads in Cassandra drivers.
The DataStax Ruby driver is in maintenance mode (not actively developed), and the DSE-only Ruby driver is EOL. DataStax recommends using an actively supported driver if possible.
If you must use a Ruby driver to support a legacy application or database, see DataStax Ruby driver for Apache Cassandra®.
The authentication methods that your HCD cluster supports determines which credentials you need for your driver’s connection. See your driver’s documentation for connection details and examples.
Most DSE-specific information in the driver documentation also applies to HCD. If a DSE-specific feature isn’t supported in HCD, use built-in Cassandra-compatible options instead.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
See Java driver quickstart for HCD and the documentation for your version of the Java driver:
See Node.js driver quickstart for HCD and the following:
The DataStax PHP driver isn’t compatible with HCD.
The DataStax Ruby driver isn’t compatible with HCD.
After obtaining the necessary authentication credentials, see your driver’s documentation for Astra DB connection details and examples.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
To use the GoCQL driver with Astra DB, DataStax provides gocql-astra, which includes gocql and additional support for connections to Astra DB.
To get started, see Go driver quickstart for Astra DB.
See Java driver quickstart for Astra DB and the documentation for your version of the Java driver:
See Node.js driver quickstart for Astra DB and the following:
The DataStax PHP driver isn’t compatible with Astra DB.
See the following:
The DataStax Ruby driver isn’t compatible with Astra DB.
Driver sessions and clusters
All drivers use root objects to connect to your Cassandra clusters, which can be Astra DB databases, DSE clusters, Cassandra clusters, or HCD clusters.
These root objects are expensive to create because they initialize and maintain connection pools to every node in a cluster. However, a single root object can handle thousands of queries concurrently, so you can use the same session instance to execute all the queries for an application.
Follow these best practices to ensure that you instantiate and reuse these objects effectively:
-
Create only one long-lived root object for each physical cluster.
-
Create one session instance for each application, and then reuse that session for the entire lifetime of the application. For example, don’t open and close the session object for each individual request or batch of requests.
-
For multi-region Astra DB databases, you must instantiate one root object for each region that your application needs to connect to, and you must provide the region-specific SCB for authentication in each root object.
The Java and Node.js drivers combine the cluster and session concepts into one object.
All other drivers provide separate cluster and session objects.
For more information about session and cluster configuration, see your driver’s documentation.
-
C/C++
-
C#
-
Go
-
Java
-
Node.js
-
PHP
-
Python
-
Ruby
Create one CassCluster for each physical cluster.
Create and reuse one CassSession for each application.
Create one Cassandra.Cluster for each physical cluster.
Create and reuse one Cassandra.Session for each application.
Create one NewCluster for each physical cluster.
Create and reuse one Session for each application.
The Java driver defines clusters and sessions together in CqlSession.
Create one CqlSession instance for each target physical Cassandra cluster, and then reuse those instances throughout your application.
For more information and examples, see the documentation for your version of the Java driver:
If you want the driver to retry the connection if it fails to establish a CQL session, set advanced.reconnect-on-init to true.
For more information, see Cassandra driver reconnection policies.
The Node.js driver combines the concepts of session and cluster into a single Client interface.
Create one Client instance for a given cluster, and then use that instance across your application.
For an example, see Getting started with the Node.js driver.
Use Cassandra::Cluster for each physical cluster.
Use Cassandra::Session for each application.
For more information and best practices to help optimize driver connections, see Performance tuning for Cassandra drivers.
Connection pools and initial contact points
Connection pooling is separate from the initial contact points. Initial contact points are supplied to the root driver instance (session or cluster), and those contact points are used to establish the control connection required to discover the cluster topology only.
When you create a cluster object for Cassandra, DSE, or HCD, DataStax recommends that you specify multiple contact points from your cluster. If your cluster is deployed to multiple availability zones, specify contact points from different zones.
The driver discovers all the nodes after a successful connection to the cluster, but you can improve resilience by providing multiple contact points. If no contact points are available, then cluster object creation fails.
You don’t need to do this for Astra DB because the contact points are provided in the database’s Secure Connect Bundle (SCB). For a multi-region Astra DB database, you must download the SCB for each region, and then configure your driver connections to use the appropriate region-specific SCB.
Reconnect drivers after a migration
If you migrate your data from one Cassandra database platform to another, you must update your client applications to connect to your new databases.
At minimum, you must update the driver connection strings.
Additional changes might be required if you upgraded your driver version or migrated to a database platform with a different feature set.
For example, if you migrated to Astra DB, your drivers cannot create keyspaces because CQL for Astra DB doesn’t support CREATE KEYSPACE.
For information about updating driver connections after a migration, see the DataStax migration documentation on Connecting client applications to your new target database. Although this documentation is in the context of zero downtime migration, the information applies to most Cassandra-to-Cassandra migrations where you need to update Cassandra driver connection strings.
