Repository files navigation

This is a maintained Rust project thatexposes the DataStax cpp driver athttps://github.com/datastax/cpp-driver/in a somewhat-sane crate.It was originally a fork ofhttps://github.com/tupshin/cassandra-rs but that is no longer maintained.

It is a wrapper around the raw driver binding cratecassandra-cpp-sys.

Documentation (crates.io).

For this crate to work, you must first have installed a sufficiently-recent version of the datastax-cpp driver (at least 2.16).Follow the steps in thecpp driver docsto do so. Pre-built packages are available for most platforms.

Make sure that the driver (specificallylibcassandra_static.a andlibcassandra.so) are in your/usr/local/lib64/ directory

Alternatively you can use theFloki utility to create you a Dockerized compilation environment. After installing Floki, just type

floki

in the root of this project. You will be dropped into a Rust compilation environment; typecargo build as normal to build the driver.

See theAPI documentation.

TheCassandra Query Language (CQL) documentationis likely to be useful.

Since this crate provides a relativelythin wrapper around the DataStax driver, you may also find the DataStaxdocumentation andAPI docs useful.

For a straightforward example seesimple.rs.

There are additional examples included with the project intests andexamples.

Version 3.0 fixes a soundness issue with the previous API. The iterators in theunderlying Cassandra driver invalidate the current item whennext() is called,and this was not reflected in the Rust binding prior to version 3.

To deal with this, the various iterators (ResultIterator,RowIterator,MapIterator,SetIterator,FieldIterator,UserTypeIterator,KeyspaceIterator,FunctionIterator,AggregateIterator,TableIterator,ColumnIterator) no longer implementstd::iter::Iterator. Instead, since thisis alendingiterator,these types all implement a newLendingIterator trait. We define thisourselves because there is currently no widely-used crate that implements it.

To upgrade, change

for rowin result{// ... do something with row ...}

to

letmut iter = result.iter();whileletSome(row) = iter.next(){// ... do something with row ...}

The intermediate variableiter is necessary, otherwise you will infinitelyvisit the first row of the result!

Other changes:

• Many types now take a lifetime argument, e.g.,Value is nowValue<'a>,ResultIterator is nowResultIterator<'a>. In almost all cases you can omitthis and it will be inferred for you. If not, you can usually writeValue<'_> to let Rust worry about it for you.
• RowIterator no longer implementsDisplay (since it would consume theiterator); howeverRow does.
• TupleIterator is removed - it was never used, since you use the set iterator(Value::get_set()) for lists, sets, and tuples.
• ConstDataType::sub_data_by_name andConstDataType::sub_type_name now take&self rather than an explicit argument.
• FunctionMeta::argument now returns the name and type, rather than just().

Version 2.0 introduces a new and safer API.Statements (andPreparedStatement andBatch) are now associated with a specificSession.In addition, the legacy.wait() API is removed in favour of the now-ubiquitous.await.

• This crate's functions have becameasync, meaning they can only be called aspart of an asynchronous workflow. To use these functions, you can either callthem from within an asynchronous function using the.await operator, or youcan call them from a synchronous context using theblock_on method fromtokioruntime.

• Thestmt! macro andStatement::new method have been replaced with theSession::statement() method, which records the association with the session.Simply update your code to use the new method instead of the macro to continueusing its functionality.

• Statements are executed with.execute(), which consumesthe statement: you cannot execute the same statement twice; if you need this,recreate the statement.

• Batch::new is removed in favour ofSession::batch.

• There is a new error,BatchSessionMismatch, which occurs if you try to addstatements from differentSessions into the sameBatch.

• Connection methods are tidied up.Cluster::connect_async is removed sinceCluster::connect is now async.Session::connect andSession::connect_keyspace are removed - useCluster::connect andCluster::connect_keyspace instead.

• Session::close (which allowed waiting until in-flight requests on thesession were complete) is removed because it is non-trivial to implementsafely. This functionality is no longer supported.

• Cluster::set_ssl now consumes its argument, for improved safety.

Since version 0.15, this crate usesstd::future, allowing your code tousefutures:0.3,async/await, etc.

Previous versions (up to 0.14) usedfutures:0.1. You can either remain onthe 0.14 stream, update your code to usestd::future, or use a compatibilityshim (e.g.,futures::compat).

The API changed significantly in version 0.10.(Version 0.9 was skipped, for consistency with thecassandra-cpp-sys version number.)For a summary of the main changes, seeCHANGELOG.

This crate includes the feature flagearly_access_min_tls_version, which allows you to build against a version of the DataStax driver including thecass_ssl_set_min_protocol_version method, as defined inthis PR. You must have a version of the driver supporting this installed locally to be able to compile (and run) with this feature flag.

When this this feature is available in the mainline driver this flag will be set to do nothing and deprecated, and the functions will be added to the main library. The flag will then be retired in the next breaking change.

This code is open source, licensed under the Apache License Version 2.0 asdescribed inLICENSE.

Please seeCONTRIBUTING.md for details on how to contributeto this project.

This crate is regularly built by GitHub Actions; to see details of the most recent buildsclick on the "build" badge at the top of this page.

You must have the DataStax driver installed on your system in order to buildthis crate.

The unit tests assume Cassandra is running on the local host accessible on thestandard port. The easiest way to achieve this is using Docker and the standardCassandra image, with

docker pull cassandradocker run -d --net=host --name=cassandra cassandra

You should run them single-threaded to avoid the dreadedorg.apache.cassandra.exceptions.ConfigurationException: Column family ID mismatcherror. The tests share a keyspace and tables, so if run in parallel theyinterfere with each other.

cargo test -- --test-threads 1

Remember to destroy the container when you're done:

docker stop cassandradocker rm cassandra

This project was forked fromcassandra, which was no longer being maintained.