Cassandra (CQL) driver for Rust, using the DataStax C/C++ driver under the covers.

Overview

Build Status Current Version License

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 was originally a fork of https://github.com/tupshin/cassandra-rs but that is no longer maintained.

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

Documentation (crates.io).

Getting started

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

See the API documentation.

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.

Futures (version 0.15)

Since version 0.15, this crate uses std::future, allowing your code to use futures:0.3, async/await, etc.

Previous versions (up to 0.14) used futures:0.1. You can either remain on the 0.14 stream, update your code to use std::future, or use a compatibility shim (e.g., futures::compat).

Migrating from version 0.8

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

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.

Comments
  • Segfault when sending Row across threads

    Segfault when sending Row across threads

    I have a utility that executes a query and send each Row though a channel and implements paging. But I experienced some segfault:

    #0  core::str::run_utf8_validation () at src/libcore/str/mod.rs:1531
    #1  0x000055dd508053ac in core::str::from_utf8 () at src/libcore/str/mod.rs:342
    #2  0x000055dd506db27a in cassandra_cpp::cassandra::value::Value::get_str::{{closure}} ()
        at registry/src/github.com-1ecc6299db9ec823/cassandra-cpp-0.15.0/src/cassandra/value.rs:421
    #3  core::result::Result<T,E>::and_then (self=..., op=...)
        at /rustc/5e7af4669f80e5f682141f050193ab679afdb4b1/src/libcore/result.rs:727
    #4  cassandra_cpp::cassandra::value::Value::get_str (self=<optimized out>)
        at registry/src/github.com-1ecc6299db9ec823/cassandra-cpp-0.15.0/src/cassandra/value.rs:416
    #5  0x000055dd506db3cc in cassandra_cpp::cassandra::value::Value::get_string (self=0x0)
        at registry/src/github.com-1ecc6299db9ec823/cassandra-cpp-0.15.0/src/cassandra/value.rs:428
    #6  0x000055dd5050e758 in <cassandra_cpp::cassandra::row::Row as cassandra_cpp::cassandra::row::AsRustType<alloc::string::String>>::get_by_name (self=<optimized out>, name=...)
        at registry/src/github.com-1ecc6299db9ec823/cassandra-cpp-0.15.0/src/cassandra/row.rs:98
    #7  <cassandra_cpp::cassandra::row::Row as services::cql::extensions::AsRustTypeExt<T>>::get_by_name (self=<optimized out>, name=...)
        at services/src/cql/extensions.rs:45
    
    (gdb) select-frame 2
    (gdb) info locals
    slice = &[u8] {data_ptr: 0x0, length: 34}
    message_length = <optimized out>
    message_ptr = <optimized out>
    slice = <optimized out>
    err = <optimized out>
    val = <optimized out>
    

    It makes sense though, as iterating with cass_iterator_get_row invalidates the previous row. https://docs.datastax.com/en/developer/cpp-driver/1.0/api/struct.CassIterator/#function-cass_iterator_get_row

    https://github.com/Metaswitch/cassandra-rs/blob/09d5bbbd05c9525e3600be8a15d3dcb2c03239b8/src/cassandra/result.rs#L187-L192

    So, I suppose the Row type should not be Send or the iterator item should be a reference with a lifetime reflecting that, to prevent misuse like I did.

    bug help wanted awaiting info 
    opened by gwik 12
  • Workaround cpp driver string bind by name bug

    Workaround cpp driver string bind by name bug

    The cassandra cpp driver ignores the value length parameter and tries to find a null terminator in the passed string. Worked around using cass_statement_bind_bytes_by_name_n which is compatible and with string type and honor the value length parameter.

    opened by gwik 10
  • List data cannot be correctly displayed in the terminal

    List data cannot be correctly displayed in the terminal

    I tried using simple.rs to generate information and apply it. But when I generate a new field and specify the data type as list, the println! on the terminal is [<error>]. How do I display the correct list information on the terminal?

    bug 
    opened by pili2026 8
  • remove rustc-serialize from dependency tree

    remove rustc-serialize from dependency tree

    decimal by default pulls in various extra dependencies including the ancient rustc-serialize.

    I can see that the project would like to reintroduce decimal support https://github.com/Metaswitch/cassandra-rs/issues/122 so I didnt outright remove this unused dep. But maybe you would prefer me to just remove the dep so that decimal support can start from scratch and be free to choose a more up to date decimal crate?

    opened by rukai 7
  • The scope of the unsafe block can be appropriately reduced

    The scope of the unsafe block can be appropriately reduced

    In these functions you use the unsafe keyword for almost the entrie function body.

    We need to mark unsafe operations more precisely using unsafe keyword. Keeping unsafe blocks small can bring many benefits. For example, when mistakes happen, we can locate any errors related to memory safety within an unsafe block. This is the balance between Safe and Unsafe Rust. The separation is designed to make using Safe Rust as ergonomic as possible, but requires extra effort and care when writing Unsafe Rust.

    Hope this PR can help you. Best regards. References https://doc.rust-lang.org/nomicon/safe-unsafe-meaning.html https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html

    cleanup awaiting info 
    opened by peamaeq 6
  • fix build on aarm64

    fix build on aarm64

    currently this crate fails to compile on M1 / arm64 based machines due to this issue: https://github.com/remacs/remacs/issues/1393

    This PR fixes this by casting to libc::c_char rather than i8

    opened by stefanofranz 6
  • Batch execution no longer consumes the batch

    Batch execution no longer consumes the batch

    Session::execute_batch and Session::execute_batch_with_payloads now take &Batch rather than Batch.

    This was apparently an oversight in the original code; the parallel execute takes &Statement already.

    This is a breaking change, but it's a straightforward fix: just add & to your argument list.

    While we're here, fix a couple of warnings in test code related to printing panics, and remove travis-cargo (which was intermittently broken, and only used for coverage which we don't look at).

    Fixes #118

    opened by kw217 6
  • Fails to compile on macOS due to stdc++ library ref

    Fails to compile on macOS due to stdc++ library ref

    The following line in build.rs causes the problem: println!("cargo:rustc-flags=-l dylib=stdc++");

          ld: library not found for -lstdc++
          clang: error: linker command failed with exit code 1 (use -v to see invocation)
    

    Can you please disable it, at least for macOS builds? Thanks.

    bug help wanted 
    opened by a1ph 6
  • Does not compile on M1 architecture

    Does not compile on M1 architecture

    On a Macbook Air with the M1 chip, attempting to run cargo build on a simple Rust project that simply imports from cassandra_cpp and it fails due to a mismatched raw pointer type

    error[E0308]: mismatched types
      --> /Users/brandondail/.cargo/registry/src/github.com-1ecc6299db9ec823/cassandra-cpp-0.16.0/src/cassandra/schema/aggregate_meta.rs:52:22
       |
    52 |             raw2utf8(name, name_length).expect("must be utf8")
       |                      ^^^^ expected `u8`, found `i8`
       |
       = note: expected raw pointer `*const u8`
                  found raw pointer `*const i8`
    
    error[E0308]: mismatched types
      --> /Users/brandondail/.cargo/registry/src/github.com-1ecc6299db9ec823/cassandra-cpp-0.16.0/src/cassandra/schema/aggregate_meta.rs:62:22
       |
    62 |             raw2utf8(name, name_length).expect("must be utf8")
       |                      ^^^^ expected `u8`, found `i8`
       |
       = note: expected raw pointer `*const u8`
                  found raw pointer `*const i8`
    
    error[E0308]: mismatched types
       --> /Users/brandondail/.cargo/registry/src/github.com-1ecc6299db9ec823/cassandra-cpp-0.16.0/src/cassandra/schema/keyspace_meta.rs:150:22
        |
    150 |             raw2utf8(name, name_length).expect("must be utf8")
        |                      ^^^^ expected `u8`, found `i8`
        |
        = note: expected raw pointer `*const u8`
                   found raw pointer `*const i8`
    
    error: aborting due to 3 previous errors
    
    For more information about this error, try `rustc --explain E0308`.
    error: could not compile `cassandra-cpp`
    
    opened by aweary 5
  • feat: use parking_lot::Mutex

    feat: use parking_lot::Mutex

    parking_lot::Mutex is faster than std::sync::Mutex, so let's use it for the critical lock in CassFuture.

    This section of parking_lot's docs describes the difference: https://docs.rs/parking_lot/0.11.0/parking_lot/type.Mutex.html#differences-from-the-standard-library-mutex

    opened by jhgg 5
  • Convert to owned repository

    Convert to owned repository

    being forked doesn't allow code search on GitHub which is very convenient. is it possible to convert this fork to a first-class repository?

    also have you contacted the original author @tupshin about transfering the repo? that repo still shows up first in Google search from what I've seen

    cleanup 
    opened by nkconnor 5
  • UB on ResultIterator drop

    UB on ResultIterator drop

    If a ResultIterator is dropped while a Row it returned is still alive then we hit undefined behavior. I have seen this exposed as garbage data and segfaults. Specifically cass_iterator_free is the underlying API call, its documentation does not say not to call it while children are alive, so not sure if its our bug or an upstream bug.

    Specifically the driver version that exposed this issue to us was 0.16.2, the problem did not occur in 0.16.1. Its likely caused by one of these performance PRs:

    • https://github.com/datastax/cpp-driver/pull/505
    • https://github.com/datastax/cpp-driver/pull/510
    bug help wanted 
    opened by rukai 1
  • Build fail on windows

    Build fail on windows

    I have a project that uses this crate but it fails because the linker cannot find 'cryoto.lib' I have installed correctly every dependencies. any idea ?

    help wanted awaiting info 
    opened by Nagispace 3
  • The number of parameters and parameter types not exposed on PreparedStatement

    The number of parameters and parameter types not exposed on PreparedStatement

    I can't find a way to get the number of parameters on a PreparedStatement. Also there is no way to get the actual type of the parameter by name, because the parameter_data_type_by_name returns a ConstDataType which is defined in a private module and not exposed in the public API.

    Exposing such information would be useful in all the use-cases where the CQL string is provided by the user or built dynamically, so the types are not known at the time of writing the program and cannot be hardcoded.

    enhancement help wanted 
    opened by pkolaczk 1
  • Decimal type related functionality is missing

    Decimal type related functionality is missing

    I noticed the Decimal type related functionality of the driver is not exported in this crate. For example the bind_decimal method is commented out: https://github.com/Metaswitch/cassandra-rs/blob/master/src/cassandra/statement.rs#L682

    What is the reason behind that? Is there a workaround clients can use? What would need to be solved so this crate can expose that functionality?

    enhancement help wanted 
    opened by gszabo 1
  • [0.16] disallow preparing statements that look like `SELECT * FROM ...`

    [0.16] disallow preparing statements that look like `SELECT * FROM ...`

    A prepared statement that has a SELECT * in it is unsafe.

    More details here:

    • https://docs.datastax.com/en/developer/java-driver/3.0/manual/statements/prepared/#avoid-preparing-select-queries
    • https://issues.apache.org/jira/browse/CASSANDRA-10786

    This is a very very bad footgun, and can cause your driver to return incorrect rows when a table is altered.

    We should disallow these kind of queries from being prepared, as it can introduce soundness bugs in one's code.

    enhancement help wanted improved-api 
    opened by jhgg 3
  • [0.16] the ability to specify a default consistency level for statements / batches on either Cluster or Session

    [0.16] the ability to specify a default consistency level for statements / batches on either Cluster or Session

    Currently, the underlying C++ library defaults everything to a consistency level of ONE. (https://docs.datastax.com/en/developer/cpp-driver/2.15/api/struct.CassStatement/#function-cass_statement_set_consistency)

    It doesn't allow you to specify a more sensible default. Since we're wrapping this library, we could very easily support setting a consistency level on a Cluster or Session level, and propagating that change down into the execution handler.

    This has been a footgun for us, where we forget to set consistency level on a query to have it be doing ONE reads/writes instead of QUORUM read/writes. By providing an API that lets us set the default consistency level, this will let users of the library opt out of this nonsense default from the C++ driver, and not have to worry about setting the consistency level with each statement they execute. Perhaps even we should be opinionated here and say that the default consistency level should be LOCAL_QUORUM, because honestly, ONE is an insane default that can lead to data loss/inconsistency.

    Our code right now has a LOT of x.set_consistency(cassandra::Consistency::LOCAL_QUORUM)?; and it's pretty dangerous if forgotten.

    enhancement help wanted improved-api 
    opened by jhgg 1
Releases(1.2.0)
Owner
null
High-level async Cassandra client written in 100% Rust.

CDRS tokio CDRS is production-ready Apache Cassandra driver written in pure Rust. Focuses on providing high level of configurability to suit most use

Kamil Rojewski 73 Dec 26, 2022
📺 Netflix in Rust/ React-TS/ NextJS, Actix-Web, Async Apollo-GraphQl, Cassandra/ ScyllaDB, Async SQLx, Kafka, Redis, Tokio, Actix, Elasticsearch, Influxdb Iox, Tensorflow, AWS

Fullstack Movie Streaming Platform ?? Netflix in RUST/ NextJS, Actix-Web, Async Apollo-GraphQl, Cassandra/ ScyllaDB, Async SQLx, Spark, Kafka, Redis,

null 34 Apr 17, 2023
ORM for ScyllaDb and Cassandra

ScyllaDb/Cassandra Object-Relation Mapper Features This library contains several crates with the following features: Automatic map tables to Rust stru

null 36 Jan 1, 2023
Async Lightweight HTTP client using system native library if possible. (Currently under heavy development)

Async Lightweight HTTP Client (aka ALHC) What if we need async but also lightweight http client without using such a large library like reqwest, isahc

SteveXMH 7 Dec 15, 2022
This is a maintained rust project that exposes the cpp driver at cpp-driver in a somewhat-sane crate.

cassandra-rs This is a maintained rust project that exposes the cpp driver at https://github.com/datastax/cpp-driver/ in a somewhat-sane crate. For th

Tupshin Harper 51 Aug 20, 2020
An LSM storage engine designed to significantly reduce I/O amplification written in safe rust (Under active development)

VelarixDB is an LSM-based storage engine designed to significantly reduce IO amplification, resulting in better performance and durability for storage

gifted_dl 14 Sep 25, 2024
An ArangoDB driver for Rust

Rincon Rincon is an ArangoDB driver for Rust. It enables low level access to ArangoDB in a typesafe and Rust idiomatic manner. The name Rincon is deri

Innoave 35 Mar 21, 2021
The official MongoDB Rust Driver

MongoDB Rust Driver This repository contains the officially supported MongoDB Rust driver, a client side library that can be used to interact with Mon

mongodb 1.1k Dec 30, 2022
TDS 7.2+ (mssql / Microsoft SQL Server) async driver for rust

Tiberius A native Microsoft SQL Server (TDS) client for Rust. Supported SQL Server versions Version Support level Notes 2019 Tested on CI 2017 Tested

Prisma 189 Dec 25, 2022
Asyncronous Rust Mysql driver based on Tokio.

mysql-async Tokio based asynchronous MySql client library for rust programming language. Installation Library hosted on crates.io. [dependencies] mysq

Anatoly I 292 Dec 30, 2022
Native PostgreSQL driver for the Rust programming language

Rust-Postgres PostgreSQL support for Rust. postgres Documentation A native, synchronous PostgreSQL client. tokio-postgres Documentation A native, asyn

Steven Fackler 2.8k Jan 8, 2023
Official Skytable client driver for Rust

Skytable client Introduction This library is the official client for the free and open-source NoSQL database Skytable. First, go ahead and install Sky

Skytable 29 Nov 24, 2022
cogo rust coroutine database driver (Mysql,Postgres,Sqlite)

cdbc Coroutine Database driver Connectivity.based on cogo High concurrency,based on coroutine No Future<'q,Output=*>,No async fn, No .await , no Poll*

co-rs 10 Nov 13, 2022
This is superseded by the official MongoDB Rust Driver

This Repository is NOT a supported MongoDB product MongoDB Rust Driver Prototype NOTE: This driver is superseded by the official MongoDB Rust driver,

MongoDB, Inc. Labs 382 Nov 15, 2022
This is an Oracle database driver for Rust based on ODPI-C

Rust-oracle This is an Oracle database driver for Rust based on ODPI-C. Change Log See ChangeLog.md. Build-time Requirements C compiler. See Compile-t

Kubo Takehiro 138 Dec 23, 2022
Easy to use rust driver for arangoDB

arangors arangors is an intuitive rust client for ArangoDB, inspired by pyArango. arangors enables you to connect with ArangoDB server, access to data

fMeow 116 Jan 1, 2023
A Rust port of Pimoroni's uc8151 driver

uc8151-rs - a no-std Rust library for the UC8151(IL0373) e-ink display This is a Rust port of the Pimoroni UC8151 library. UC8151 is also sometimes re

null 6 Dec 15, 2022
ENC28J60 Linux network driver written in Rust.

enc28j60rs ENC28J60 Linux ethernet driver written in Rust. Tested with Raspberry Pi 4 Model B + Linux kernel 6.2.8 + Raspberry Pi OS AArch64. Kernel T

Ryo Munakata 11 May 1, 2023
MIPI Display Serial Interface unified driver

mipidsi This crate provides a generic display driver to connect to TFT displays that implement the MIPI DSI. Uses display_interface to talk to the har

Aleš Katona 31 Dec 20, 2022