sqlx-scylladb

A database driver for ScyllaDB to be used with the Rust sqlx framework.

Wrap the scylla-rust-driver using the sqlx interface.

Why not use the scylla-rust-driver directly?

sqlx has excellent testing and migration features.

It is better to use these features rather than creating your own testing or migration functionality.

Usage

Quickstart

use sqlx_scylladb::ScyllaDBPoolOptions;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let pool = ScyllaDBPoolOptions::new()
        .max_connections(5)
        .connect("scylladb://localhost/test")
        .await?;

    sqlx::query("INSERT INTO users(id, name) VALUES(?, ?)")
      .bind(1)
      .bind("Alice")
      .execute(&pool)
      .await?;

    let (name,): (String,) = sqlx::query_as("SELECT name FROM users WHERE id = ?")
      .bind(1)
      .fetch_one(&pool)
      .await?;

    assert_eq!("Alice", name);

    Ok(())
}

Connection URL

In addition to DATABASE_URL, it also supports SCYLLADB_URL as an environment variable.

Example

scylladb://myname:mypassword@localhost:9042/my_keyspace?nodes=example.test,example2.test:9043&tcp_nodelay&tcp_keepalive=40&compression=lz4&replication_strategy=simple&replication_factor=2&page_size=10

Basic

Options

Features

Type bindings

• ASCII (&str, String, Box<str>, Cow<'_, str>, Rc<str>, Arc<str>)
• TEXT (&str, String, Box<str>, Cow<'_, str>, Rc<str>, Arc<str>)
• BOOLEAN (bool)
• TINYINT (i8)
• SMALLINT (i16)
• INT (i32)
• BIGINT (i64)
• FLOAT (f32)
• DOUBLE (f64)
• BLOB (Vec<u8>)
• UUID (uuid::Uuid)
• TIMEUUID (scylla::value::CqlTimeuuid)
• TIMESTAMP (scylla::value::CqlTimestamp, chrono::DateTime<Utc>, time::OffsetDateTime)
• DATE (scylla::value::CqlDate, chrono::NaiveDate, time::Date)
• TIME (scylla::value::CqlTime, chrono::NaiveTime, time::Time)
• INET (std::net::IpAddr)
• DECIMAL (bigdecimal::Decimal)
• Counter (deserialize only) (scylla::value::Counter)
• Duration
• Varint

• LIST<ASCII>, SET<ASCII> ([&str], Vec<String>)
• LIST<TEXT>, SET<TEXT> ([&str], Vec<String>)
• LIST<BOOLEAN>, SET<BOOLEAN> (Vec<bool>)
• LIST<TINYINT>, SET<TINYINT> (Vec<i8>)
• LIST<SMALLINT>, SET<SMALLINT> (Vec<i16>)
• LIST<INT>, SET<INT> (Vec<i32>)
• LIST<BIGINT>, SET<BIGINT> (Vec<i64>)
• LIST<FLOAT>, SET<FLOAT> (Vec<f32>)
• LIST<DOUBLE>, SET<DOUBLE> (Vec<f64>)
• LIST<BLOB>, SET<BLOB> (Vec<Vec<u8>>)
• LIST<UUID>, SET<UUID> (Vec<uuid::Uuid>)
• LIST<TIMEUUID>, SET<TIMEUUID> (Vec<scylla::value::CqlTimeuuid>)
• LIST<TIMESTAMP>, SET<TIMESTAMP> (Vec<scylla::value::CqlTimestamp>, Vec<chrono::DateTime<Utc>>, Vec<time::OffsetDateTime>)
• LIST<DATE>, SET<DATE> (Vec<scylla::value::CqlDate>, Vec<chrono::NaiveDate>, Vec<time::Date>)
• LIST<TIME>, SET<TIME> (Vec<scylla::value::CqlTime>, Vec<chrono::NaiveTime>, Vec<time::Time>)
• LIST<INET>, SET<INET> (Vec<std::net::IpAddr>)
• LIST<DECIMAL>, SET<DECIMAL> (Vec<bigdecimal::Decimal>)
• LIST<DURATION> (Vec<scylla::value::CqlDuration>)
• Varint

• MAP<ASCII, ASCII>, MAP<ASCII, TEXT>, MAP<TEXT, ASCII>, MAP<TEXT, TEXT> (HashMap<String, String>)
• MAP<ASCII, BOOLEAN>, MAP<TEXT, BOOLEAN> (HashMap<String, bool>)
• MAP<ASCII, TINYINT>, MAP<TEXT, TINYINT> (HashMap<String, i8>)
• MAP<ASCII, SMALLINT>, MAP<TEXT, SMALLINT> (HashMap<String, i16>)
• MAP<ASCII, INT>, MAP<TEXT, INT> (HashMap<String, i32>)
• MAP<ASCII, BIGINT>, MAP<TEXT, BIGINT> (HashMap<String, i64>)
• MAP<ASCII, FLOAT>, MAP<TEXT, FLOAT> (HashMap<String, f32>)
• MAP<ASCII, DOUBLE>, MAP<TEXT, DOUBLE> (HashMap<String, f64>)
• MAP<ASCII, UUID>, MAP<TEXT, UUID> (HashMap<String, uuid::Uuid>)
• MAP<ASCII, INET>, MAP<TEXT, INET> (HashMap<String, IpAddr>)

User defined type

• Definition using the derive macro. Use the new type idiom to implement user defined types for array types. (See the example for usage.)

Any type not supported by default

• You can add any type supported by scylla-rust-driver. (See the example for usage.)

Testing

• You can use #[sqlx::test] macro.

Migration

• Implemented sqlx::migrate::Migrator trait.
• Support migrations in #[sqlx::test] macro.
• You can use the command-line tool.
  • To install it, run cargo install --git https://github.com/masato-hi/sqlx-scylladb/tree/main/sqlx-scylladb-cli

TLS

• TLS (Enable with the openssl-010 or rustls-023 feature)

Transaction

Transaction are implemented using batch statement.

Please carefully read the documentation on batch operations in ScyllaDB before using them.

BATCH | ScyllaDB Docs

Performance

Compared to using the scylla-rust-driver, performance decreases by approximately 10%.

However, this equates to a reduction of about 50 milliseconds for 10,000 operations.

License

This project is licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)

MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any Contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.