C++ driver quickstart
The C++ driver does not support the vector data type. These instructions are for users connecting to a HCD database. |
Use the C++ driver only if your application previously used a CQL-based driver or if you need to explicitly use CQL.
Review the Connection methods comparison page to determine the best option for your use case.
This quickstart provides an end-to-end workflow for how to install the driver, connect it to your database, and migrate an existing DataStax C++ driver to a version that is capable of connecting to your HCD database.
Prerequisites
You need the following items to complete this quickstart:
-
A running HCD database
-
The C++ driver and its dependencies for your platform downloaded from Artifactory. If a package is not available for your platform, you can build the driver from the source code packages.
Install the C++ driver
Select your platform to view the appropriate installation instructions.
Pre-built packages are available for CentOS 7, Ubuntu 20.04/22.04, Rocky Linux 8/9, and Windows. All packages are available from our Artifactory server.
-
CentOS
-
Rocky Linux
-
Ubuntu
-
Windows
CentOS doesn’t have up-to-date versions of libuv so DataStax provides current packages. These packages can be found in the dependencies directory under each driver version in Artifactory.
-
First, 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 does not have up-to-date versions of libuv so packages are available for this platform.
Run the following commands to 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 do not 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 obtained from Artifactory and add the include and library directories to the Additional Include Directories and Additional Dependencies configuration properties for your project.
Lastly, 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.#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; }
-
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
.For static linking, use
cassandra_static.lib
.Link your application against
cassandra.lib
.cassandra.dll
must be in the runtime path for your application.After connecting to your database, use the following code to query your database. This code creates a
CassStatement
object to connect to your Hyper-Converged Database (HCD) 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
Migrate your existing DataStax C++ driver to a version that is capable of connecting to your HCD database.
-
In your existing C++ driver code, modify the connection code to use the Astra DB API.
Both the C++ driver for Cassandra and the DataStax Enterprise (DSE) C++ driver use the same code to connect and query your Astra database. When using the DSE C++ driver, use the header
#include <dse.h>
.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 * }
-
Build and link your application against the C++ driver for Apache Cassandra.
-
Linux or macOS
-
Windows
For static linking, use
cassandra_static.a
ordse_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
.For static linking, use
cassandra_static.lib pass:c[
.Link your application against
cassandra.lib
. Your application requirescassandra.dll
to be in your runtime path. -