Get started with the C++ driver

Because DataStax Enterprise (DSE) is based on Apache Cassandra®, you can use Cassandra drivers to connect to your DSE databases.

This quickstart explains how to install a driver, connect it to your DSE 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 DSE 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	DSE 6.9	DSE 6.8	DSE 5.1	Comments
2.15 and later	Partially compatible	Partially compatible	Partially compatible	Doesn’t support the vector type. Doesn’t support DataStax Graph, which was introduced in DSE 6.8. Compatible with legacy DSE Graph only.
2.3 to 2.14	Partially compatible	Partially compatible	Partially compatible	Doesn’t support the vector type. The DataStax C/C++ driver unified with the DSE-only driver in version 2.15. Pre-unification versions might not support DSE-specific features. For information about a specific version, see the DataStax C/C++ driver changelog.
Earlier versions	Not compatible	Not compatible	Not compatible

Prepare the environment and database

To use this driver, you need the following:

A running DSE cluster
A keyspace
A C++ compiler installed

Authentication methods for drivers

The DSE-compatible drivers ship with built-in authentication providers that provide the necessary utilities to connect to secure DSE clusters. However, DSE clusters have no authentication service enabled by default. This simplifies initial setup, but it isn’t intended for production deployments. You must configure your preferred authentication method, security schemes, users, and roles in your clusters before attempting to use a non-default authentication method through a driver. The required credentials for the driver connection depend on your cluster and authentication method.

DSE unified authentication provides 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 passwords, LDAP/Active Directory usernames and passwords, and Kerberos authentication. All of these features are supported directly in most DSE-compatible drivers with built-in classes to enable the desired security configuration. Some drivers include support for custom authentication provider classes if your desired authentication method isn’t supported by the built-in providers.

Internal username and password authentication

Always use this method in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.

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.

To authenticate with a username and password, provide the username and password in the driver configuration. For example, in a test environment, you could use superuser credentials. In production, use narrowly scoped user roles for better security.

In addition to traditional role-based access control (RBAC), DSE supports proxy authentication (authorization through proxy roles). With proxy authentication, the driver authenticates with a fixed set of credentials that authorize access to a cluster in lieu of direct role assignment. The driver uses the credentials to connect to the cluster and execute requests (with proxy execute) within the context of the proxy roles.

This guide uses username and password authentication for simplicity. For examples of other authentication methods, including proxy authentication, see your driver’s documentation.

LDAP/Active Directory authentication

Always use this method in conjunction with client-server transport encryption because it transmits credentials in clear text in the native protocol.

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.

For usage instructions and examples, see your driver’s documentation.

Kerberos authentication

Most DSE-compatible drivers extend authentication providers to support Kerberos authentication for DSE either directly or through custom provider implementations.

Kerberos authentication uses keytabs, ticket caches, and Kerberos configuration files:

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.
Kerberos ticket cache: To use the Kerberos ticket cache, use the kinit command to authenticate with the Kerberos server and obtain a ticket. Then, verify the ticket cache contains a ticket for the successful authentication with the klist command. Once you verify there is a ticket in the ticket cache, you can run an application that is configured to use the Kerberos authentication provider. 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.
Kerberos configuration file: Driver authentication against a Kerberos-enabled DSE cluster requires a krb5.conf file containing the Kerberos configuration settings. If this file isn’t in the node’s /etc directory, contact your Kerberos system administrator to locate the file. To reference a krb5.conf file in a non-default location, set the KRB5_CONFIG environment variable to the location of your krb5.conf. Kerberos command line tools such as kinit, klist, and kdestroy respect this variable, as well as drivers with support for Kerberos authentication with krb5.conf.

For more information, see the following:

General plain-text options and custom authentication implementations: C/C++ driver security
Kerberos, proxy authentication, and DSE-specific plain-text options: C/C++ driver DSE authentication features

SSL-encrypted connections for drivers

Cassandra drivers support SSL-encrypted connections between the driver and server. Encrypted driver connections follow a typical SSL workflow:

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.

SSL isn’t required, but it is recommended for production deployments, especially those with clients communicating over the public internet.

To use SSL-encrypted connections, you must do the following:

Select an identity verification method:

No identity verification (Not recommended)

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.

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.

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 Configure SSL for client-to-node connections in DSE.
Configure SSL in your DSE cluster.

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 in a DSE cluster, you need access to your cluster’s cassandra.yaml file. The location of the cassandra.yaml file depends on your DSE installation method. For information about editing cassandra.yaml and configuring SSL, see Configure SSL for DataStax Enterprise.
Configure your driver to use the SSL certificates and the SSL-encrypted connection based on your preferred identity verification method. For instructions and examples, see C/C++ driver SSL and CassSsl.

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 DSE 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();

     /* Set credentials provided when creating your database */
     cass_cluster_set_credentials(cluster, "username", "password");

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

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 or dse_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.

Use DSE advanced workloads

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.

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.

Get started with the C++ driver

C++ driver ownership

C++ driver compatibility

Prepare the environment and database

Authentication methods for drivers

SSL-encrypted connections for drivers

Install the C++ driver

Connect the C++ driver

Use DSE advanced workloads

Reconnect the C++ driver after a migration

Documentation and release notes

Was this helpful?

Give Feedback