CDRS is Apache Cassandra driver written in pure Rust. The driver implements all the features described in Cassandra binary protocol specification (versions 3 and 4).
In order to start any communication with Cassandra cluster that requires authentication there should be provided a list of Cassandra nodes (IP addresses of machines where Cassandra is installed and included into a cluster). To get more details how to configure multinode cluster refer, for instance, to DataStax documentation.
rust
use cdrs::cluster::Cluster;
let cluster = Cluster::new(vec!["youraddress_1:9042", "youraddress_2:9042"], authenticator);
First agrument is a Rust Vec of node addresses, the second argument could be any structure that implements cdrs::authenticators::Authenticator trait. This allows to use custom authentication strategies, but in this case developers should implement authenticators by themselves. Out of the box CDRS provides two types of authenticators:
cdrs::authenticators::NoneAuthenticator that should be used if authentication is disabled (Cassandra authenticator is set to AllowAllAuthenticator) on server.
cdrs::authenticators::PasswordAuthenticator that should be used if authentication is enabled on the server and authenticator is PasswordAuthenticator:
rust
use cdrs::authenticators::PasswordAuthenticator;
let authenticator = PasswordAuthenticator::new("user", "pass");
When cluster nodes are described new Session could be established. Each new Session has its own load balancing strategy as well as data compression. (CDRS supports both Snappy and LZ4 compresssions)
rust
let mut no_compression = cluster.connect(RoundRobin::new())
.expect("No compression connection error");
let mut lz4_compression = cluster.connect_lz4(RoundRobin::new())
.expect("LZ4 compression connection error");
let mut snappy_compression = cluster.connect_snappy(RoundRobin::new())
.expect("Snappy compression connection error");
where the first argument of each connect methods is a load balancer. Each structure that implements cdrs::load_balancing::LoadBalancingStrategy could be used as a load balancer during establishing new Session. CDRS provides two strategies out of the box: cdrs::load_balancing::{RoundRobin, Random}. Having been set once at the start load balancing strategy cannot be changed during the session.
Unlike to load balancing compression method could be changed without session restart:
rust
use compression::Compression;
let mut session = cluster.connect(RoundRobin::new())
.expect("No compression connection error");
session.compression = Compression::LZ4;
SSL-encrypted connection is also awailable with CDRS however to get this working CDRS itself should be imported with ssl feature enabled:
```toml [dependencies] openssl = "0.9.6"
[dependencies.cdrs] version = "*" features = ["ssl"] ```
Another difference comparing to non-encrypted connection is necessity to create SSLConnector
```rust use std::path::Path; use openssl::ssl::{SslConnectorBuilder, SslMethod}; use cdrs::client::CDRS; use cdrs::authenticators::PasswordAuthenticator; use cdrs::transport::TransportTls;
// here needs to be a path to your SSL certificate let path = Path::new("./node0.cer.pem"); let mut sslconnectorbuilder = SslConnectorBuilder::new(SslMethod::tls()).unwrap(); sslconnectorbuilder.buildermut().setcafile(path).unwrap(); let connector = sslconnector_builder.build(); ```
When these preparation are done we're good to start SSL-encrypted session.
rust
let mut no_compression = cluster.connect_ssl(RoundRobin::new())
.expect("No compression connection error");
let mut lz4_compression = cluster.connect_lz4_ssl(RoundRobin::new())
.expect("LZ4 compression connection error");
let mut snappy_compression = cluster.connect_snappy_ssl(RoundRobin::new())
.expect("Snappy compression connection error");
More details regarding configuration Cassandra server for SSL-encrypted Client-Node communication could be found, for instance, on DataStax website.
CDRS Session implements cdrs::query::QueryExecutor trait that provides few options for immediate query execution:
```rust // simple query session.query("SELECT * from my.store").unwrap();
// simple query with tracing and warnings let withtracing = true; let withwarnings = true; session.querytw("SELECT * FROM my.store", withtracing, with_warnings).unwrap();
// query with query values let values = queryvalues!(1 as i32, 1 as i64); session.querytw("INSERT INTO my.numbers (myint, mybigint) VALUES (?, ?)", values).unwrap();
// query with query values, tracing and warnings let withtracing = true; let withwarnings = true; let values = queryvalues!(1 as i32, 1 as i64); session.querytw("INSERT INTO my.numbers (myint, mybigint) VALUES (?, ?)", values, withtracing, withwarnings).unwrap();
// query with query params use cdrs::query::QueryParamsBuilder; use cdrs::consistency::Consistency;
let mut params = QueryParamsBuilder::new(); params = params.consistency(Consistency::Any); session.querywithparams("SELECT * FROM my.store", params.finalize()).unwrap();
// query with query params and tracing, warnings use cdrs::query::QueryParamsBuilder; use cdrs::consistency::Consistency;
let withtracing = true; let withwarnings = true;
let mut params = QueryParamsBuilder::new(); params = params.consistency(Consistency::Any);
session.querywithparamstw("SELECT * FROM my.store", params.finalize(), withtracing, with_warnings).unwrap(); ```
During preparing a query a server parses the query, saves parsing result into cache and returns back to a client an ID that could be further used for executing prepared statement with different parameters (such as values, consistency etc.). When a server executes prepared query it doesn't need to parse it so parsing step will be skipped.
CDRS Session implements cdrs::query::PrepareExecutor trait that provides few option for preparing query:
```rust let preparedquery = session.prepare("INSERT INTO my.store (myint, my_bigint) VALUES (?, ?)").unwrap();
// or with tracing and warnings let withtracing = true; let withwarnings = true;
let prepredquery = session.preparetw("INSERT INTO my.store (myint, mybigint) VALUES (?, ?)", withtracing, withwarnings).unwrap(); ```
When query is prepared on the server client gets prepared query id of type cdrs::query::PreparedQuery. Having such id it's possible to execute prepared query using session methods from cdrs::query::ExecExecutor:
```rust // execute prepared query without specifying any extra parameters or values session.exec(&preparedQuery).unwrap();
// execute prepared query with tracing and warning information let withtracing = true; let withwarnings = true;
session.exectw(&preparedQuery, withtracing, with_warnings).unwrap();
// execute prepared query with values let valueswithnames = queryvalues!{"mybigint" => bigint, "my_int" => int};
session.execwithvalues(&preparedQuery, valueswithnames).unwrap();
// execute prepared query with values with warnings and tracing information let withtracing = true; let withwarnings = true;
let valueswithnames = queryvalues!{"mybigint" => 1 as i64, "my_int" => 2 as i32};
session.execwithvaluestw(&preparedQuery, valueswithnames, withtracing, with_warnings).unwrap();
// execute prepared query with parameters use cdrs::query::QueryParamsBuilder; use cdrs::consistency::Consistency;
let mut params = QueryParamsBuilder::new(); params = params.consistency(Consistency::Any); session.execwithparameters(&preparedQuery, params.finalize()).unwrap();
// execute prepared query with parameters, tracing and warning information use cdrs::query::QueryParamsBuilder; use cdrs::consistency::Consistency;
let withtracing = true; let withwarnings = true; let mut params = QueryParamsBuilder::new(); params = params.consistency(Consistency::Any); session.execwithparameterstw(&preparedQuery, params.finalize(), withtracing, with_warnings).unwrap(); ```
CDRS Session supports batching few queries in a single request to Apache Cassandra via implementing cdrs::query::BatchExecutor trait:
```rust // batch two queries use cdrs::query::{BatchQueryBuilder, QueryBatch};
let mut queries = BatchQueryBuilder::new(); queries = queries.addqueryprepared(&preparedquery); queries = queries.addquery("INSERT INTO my.store (myint) VALUES (?)", queryvalues!(1 as i32)); session.batchwithparams(queries.finalyze());
// batch queries with tracing and warning information use cdrs::query::{BatchQueryBuilder, QueryBatch};
let withtracing = true; let withwarnings = true; let mut queries = BatchQueryBuilder::new(); queries = queries.addqueryprepared(&preparedquery); queries = queries.addquery("INSERT INTO my.store (myint) VALUES (?)", queryvalues!(1 as i32)); session.batchwithparamstw(queries.finalyze(), withtracing, with_warnings); ```
Accordingly to specification along with queries there could be provided something that is called values. Apache Cassandra server will use values instead of ? symbols from a query string.
There are two types of queries defined in the spec and supported by CDRS driver. Each of these two types could be easily constructed via provided query_values! macros.
rust
let simple_values = query_values!(1 as i32, 2 as i32);
rust
let values_with_names = query_values!{"my_bigint" => 1 as i64, "my_int" => 2 as i32};
Each type that implements Into<cdrs::types::value::Value> could be used as a value in query_values! macros. For primitive types please refer to following wrapper CDRS types that could be easily converted to Value. For custom types (in Cassandra terminology User Defined Types) IntoCDRSValue derive could be used:
```rust
struct Udt { pub number: i32, pub number16: i16, pub number8: N, }
// for nested structures it works as well
struct N { pub n: i16, } ```
Look into this link to find a full example how to use CDRS + into-cdrs-value-derive crate.
In ordert to query information from Cassandra DB and transform results to Rust types an structures each row in a query result should be transformed leveraging one of following traits provided by CDRS cdrs::types::{AsRustType, AsRust, IntoRustByName, ByName, IntoRustByIndex, ByIndex}.
AsRustType may be used in order to transform such complex structures as Cassandra lists, sets, tuples. The Cassandra value in this case could non-set and null values.
AsRust trait may be used for similar purposes as AsRustType but it assumes that Cassandra value is neither non-set nor null value. Otherwise it panics.
IntoRustByName trait may be used to access a value as a Rust structure/type by name. Such as in case of rows where each column has its own name, and maps. These values may be as well non-set and null.
ByName trait is the same as IntoRustByName but value should be neither non-set nor null. Otherwise it panics.
IntoRustByIndex is the same as IntoRustByName but values could be accessed via column index basing on their order provided in query. These values may be as well non-set and null.
ByIndex is the same as IntoRustByIndex but value can be neither non-set nor null. Otherwise it panics.
Relations between Cassandra and Rust types are described in type-mapping.md. For details see examples.