Get started with the C++ driver

Because Astra Managed Clusters is based on Apache Cassandra®, you can use Cassandra drivers to connect to your Astra databases.

This quickstart explains how to install a driver, connect it to your Astra database, and then send some CQL statements to the database.

To use the C++ driver, you need to choose a compatible version, install the driver and its dependencies, and then connect the driver to your Astra database with a CassSession object. Once connected, you can write scripts that use the driver to run commands against your database.

C++ driver ownership

Following version 2.17.1, the C++ driver is maintained by the Apache Software Foundation (ASF). Version 2.17.1 and earlier were maintained by DataStax.

Version 2.17.1 and earlier were available from the DataStax Artifactory server. This Artifactory server will be removed or replaced in a later release or as determined by DataStax policies. The driver is also available from the apache/cassandra-cpp-driver GitHub repository.

C++ driver compatibility

DataStax officially supports the latest 12 months of releases, and DataStax recommends using the latest driver version whenever possible. Compatibility isn’t guaranteed for earlier versions. For upgrade guides and compatibility information for earlier versions, see Unsupported drivers.

New features and bug fixes are developed on the latest minor version of the driver, and users are encouraged to stay current with those minor releases. APIs are maintained stable according to semantic versioning conventions, and upgrades should be trivial.

Unless otherwise specified, compatibility version ranges include all patch versions. For example, a range of 4.0 to 4.3 includes all versions from 4.0.0 to the last 4.3.z release.

C++ driver compatibility
Driver version	Astra compatibility	Comments
2.15 and later	Partially compatible	Doesn’t support the vector type.
Earlier versions	Not compatible

Prepare the environment and database

Install a C++ compiler.
Create a database.
Download your database’s Secure Connect Bundle (SCB).

For more information, including connections to multi-region databases, see The SCB and encrypted connections for drivers.
Set the following environment variables:
- DATABASE_ID: The database ID.
- APPLICATION_TOKEN: An application token with the Database Administrator role.
  
  For more information, see Authentication methods for drivers.

Authentication methods for drivers

You use an application token and a Secure Connect Bundle (SCB) to connect a driver to an Astra database.

The application token authenticates the driver to the database, and the token’s role determines the actions that the driver is authorized to perform on the database. When you generate a token, the token details include a clientId, secret, and token:

{
  "clientId": "CLIENT_ID",
  "secret": "CLIENT_SECRET",
  "token": "APPLICATION_TOKEN"
}

clientId and secret are legacy authentication methods that predate token.
token is a unified token that comprises everything you need for Astra token authentication.

Cassandra drivers use username and password authentication for Astra connections, typically through an authentication class or argument, such as PlainTextAuthProvider. To set the username and password for a Cassandra driver connection, you can use either the unified token or the legacy clientId and secret:

Unified token authentication (Recommended)

To authenticate with the unified application token, set the username to the literal string token, and set the password to your unified application token. For example:

("token", "APPLICATION_TOKEN")

Legacy clientId and secret authentication

For legacy applications and older driver versions that don’t use unified application tokens, you can use the clientId as the username and the secret as the password. For example:

("CLIENT_ID", "SECRET")

However, if you are using a legacy token created prior to the introduction of the unified token format, DataStax recommends rotating these tokens due to their age.

In addition to the application token, you must provide an SCB to set contact points and establish a secure connection to your database. For more information, see The SCB and encrypted connections for drivers.

The SCB and encrypted connections for drivers

In addition to an application token, you must provide an SCB to set contact points and provide certificates necessary to establish a secure mutual TLS (mTLS) connection to your database.

To establish an encrypted connection between your application and database, the driver uses the SSL certificates and trusted certificate authorities (CAs) in the SCB to verify the Astra server’s identity. Mechanically, 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 driver 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 list of trusted CAs. If there are no matches, then identity verification fails and the driver connection isn’t established.

All Astra-compatible drivers have configuration file attributes, builder methods, or constructor parameters to use the SCB. In your driver configuration, you set the path to the SCB zip file, and then the driver automatically gets the required information and files from the SCB. When using an SCB, don’t set any options that are inferred from the SCB, such as contact points and SSL encryption settings. Additionally, don’t extract the SCB zip file; it must be provided to the driver as an unextracted archive.

For multi-region databases, you need the region-specific SCB for each region that your application will connect to.

To connect to one region of a multi-region database, download the SCB for a region that is geographically close to your application to reduce latency.

To connect to multiple regions or databases in the same application, download the SCB for each region or database. Then, in your application’s code, create one root driver instance (session or cluster) for each region or database, using custom logic to select the appropriate SCB for each instance. For more information, see Best practices: Session and cluster handling and Connection pools and initial contact points.

DataStax recommends that you use a driver version that supports SCB authentication for simplified configuration and reduced chance of connection failures. 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. For an example, see DataStax Ruby and PHP drivers (Maintenance).

Install the C++ driver

Download and install the C++ driver.

If you install an earlier version of the driver, make sure your version is compatible with Astra and your application’s CQL statements. For example, if you need to query vector data, make sure your driver version supports the vector type.

Connect the C++ driver

In the root of your C++ project, create a connect_database.c file:
```
cd my_project
touch connect_database.c
```

Copy the following connection code into the connect_database.c file.

This code creates a CassSession object to connect to your database. For more information, see Best practices: Session and cluster handling and Connection pools and initial contact points.

connect_database.c

#include <cassandra.h>
#include <stdio.h>

