Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add extensive information about the driver in README
Browse files Browse the repository at this point in the history
@Gor027
Gor027 committed Oct 11, 2022

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode
1 parent 4e1207a commit 8dff52c
Showing 1 changed file with 305 additions and 6 deletions.
311 changes: 305 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,311 @@
# cpp-rust-driver
Wrapper around ScyllaDB's rust-driver compatible with Datastax cpp-driver (WIP)
# 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](https://github.com/scylladb/cpp-rust-driver/tree/master/examples) directory.

```c++
#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;
}
```
# Features
___
The driver inherits almost all the features of C/C++ and Rust drivers, such as:
* [Asynchronous API](http://datastax.github.io/cpp-driver/topics/#futures)
* Shard-aware routing
* Simple, Prepared and Batch statements
* Query paging
* CQL binary protocol version 4
* Load balancing policies
* Retry policies
* SSL
* Authentication
* [Tuples](http://datastax.github.io/cpp-driver/topics/basics/tuples/) and [UDTs](http://datastax.github.io/cpp-driver/topics/basics/user_defined_types/)
* [Nested collections](http://datastax.github.io/cpp-driver/topics/basics/binding_parameters/#nested-collections)
* [Data types](http://datastax.github.io/cpp-driver/topics/basics/data_types/)
* Schema metadata (keyspace metadata, materialized views, etc.)
# Limitations
<table>
<thead>
<tr>
<th>Function</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan=2 align="center" style="font-weight:bold">Prepared</td>
</tr>
<tr>
<td>cass_prepared_parameter_name</td>
<td rowspan="2">Unimplemented</td>
</tr>
<tr>
<td>cass_prepared_parameter_data_type[by_name]</td>
</tr>
<tr>
<td colspan=2 align="center" style="font-weight:bold">Statement</td>
</tr>
<tr>
<td>cass_statement_bind_custom[by_name]</td>
<td rowspan="3">Binding is not implemented for custom types in the Rust driver. <br> Binding Decimal and Duration types requires encoding raw bytes into BigDecimal and CqlDuration types in the Rust driver.</td>
</tr>
<tr>
<td>cass_statement_bind_decimal[by_name]</td>
</tr>
<tr>
<td>cass_statement_bind_duration[by_name]</td>
</tr>
<tr>
<td colspan=2 align="center" style="font-weight:bold">Future</td>
</tr>
<tr>
<td>cass_future_wait_timed</td>
<td rowspan="3">Unimplemented</td>
</tr>
<tr>
<td>cass_future_tracing_id</td>
</tr>
<tr>
<td>cass_future_coordinator</td>
</tr>
<tr>
<td colspan=2 align="center" style="font-weight:bold">Collection</td>
</tr>
<tr>
<td>cass_collection_new_from_data_type</td>
<td rowspan="2">Unimplemented</td>
</tr>
<tr>
<td>cass_collection_data_type</td>
</tr>
<tr>
<td>cass_collection_append_custom[_n]</td>
<td rowspan="3">Unimplemented because of the same reasons as binding for statements.<br> <b>Note</b>: The driver does not check whether the type of the appended value is compatible with the type of the collection items.</td>
</tr>
<tr>
<td>cass_collection_append_decimal</td>
</tr>
<tr>
<td>cass_collection_append_duration</td>
</tr>
<tr>
<td colspan=2 align="center" style="font-weight:bold">User Defined Type</td>
</tr>
<tr>
<td>cass_user_type_set_custom[by_name]</td>
<td rowspan="3">Unimplemented because of the same reasons as binding for statements.<br> <b>Note</b>: 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.</td>
</tr>
<tr>
<td>cass_user_type_set_decimal[by_name]</td>
</tr>
<tr>
<td>cass_user_type_set_duration[by_name]</td>
</tr>
<tr>
<td colspan=2 align="center" style="font-weight:bold">Value</td>
</tr>
<tr>
<td>cass_value_is_duration</td>
<td>Unimplemented</td>
</tr>
<tr>
<td>cass_value_get_decimal</td>
<td rowspan="2">Getting raw bytes of Decimal and Duration values requires lazy deserialization feature in the Rust driver.</td>
</tr>
<tr>
<td>cass_value_get_duration</td>
</tr>
<tr>
<td>cass_value_get_bytes</td>
<td>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.</td>
</tr>
<tr>
<td colspan=2 align="center" style="font-weight:bold">Timestamp generators</td>
</tr>
<tr>
<td>cass_timestamp_gen_server_side_new</td>
<td rowspan="5">Timestamp generator is not implemented in the Rust driver.</td>
</tr>
<tr>
<td>cass_timestamp_gen_monotonic_new</td>
</tr>
<tr>
<td>cass_timestamp_gen_monotonic_new_with_settings</td>
</tr>
<tr>
<td>cass_timestamp_gen_free</td>
</tr>
<tr>
<td>cass_cluster_set_timestamp_gen</td>
</tr>
<tr>
<td colspan=2 align="center" style="font-weight:bold">Metadata</td>
</tr>
<tr>
<td>cass_keyspace_meta_is_virtual</td>
<td rowspan="7">Currently, fetching metadata information is under review and is not merged yet:<br> &bull; <a href="https://github.com/scylladb/cpp-rust-driver/pull/72">Schema metadata</a> <br> &bull; <a href="https://github.com/scylladb/cpp-rust-driver/pull/76">Materialized View</a> <br> UDF, Aggregate and Index are not supported in the Rust driver, yet. </td>
</tr>
<tr>
<td>cass_table_meta_is_virtual</td>
</tr>
<tr>
<td>cass_table_meta_clustering_key_order</td>
</tr>
<tr>
<td>cass_materialized_view_meta_clustering_key_order</td>
</tr>
<tr>
<td>cass_function_*</td>
</tr>
<tr>
<td>cass_aggregate_*</td>
</tr>
<tr>
<td>cass_index_*</td>
</tr>
</tbody>
</table>
# Testing
Integration tests from the original `cpp-driver` are compilable but do not pass yet (also they require libuv, openssl and kerberos to build). To build and run them:
___
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:
* Install `libuv`, `openssl` and `kerberos` on your system:
```shell
# 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
```

* Clone and install [scylla-ccm](https://github.com/scylladb/scylla-ccm) system-wide
* Clone and build [scylla-jmx](https://github.com/scylladb/scylla-jmx) alongside `scylla-ccm`
* Clone, build and symlink [scylla-tools-java](https://github.com/scylladb/scylla-tools-java) from `[SCYLLA_ROOT]/resources/cassandra`
* Assuming `scylla` is installed and built in the release mode <br> ``` ln -s [PATH_TO_TOOLS]/scylla-tools-java [PATH_TO_SCYLLA]/resources/cassandra```

Finally, to build the integration tests:

```
mkdir build && cd build
cmake -DCASS_BUILD_INTEGRATION_TESTS=ON ..
make
./cassandra-integration-tests
cmake -DCASS_BUILD_INTEGRATION_TESTS=ON .. && make
```

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

```shell
./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`](https://github.com/scylladb/cpp-rust-driver/blob/master/.github/workflows/build.yml) and [`cassandra.yml`](https://github.com/scylladb/cpp-rust-driver/blob/master/.github/workflows/cassandra.yml) workflows.

# Getting Help
___

* Slack: http://slack.scylladb.com/
* `Issues` section of GitHub repository

# Reference Documentation
___

* [CQL binary protocol](https://github.com/apache/cassandra/blob/trunk/doc/native_protocol_v4.spec) version 4

# Other Drivers
___

* [ScyllaDB Rust driver](https://github.com/scylladb/scylla-rust-driver)
* [C/C++ Driver for ScyllaDB](https://github.com/scylladb/cpp-driver)

# License
___

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

0 comments on commit 8dff52c

Please sign in to comment.