search

scylladb / cpp-rust-driver

API-compatible rewrite of https://github.com/scylladb/cpp-driver as a wrapper for Rust driver.
GNU Lesser General Public License v2.1
16 stars 11 forks source link

readme

ScyllaDB Cpp-Rust Driver

Wrapper around ScyllaDB's rust-driver compatible with Datastax cpp-driver.

Note: It is work in progress, bug reports and pull requests are welcome!

Examples

There are some examples in the examples directory. To run a single example:

cd examples/cloud
gcc cloud.c PATH_TO_CPP_RUST/scylla-rust-wrapper/target/debug/libscylla_cpp_driver.so -Wl,-rpath,PATH_TO_CPP_RUST/build  -I PATH_TO_CPP_RUST/include -o cloud
./cloud path_to_connection_bundle username password
#include <cassandra.h>
#include <stdio.h>

int main(int argc, char* argv[]) {
  /* Setup and connect to cluster */
  CassFuture* connect_future = NULL;
  CassCluster* cluster = cass_cluster_new();
  CassSession* session = cass_session_new();
  char* hosts = "127.0.0.1";
  if (argc > 1) {
    hosts = argv[1];
  }

  /* Add contact points */
  cass_cluster_set_contact_points(cluster, hosts);

  /* Provide the cluster object as configuration to connect the session */
  connect_future = cass_session_connect(session, cluster);

  if (cass_future_error_code(connect_future) == CASS_OK) {
    CassFuture* close_future = NULL;

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

    /* Close the session */
    close_future = cass_session_close(session);
    cass_future_wait(close_future);
    cass_future_free(close_future);
  } else {
    /* Handle error */
    const char* message;
    size_t message_length;
    cass_future_error_message(connect_future, &message, &message_length);
    fprintf(stderr, "Unable to connect: '%.*s'\n", (int)message_length, message);
  }

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

  return 0;
}

Logging

The logging API and implementation are compatible with the C++ driver, for more details please refer to the logging documentation. As the tracing framework is used under the hood to instrument the collection of logs from the Rust driver and the Cpp-Rust wrapper, the logging level and callback are passed through a custom event subscriber which is globally set as default when cass_log_set_level is called. So, cass_log_set_level must be called only once as subsequent attempts trying to modify the globally set event subscriber will be ignored. Also, Rust programs using Cpp-Rust driver under the hood must avoid calling tracing::subscriber::set_global_default as this will cause conflicts.

Note: The logging configuration must be done before any other driver function is called, otherwise, the default logging callback will be used, and logs will appear on stderr.
void on_log(const CassLogMessage* message, void* data) {
  /* Handle logging */
}

int main() {
  void* log_data = NULL /* Custom log resource */;
  cass_log_set_callback(on_log, log_data);
  cass_log_set_level(CASS_LOG_INFO);

  /* Create cluster and connect session */
}

Features

The driver inherits almost all the features of C/C++ and Rust drivers, such as:

Limitations

Note: This section may be incomplete, so not everything that is unimplemented is mentioned here.
Function Description
Statement
cass_statement_bind_custom[by_name] Binding is not implemented for custom types in the Rust driver.
Future
cass_future_coordinator Unimplemented
Collection
cass_collection_append_custom[_n] Unimplemented because of the same reasons as binding for statements.
Note: The driver does not check whether the type of the appended value is compatible with the type of the collection items.
User Defined Type
cass_user_type_set_custom[by_name] Unimplemented because of the same reasons as binding for statements.
Note: The driver does not check whether the type of the value being set for a field of the UDT is compatible with the field's actual type.
Value
cass_value_get_bytes When the above requirement is satisfied, this should be implemented for all CQL types. Currently, it returns only bytes of a Blob object, otherwise returns CASS_ERROR_LIB_INVALID_VALUE_TYPE.
Timestamp generators
cass_timestamp_gen_server_side_new Timestamp generator is not implemented in the Rust driver.
cass_timestamp_gen_monotonic_new
cass_timestamp_gen_monotonic_new_with_settings
cass_timestamp_gen_free
cass_cluster_set_timestamp_gen
Metadata
cass_keyspace_meta_is_virtual UDF, Aggregate and Index are not supported in the Rust driver, yet.
cass_table_meta_is_virtual
cass_table_meta_clustering_key_order
cass_materialized_view_meta_clustering_key_order
cass_function_*
cass_aggregate_*
cass_index_*

Testing

Integration tests from the original cpp-driver are compilable but not all tests pass yet. Some tests are added to GitHub Actions workflows and are used to test every pull request on both ScyllaDB and Cassandra clusters.

To build and run the integration tests several requirements need to be met:

# On Ubuntu
sudo apt-get install libuv1-dev
sudo apt-get install libssl1.0.0
sudo apt-get install libkrb5-dev

# On Fedora
sudo dnf install libuv-devel
sudo dnf install openssl-devel
sudo dnf install krb5-devel

Finally, to build the integration tests:

mkdir build && cd build
cmake -DCASS_BUILD_INTEGRATION_TESTS=ON  .. && make

Now, use --gtest_filter to run certain integration tests:

./cassandra-integration-tests --scylla --install-dir=[PATH_TO_SCYLLA] --version=3.0.8 --category=CASSANDRA --verbose=ccm --gtest_filter="ClusterTests.*"
Note: Tests that pass with ScyllaDB and Cassandra clusters can be found in GitHub Actions build.yml and cassandra.yml workflows.

Build rpm package

To build rpm package, run the following command:

./dist/redhat/build_rpm.sh --target rocky-8-x86_64

It will construct chrooted build environment of target distribution using mock, and build rpm in the environment. Target parameter should be mock .cfg file name. Currently tested on rocky-8-x86_64, rocky-9-x86_64, fedora-38-x86_64, fedora-39-x86_64, fedora-40-x86_64, fedora-rawhide-x86_64. Build environment should be Fedora or RHEL variants + EPEL, since other distribution does not provide mock package. Built result will placed under build/redhat/{rpms,srpms}.

Build deb package

To build deb package, run the following command:

./dist/debian/build_deb.sh --target mantic

It will construct chrooted build environment of target distribution using pbuilder, and build deb in the environment. Target parameter should be debian/ubuntu codename. On Ubuntu targets, currently tested on bionic (18.04), focal (20.04), jammy (22.04), mantic (23.10), noble (24.04). On Debian targets, currently tested on buster (10), bullseye (11), bookworm (12), trixie (13), sid (unstable). Build environment should be Fedora, Ubuntu or Debian, since these distribution provides pbuilder package. Built result will placed under build/debian/debs.

Build & install HomeBrew package (macOS)

To build HomeBrew pacakge, run the following command:

cd dist/homebrew
brew install --HEAD ./scylla-cpp-rust-driver.rb

It will run build & install the driver in HomeBrew environment. Tested on macOS 14.5.

Getting Help

Reference Documentation

Other Drivers

License

This project is licensed under the GNU Lesser General Public License v2.1