cassandra-cpp
This is a maintained Rust project that exposes the DataStax cpp driver at https://github.com/datastax/cpp-driver/ in a somewhat-sane crate.
It is a wrapper around the raw driver binding crate cassandra-cpp-sys.
Getting started
You can use this crate from cargo with
[]
= "0.10"
For this crate to work, you must first have installed the datastax-cpp driver. Follow the steps in the cpp driver docs to do so. Pre-built packages are available for most platforms.
Make sure that the driver (specifically libcassandra_static.a
and libcassandra.so
) are in your /usr/local/lib64/
directory
Documentation
You can view the API documentation by running cargo doc
and visiting
target/doc
in your browser.
The Cassandra Query Language (CQL) documentation is likely to be useful.
Since this crate provides a relatively thin wrapper around the DataStax driver, you may also find the DataStax documentation and API docs useful.
Example
For a straightforward example see simple.rs
.
There are additional examples included with the project in tests
and
examples
.
Migrating from version 0.8
The API changed significantly in version 0.10. Here is a summary of the main changes.
(Version 0.9 was skipped, for consistency with the cassandra-cpp-sys
version number.)
Errors:
- The internal module
errors
and the underlyingcassandra-cpp-sys
crate are no longer exposed in the API. All necessary types are defined in this crate's root module. - All errors are now reported consistently using a single newly-defined
Error
type.- The crate makes every effort to return an error rather than panicking.
CassError
,CassErrorResult
, and others are replaced byError
andCassErrorCode
.- Several return types have changed from
T
toResult<T, Error>
.
Futures:
- There is only a single future type,
CassFuture
, and it implements the Rust/Tokio futures API. It interoperates smoothly with existing futures code.Future
,CloseFuture
,ResultFuture
,PreparedFuture
,SessionFuture
are all subsumed.wait
is replaced withFuture::wait
; other methods have standard analogues as well. See the futures documentation for details.- Callbacks can no longer be set explicitly on a future; instead the normal
futures mechanisms (e.g.,
and_then
) should be used.
Values:
- The
Column
type is retired; instead useValue
. - Some
Value
getters have new names for consistency, e.g.,get_flt
andget_dbl
are nowget_f32
andget_f64
respectively. Value::get_string
now gets aString
, not a&str
; you can get a&str
withget_str
.- The "magic" auto-converting
Row
gettersget_col
andget_col_by_name
are renamed toget
andget_by_name
respectively. This is to avoid confusion withget_column
, which is something else entirely (it gets aValue
from aRow
). - Values have a new
is_null
method to allow retrieving null values. - UUIDs now support
Eq
andOrd
.
Miscellaneous types:
- Several types which wrapped
cassandra-cpp-sys
types now have enums of their own, complete with implementations ofDebug
,Eq
,PartialEq
,Display
, andFromStr
. This includesBatchType
,CassErrorCode
,Consistency
,LogLevel
,SslVerifyFlag
, andValueType
. CqlProtocol
is now simply an alias for an integer.- Contact points are now expressed as a simple string in the driver's preferred format.
ContactPoints
is retired.
Other:
- Logging uses the
slog
crate. It is no longer possible to set your own logging callback, but you can set theslog
logger. - Internally, the code is cleaner and smaller and some tests have been added.
License
This code is open source, licensed under the Apache License Version 2.0 as
described in LICENSE
.
Contributing
Please see CONTRIBUTING.md
for details on how to contribute
to this project.
Development
This crate is regularly built by Travis; to see details of the most recent builds click on the "build" badge at the top of this page.
You must have the DataStax driver installed on your system in order to build this crate.
The unit tests assume Cassandra is running on the local host accessible on the standard port. The easiest way to achieve this is using Docker and the standard Cassandra image, with
docker pull cassandra
docker run -d --net=host --name=cassandra cassandra
You should run them single-threaded to avoid the dreaded
org.apache.cassandra.exceptions.ConfigurationException: Column family ID mismatch
error. The tests share a keyspace and tables, so if run in parallel they
interfere with each other.
cargo test -- --test-threads 1
Remember to destroy the container when you're done:
docker stop cassandra
docker rm cassandra
History
This project was forked from cassandra, which was no longer being maintained.