C++ driver quickstart

This driver doesn’t support the vector data type.

DataStax recommends CQL drivers only for Serverless (Non-Vector) databases, existing applications that previously used a CQL-based driver, or if you plan to exclusively use CQL.

It is possible to use CQL drivers for non-vector data in Serverless (Vector) databases. However, DataStax recommends the Data API and clients for Serverless (Vector) databases.

To determine the option that best suits your use case, see Compare connection methods.

This quickstart explains how to install the driver, connect it to your database, and, if necessary, migrate an existing DataStax C++ driver to a version that can connect to your Serverless (Non-Vector) database.

Prerequisites

An active Astra account
An active Serverless (Non-Vector) database
A secure connect bundle downloaded from the Astra Portal
An application token

Install the C++ driver

Download and install the C++ driver and its dependencies for your platform.

DataStax provides pre-built packages for CentOS 7, Ubuntu 20.04/22.04, Rocky Linux 8/9, and Windows in the DataStax Artifactory server. If a package isn’t available for your platform, you can build the driver from the source code packages.

CentOS
Rocky Linux
Ubuntu
Windows

CentOS doesn’t have up-to-date versions of libuv so DataStax provides current packages. You can find these packages in the dependencies directory under each driver version in Artifactory.

Install dependencies. Replace VERSION with the release version of the package.
```
$ yum install openssl krb5 zlib
$ rpm -Uvh libuv-VERSION.rpm
```

Install the runtime library:

$ rpm -Uvh cassandra-cpp-driver-VERSION.rpm

Optional: Install the development package and the debug symbols:

$ rpm -Uvh cassandra-cpp-driver-devel-VERSION.rpm
$ rpm -Uvh cassandra-cpp-driver-debuginfo-VERSION.rpm

Rocky Linux doesn’t have up-to-date versions of libuv so packages are available for this platform.

Install dependencies:

$ yum install openssl krb5 zlib
$ rpm -Uvh libuv-VERSION.rpm

Install the runtime library:

$ rpm -Uvh cassandra-cpp-driver-VERSION.rpm

Optional: Install the development package and the debug symbols:

$ rpm -Uvh cassandra-cpp-driver-devel-VERSION.rpm
$ rpm -Uvh cassandra-cpp-driver-debuginfo-VERSION.rpm

Newer versions of Ubuntu include workable versions of all dependencies; you don’t need to download anything from Artifactory.

Run the following commands to install dependencies:
```
$ apt-get install libssl libkrb5 zlib1g libuv1
```

Install the runtime library:

$ dpkg -i cassandra-cpp-driver_VERSION.deb

Optional: Install the development package and the debug symbols.

$ dpkg -i cassandra-cpp-driver-dev_VERSION.deb
$ dpkg -i cassandra-cpp-driver-dbg_VERSION.deb

DataStax provides packages (.zip files) for all of the dependencies, except for Kerberos, on Windows because they can be difficult to build and install.

Unzip the packages downloaded from Artifactory.
Add the include and library directories to the Additional Include Directories and Additional Dependencies configuration properties for your project.
Download and install Kerberos for Windows.

If pre-built packages are not available for your platform or architecture you must build the driver from the original source code.

Connect the C++ driver to your database

Create a connect_database.c file in the main directory for your C++ project:
```
$ cd my_project
$ touch connect_database.c
```

Copy the following connection code into the connect_database.c file. You must set the secure_connect_bundle variable to the absolute path of your Astra database credentials file (secure-connect-DATABASE_NAME.zip).

Do not 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.

#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 = "/SECURE_CONNECT_BUNDLE_PATH/secure-connect-DATABASE_NAME.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, "clientID", "clientSecret");

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

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

Linux or macOS
Windows

For static linking, use cassandra_static.a.

cc connect_database.c -I/path/to/cassandra.h -L/path/to/cassandra.so -lcassandra

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. cassandra.dll must be in the runtime path for your application. For static linking, use cassandra_static.lib.

After connecting to your database, use the following code to query your database. This code creates a CassStatement object to connect to your Astra DB database, runs a CQL query, and prints the output to the console.

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

Migrate the C++ driver

If necessary, you can migrate an earlier DataStax C++ driver to a version that can connect to your Serverless (Non-Vector) database.

Complete the prerequisites.
Download and install the latest C++ driver version and its dependencies.

In your existing C++ driver code, modify the connection code to use the secure connect bundle credentials:

cass_cluster_set_credentials(cluster, "clientId", "clientSecret");

  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
  }

Both the C++ driver for Apache Cassandra® and the DataStax Enterprise (DSE) C++ driver use the same code to connect and query your Astra DB database. When using the DSE C++ driver, use the header #include <dse.h>.

Build and link your application against the C++ driver for Cassandra.
- Linux or macOS
- Windows
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
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. Your application requires cassandra.dll to be in your runtime path.

C++ driver quickstart

Prerequisites

Install the C++ driver

Connect the C++ driver to your database

Migrate the C++ driver

Was this helpful?

Give Feedback