Skip to main content

​
Overview

The ScyllaDB Rust Driver provides a convenient SessionBuilder API for creating and configuring database sessions. The builder pattern allows you to specify connection parameters, authentication, TLS, compression, and various other options before establishing a connection.

​
Basic Connection

The simplest way to connect to a ScyllaDB cluster is to provide at least one known node: 
use scylla::client::session_builder::SessionBuilder;
use scylla::client::session::Session;

let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .build()
    .await?;

​
Specifying Contact Points

The driver needs at least one initial contact point to discover the rest of the cluster. You can specify contact points in several ways:

​
Single Node (Hostname)

You can specify a single node using a hostname or IP address: 
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .build()
    .await?;
Or with a hostname: 
let session: Session = SessionBuilder::new()
    .known_node("db1.example.com")
    .build()
    .await?;

​
Single Node (IP Address)

You can also use SocketAddr directly: 
use std::net::{SocketAddr, IpAddr, Ipv4Addr};

let session: Session = SessionBuilder::new()
    .known_node_addr(SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 9042))
    .build()
    .await?;

​
Multiple Nodes (Hostnames)

For high availability, provide multiple contact points: 
let session: Session = SessionBuilder::new()
    .known_nodes(["127.0.0.1:9042", "db1.example.com", "db2.example.com"])
    .build()
    .await?;

​
Multiple Nodes (IP Addresses)

use std::net::{SocketAddr, IpAddr, Ipv4Addr};

let addr1 = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(172, 17, 0, 3)), 9042);
let addr2 = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(172, 17, 0, 4)), 9042);

let session: Session = SessionBuilder::new()
    .known_nodes_addr([addr1, addr2])
    .build()
    .await?;

​
Connection Configuration

​
Connection Timeout

Set the timeout for establishing a connection (default: 5 seconds): 
use std::time::Duration;

let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .connection_timeout(Duration::from_secs(30))
    .build()
    .await?;

​
Hostname Resolution Timeout

Configure the DNS hostname resolution timeout (default: 5 seconds): 
let session: Session = SessionBuilder::new()
    .known_node("db1.example.com")
    .hostname_resolution_timeout(Some(Duration::from_secs(10)))
    .build()
    .await?;
Set to None to disable the timeout.

​
TCP Configuration

​
TCP Nodelay

Control the TCP_NODELAY flag (default: true): 
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .tcp_nodelay(true)
    .build()
    .await?;

​
TCP Keepalive

Configure TCP keepalive interval (default: None): 
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .tcp_keepalive_interval(Duration::from_secs(42))
    .build()
    .await?;
Setting TCP keepalive to values below 1 second is not recommended as it can negatively impact performance.

​
Local IP Binding

Bind all TCP sockets to a specific local IP address: 
use std::net::Ipv4Addr;

let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .local_ip_address(Some(Ipv4Addr::new(192, 168, 0, 1)))
    .build()
    .await?;
By default, this is set to None, which uses INADDR_ANY for IPv4 or in6addr_any for IPv6.

​
Selecting a Keyspace

You can specify a keyspace to use on all connections: 
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .use_keyspace("my_keyspace", false)
    .build()
    .await?;
The second parameter controls whether the keyspace name is case-sensitive.

​
Pool Configuration

Set the per-node connection pool size: 
use std::num::NonZeroUsize;
use scylla::client::PoolSize;

// This session will establish 4 connections to each node.
// For ScyllaDB clusters, this number will be divided across shards
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .pool_size(PoolSize::PerHost(NonZeroUsize::new(4).unwrap()))
    .build()
    .await?;
The default is one connection per shard, which is the recommended setting for ScyllaDB.

​
Shard-Aware Port Configuration

This is a ScyllaDB-specific option that has no effect on Cassandra clusters.
Configure the local port range for shard-aware connections: 
use scylla::routing::ShardAwarePortRange;

let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .shard_aware_local_port_range(ShardAwarePortRange::new(49200..=50000)?)
    .build()
    .await?;
This is useful when you have multiple Session objects and want to prevent them from competing for ports.

​
Disabling Shard-Aware Port

You can disable the shard-aware port feature entirely: 
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .disallow_shard_aware_port(true)
    .build()
    .await?;
Disabling the shard-aware port should only be used as a last resort. The shard-aware port (19042 or 19142) makes establishing connections per shard more robust. Before disabling it, consider fixing any underlying network issues.

​
Complete Example

Here’s a comprehensive example combining multiple configuration options: 
use scylla::client::session_builder::SessionBuilder;
use scylla::client::session::Session;
use scylla::client::Compression;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let session: Session = SessionBuilder::new()
        .known_nodes(["127.0.0.1:9042", "127.0.0.2:9042"])
        .compression(Some(Compression::Snappy))
        .connection_timeout(Duration::from_secs(10))
        .tcp_nodelay(true)
        .use_keyspace("my_keyspace", false)
        .build()
        .await?;

    // Use the session...
    
    Ok(())
}

​
Next Steps

Authentication

Learn how to authenticate with username/password or custom authenticators

TLS/SSL

Configure secure TLS connections with OpenSSL or Rustls

Compression

Enable LZ4 or Snappy compression to reduce network bandwidth

Build docs developers (and LLMs) love

Get started for freeTalk to us