ScyllaDB Rust Driver

In a Client Routes setup, the driver uses a connection ID (assigned by your cloud provider) to map cluster nodes to specific proxy endpoints.

Workflow:

1. The driver queries system.client_routes on startup and during metadata refreshes to find the (address, port) pair for each node, filtered by your configured connection IDs.
2. The driver subscribes to CLIENT_ROUTES_CHANGE events to update routing information dynamically without requiring a full metadata refresh.

Limitations:

• No Mixed Clusters: All nodes in the cluster must be reachable through ClientRoutes. You cannot mix nodes reachable via ClientRoutes with nodes reachable directly.
• No TLS: TLS is not yet supported for Client Routes.
• Shard Awareness: Advanced shard awareness (targeting specific source ports) is disabled because proxy infrastructure typically does not preserve it. However, basic shard awareness remains functional, ensuring requests are still routed to the correct shards.

The DefaultRetryPolicy (implemented in scylla::policies::retry::DefaultRetryPolicy) is the driver's default mechanism for retrying queries when there is a high probability of success on a subsequent attempt. Its behavior is modeled after the DataStax Java Driver.

Key Rules

• LWT/Serial Consistency Safety: If the request consistency is a *_SERIAL level (Lightweight Transactions/Paxos), the policy returns DontRetry regardless of the error type or idempotence. This prevents unexpected semantics during the LWT protocol.
• Per-request Retry Budget: For certain error classes (Unavailable, ReadTimeout, and WriteTimeout), the policy uses a "at most once" guard. A flag is flipped after the first retry for that specific error class within a single request attempt. Subsequent identical errors for that request will result in DontRetry. These flags are reset via RetrySession::reset() between different requests.

Decision Matrix

The policy's decision to retry depends on the error type and whether the statement is marked as idempotent.

When working with nullable columns, you have two primary ways to handle values:

1. Option<T> (NULL): Sending None will insert a NULL value into the database. Note that in ScyllaDB/Cassandra, inserting a NULL is treated as a delete operation and generates a tombstone, which can impact performance.
2. Unset (Better Performance): To avoid generating tombstones, use MaybeUnset<T> or the Unset type. This tells the database to leave the column untouched rather than explicitly writing a NULL.

Use MaybeUnset::Unset or simply Unset for optimal performance during inserts.

use scylla::value::{MaybeUnset, Unset};

// 1. Sending a NULL (generates a tombstone)
let null_i32: Option<i32> = None;
session
    .query_unpaged("INSERT INTO ks.tab (a) VALUES(?)", (null_i32,))
    .await?;

// 2. Sending an Unset value (better performance, no tombstone)
let unset_i32: MaybeUnset<i32> = MaybeUnset::Unset;
session
    .query_unpaged("INSERT INTO ks.tab (a) VALUES(?)", (unset_i32,))
    .await?;

// Or simply using Unset directly
session
    .query_unpaged("INSERT INTO ks.tab (a) VALUES(?)", (Unset,))
    .await?;

The driver distinguishes between PreparedStatement and Statement (unprepared).

Prepared Statements

• Use case: Repeated operations.
• API: Use execute_* methods.
• Benefits: High performance (parsed once by DB), advanced load balancing (node/shard awareness), and metadata-based bind value verification.
• Best Practice: Prepare a statement once (e.g., store in a variable, static, or struct field) and execute it multiple times. Do not prepare the same statement before every execution.

Unprepared Statements

• Use case: One-shot operations.
• API: Use query_* methods.
• Drawbacks: Poor performance (parsed every time), primitive load balancing, and higher overhead because the driver may silently prepare them internally if they contain bind markers (?).

// Example pattern for prepared statements
// 1. Prepare once
let prepared = session.prepare("SELECT * FROM users WHERE id = ?").await?;

// 2. Execute multiple times
for id in user_ids {
    session.execute(&prepared, (id,)).await?;
}

In CQL, keyspace names can be case-insensitive (unquoted) or case-sensitive (quoted). When using Session::use_keyspace, the second argument controls this behavior:

• false: The name is treated as case-insensitive. For example, MY_KEYSPACE and my_keyspace will both resolve to the same keyspace if it was created without quotes.
• true: The name is wrapped in double quotes ("), making it case-sensitive.

If you have keyspaces with the same name but different casing (e.g., my_keyspace and MY_KEYSPACE), you must use the case_sensitive flag correctly to target the intended one.

// Targets 'my_keyspace' (case-insensitive)
session.use_keyspace("my_keyspace", false).await?;

// Targets 'my_keyspace' (case-sensitive, wrapped in quotes)
session.use_keyspace("my_keyspace", true).await?;

// Targets 'my_keyspace' (case-insensitive, even if provided in uppercase)
session.use_keyspace("MY_KEYSPACE", false).await?;

// Targets 'MY_KEYSPACE' (case-sensitive, wrapped in quotes)
session.use_keyspace("MY_KEYSPACE", true).await?;