int main(int argc, char* argv[]) {
    /* Setup and connect to cluster */
    CassCluster* cluster = cass_cluster_new();
    CassSession* session = cass_session_new();

    /* Setup driver to connect to the cloud using the secure connection bundle */
    const char* secure_connect_bundle = "PATH/TO/SCB.zip";
    if (cass_cluster_set_cloud_secure_connection_bundle(cluster, secure_connect_bundle) != CASS_OK) {
      fprintf(stderr, "Unable to configure cloud using the secure connection bundle: %s\n",
              secure_connect_bundle);
      return 1;
    }

    /* Set credentials provided when creating your database */
    const char* application_token = getenv("APPLICATION_TOKEN");
    if (!application_token) {
      fprintf(stderr, "APPLICATION_TOKEN environment variable not set.\n");
      return 1;
    }
    cass_cluster_set_credentials(cluster, "token", application_token);

    CassFuture* connect_future = cass_session_connect(session, cluster);

    if (cass_future_error_code(connect_future) == CASS_OK) {
      /* Use the session to run queries */
    } else {
      /* Handle error */
    }

    cass_future_free(connect_future);
    cass_cluster_free(cluster);
    cass_session_free(session);

    return 0;
  }

Replace PATH/TO/SCB.zip with the absolute path to your database’s Secure Connect Bundle (SCB) zip file (secure-connect-DATABASE_NAME.zip).

Don’t use the cass_cluster_set_contact_points() and cass_cluster_set_ssl() methods in conjunction with the cass_cluster_set_cloud_secure_connection_bundle() method.

To test the connection, add code to your script that queries your database and prints the output to the console.

The following example queries the release_version column in the system.local table. You can replace the example SELECT statement with any CQL statement that you want to run against a keyspace and table in your database.

connect_database.c

/* Build statement and execute query */
const char_ query = "SELECT release_version FROM system.local";
CassStatement* statement = cass_statement_new(query, 0);

CassFuture* result_future = cass_session_execute(session, statement);

if (cass_future_error_code(result_future) == CASS_OK) {
  /* Retrieve result set and get the first row */
  const CassResult_ result = cass_future_get_result(result_future);
  const CassRow* row = cass_result_first_row(result);

  if (row) {
    const CassValue* value = cass_row_get_column_by_name(row, "release_version");

    const char* release_version;
    size_t release_version_length;
    cass_value_get_string(value, &release_version, &release_version_length);
    printf("release_version: '%._s'\n", (int)release_version_length, release_version);
  }

    cass_result_free(result);
  } else {
    /_ Handle error _/
    const char_ message;
    size_t message_length;
    cass_future_error_message(result_future, &message, &message_length);
    fprintf(stderr, "Unable to run query: '%.*s'\n", (int)message_length, message);
  }

  cass_statement_free(statement);
  cass_future_free(result_future);

Build and link your application against the C++ driver:
Linux or macOS
cc connect_database.c -I/path/to/cassandra.h -L/path/to/cassandra.so -lcassandra
For static linking, use cassandra_static.a.
Windows
Include these libraries in your Microsoft Visual Studio project by adding them to the project’s properties under Configuration Properties/Linker/Input/Additional Dependencies:
Link your application against cassandra.lib. For static linking, use cassandra_static.lib.

cassandra.dll must be in your application’s runtime path.
Run the compiled application.

The console output includes the release_version value from the system.local table.

Next, you can extend or modify this script to run other commands against your database or connect to other databases. For more information, see the C++ driver documentation.

Reconnect the C++ driver 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 to a new major driver version or migrated to a database platform with a different feature set. For example, if you migrate to Astra, your drivers cannot create keyspaces because CQL for Astra 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 the referenced 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.

The following steps summarize the process for updating your driver connection strings after you migrate to Astra:

Prepare the environment and database.
Install the C++ driver.

The latest version is recommended, but you can use any Astra-compatible version.

In your existing C++ driver code, modify the connection code to use the SCB (PATH/TO/SCB.zip) and token authentication:

#include <cassandra.h>
#include <stdio.h>

int main(int argc, char* argv[]) {
    /* Setup and connect to cluster */
    CassCluster* cluster = cass_cluster_new();
    CassSession* session = cass_session_new();

    /* Set up driver to connect to the cloud using the SCB */
    const char* secure_connect_bundle = "PATH/TO/SCB.zip";
    if (cass_cluster_set_cloud_secure_connection_bundle(cluster, secure_connect_bundle) != CASS_OK) {
      fprintf(stderr, "Unable to configure cloud using the SCB: %s\n",
              secure_connect_bundle);
      return 1;
    }

    /* Set credentials provided when creating your database */
    const char* application_token = getenv("APPLICATION_TOKEN");
    if (!application_token) {
      fprintf(stderr, "APPLICATION_TOKEN environment variable not set.\n");
      return 1;
    }
    cass_cluster_set_credentials(cluster, "token", application_token);

    CassFuture* connect_future = cass_session_connect(session, cluster);

    if (cass_future_error_code(connect_future) == CASS_OK) {
      /* Use the session to run queries */
    } else {
      /* Handle error */
    }

    cass_future_free(connect_future);
    cass_cluster_free(cluster);
    cass_session_free(session);

    return 0;
  }

For more information, see Connect the C++ driver.

Build and run the application. For more information, see Connect the C++ driver.

Get started with the C++ driver

C++ driver ownership

C++ driver compatibility

Prepare the environment and database

Authentication methods for drivers

The SCB and encrypted connections for drivers

Install the C++ driver

Connect the C++ driver

Reconnect the C++ driver after a migration

Documentation and release notes

Was this helpful?

Give Feedback