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, SCYLLADB_URL is supported as a source for retrieving environment variables during testing.

Example URL

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

Part	Required	Example	Explanation
schema	Required	scylladb	Only scylladb can be specified.
username	Optional	myname	Specify the username for user authentication.
password	Optional	mypassword	Specify the password for user authentication.
host	Required	localhost	Specify the hostname of the primary node.
port	Optional	9042	Specify the port number. The default is 9042.
path	Required	my_keyspace	Specify the keyspace.

Options

Name	Example	Explanation
nodes	example.test,example2.test:9043	Specify additional nodes separated by commas.
tcp_nodelay		When using tcp_nodelay, specify the key. No value is required.
tcp_keepalive	40	When using tcp_keepalive, specify the keepalive interval in seconds.
compression	lz4	Specify when compressing communication data. Supported values are lz4 or snappy.
replication_strategy	SimpleStrategy	Specifies the replication strategy when creating a keyspace. Supported values are simple, network_topology, SimpleStrategy, NetworkTopologyStrategy.
replication_factor	2	Specify the replication factor when creating a keyspace.
page_size	10	Specify the number of results to retrieve per page when receiving query results.
tls_rootcert	/etc/certs/ca.crt	Specify the path to the root CA certificate when establishing a TLS connection.
tls_cert	/etc/certs/client.crt	Specify the path to the client certificate when establishing a TLS connection
tls_key	/etc/certs/client.key	Specify the path to the client private key when establishing a TLS connection

Features

Basic type binding

• 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 or Set type binding

• 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

User defined type

• Manual implementation.
• Derive macro. Use the new type idiom to implement user defined types for array types. (See the example for usage.)

Testing

• #[sqlx::test] macro.

Migration

• Support migrations in #[sqlx::test] macro.
• sqlx::migrate::Migrator
• 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 is reduced by approximately 20%.

However, this equates to a decrease of about 100 milliseconds for 10,000 insertions.