Connect with the C++ driver

DataStax recommends the Data API and clients for Serverless (vector) databases. You can use the Data API to run CQL statements on tables in Serverless (vector) databases.

DataStax recommends drivers only for Serverless (non-vector) databases, legacy applications that rely on a driver, or CQL functions that aren’t supported by the Data API. For more information, see Connect to Astra DB Serverless databases.

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

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

This quickstart explains how to install the driver and connect it to your database. It also explains how to upgrade from an earlier version of the C++ driver to a version that supports Astra DB.

The C++ driver doesn’t support the vector data type.

Prerequisites

  1. Create a database.

  2. Download your database’s Secure Connect Bundle (SCB).

    For multi-region databases, download the SCB for a region that is geographically close to your application to reduce latency.

    If you need to connect to multiple regions in the same application, you need the SCB for each region, and your driver code must instantiate one root object (session) for each region. For more information, see Best practices for Cassandra drivers.

  3. Set the following environment variables:

Driver authentication methods

There are two driver authentication methods:

token authentication

The token authentication method is supported and recommended for most recent driver versions.

In your driver authentication code, pass the literal string token as the username and your application token value (AstraCS:…​) as the password. For example:

("token", "AstraCS:...")
clientId and secret authentication

If you are on an older driver version that doesn’t support token authentication, then you might need to use clientId and secret.

When you generate an application token, download or copy the token.json that contains the following values:

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

Then, in your driver authentication code, pass clientId as the username and secret as the password. For example:

("CLIENT_ID", "SECRET")

For more information, see Token details.

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 DB. If you need to query vector data in Astra DB Serverless (vector) databases, make sure your version also supports vector data. For more information, see Cassandra drivers supported by DataStax.

Connect the C++ driver

  1. In the root of your C++ project, create a connect_database.c file:

    cd my_project
touch connect_database.c

  2. Copy the following connection code into the connect_database.c file, and then replace PATH/TO/SCB.zip with the absolute path to your database’s Secure Connect Bundle (SCB) zip file (secure-connect-DATABASE_NAME.zip):

    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 /
     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;
   }

    This code creates a CassStatement object to connect to your database.

    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.

  3. 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);

  4. Build and link your application against the C++ driver.

    Linux or macOS

    For static linking, use cassandra_static.a:

    cc connect_database.c -I/path/to/cassandra.h -L/path/to/cassandra.so -lcassandra
    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.

  5. Run the compiled application.

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

  6. Extend or modify this script to run other commands against your database or connect to other databases. For more information, see C++ driver documentation and DataStax-compatible Cassandra drivers.

Upgrade the C++ driver

Use these steps if you need to upgrade from an earlier version of the C++ driver to a version that supports Astra DB:

  1. Complete the prerequisites.

  2. Download and install the latest C++ driver and its dependencies.

  3. In your existing C++ driver code, modify the connection code to use the SCB 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 /
     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.

  4. Build and link your application against the C++ driver.

    Linux or macOS

    For static linking, use cassandra_static.a or dse_static.a:

    cc connect_database.c -I/path/to/cassandra.h -L/path/to/cassandra.so -lcassandra
    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.

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

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.

General Inquiries: Contact IBM