SessionBuilder - ScyllaDB Rust Driver

SessionBuilder provides a convenient way to configure and create new Session instances.

Overview

The builder pattern allows you to:

Configure connection parameters
Set compression and TLS options
Configure execution profiles and policies
Set timeouts and keepalive intervals
Customize session behavior

Creating a SessionBuilder

use scylla::client::session_builder::SessionBuilder;

let builder = SessionBuilder::new();

Building a Session

build

async fn

Finishes configuration and creates a Session.Returns: Result<Session, NewSessionError>Example:

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

Connection Configuration

known_node

Adds a known node with a hostname. If the port is not specified, 9042 is used as default.Parameters:

hostname: impl AsRef<str> - Hostname or IP address with optional port

Returns: SelfExample:

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

known_node_addr

Adds a known node with a SocketAddr.Parameters:

node_addr: SocketAddr - Socket address of the node

Returns: SelfExample:

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

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

known_nodes

Adds multiple known nodes with hostnames.Parameters:

hostnames: impl IntoIterator<Item = impl AsRef<str>> - Collection of hostnames

Returns: SelfExample:

let session = SessionBuilder::new()
    .known_nodes(["127.0.0.1:9042", "db1.example.com"])
    .build()
    .await?;

known_nodes_addr

Adds multiple known nodes with socket addresses.Parameters:

node_addrs: impl IntoIterator<Item = impl Borrow<SocketAddr>> - Collection of socket addresses

Returns: SelfExample:

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 = SessionBuilder::new()
    .known_nodes_addr([addr1, addr2])
    .build()
    .await?;

local_ip_address

Sets the local IP address all TCP sockets are bound to.By default, this is None, which is equivalent to INADDR_ANY for IPv4 or in6addr_any for IPv6.Parameters:

local_ip_address: Option<impl Into<IpAddr>> - Local IP address

Returns: SelfExample:

use std::net::Ipv4Addr;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .local_ip_address(Some(Ipv4Addr::new(192, 168, 0, 1)))
    .build()
    .await?;

connection_timeout

Changes connection timeout. The default is 5 seconds.Parameters:

duration: Duration - Connection timeout

Returns: SelfExample:

use std::time::Duration;

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

hostname_resolution_timeout

Changes DNS hostname resolution timeout. The default is 5 seconds. Using None disables the timeout.Parameters:

duration: Option<Duration> - Resolution timeout

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .hostname_resolution_timeout(Some(Duration::from_secs(10)))
    .build()
    .await?;

Authentication and Security

user

Sets username and password for plain text authentication.Parameters:

username: impl Into<String> - Username
passwd: impl Into<String> - Password

Returns: SelfExample:

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

authenticator_provider

Sets a custom authenticator provider.Parameters:

authenticator_provider: Arc<dyn AuthenticatorProvider> - Custom authenticator

Returns: SelfExample:

use std::sync::Arc;
use scylla::authentication::PlainTextAuthenticator;

let auth = Arc::new(PlainTextAuthenticator::new(
    "username".to_string(),
    "password".to_string()
));

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

tls_context

Provides TLS context for encrypted connections. If set to None, TLS is not used. Default is None.Parameters:

tls_context: Option<impl Into<TlsContext>> - TLS configuration

Returns: SelfExample (with OpenSSL):

use std::fs;
use std::path::PathBuf;
use openssl::ssl::{SslContextBuilder, SslVerifyMode, SslMethod, SslFiletype};

let certdir = fs::canonicalize(PathBuf::from("./certs/scylla.crt"))?;
let mut context_builder = SslContextBuilder::new(SslMethod::tls())?;
context_builder.set_certificate_file(certdir.as_path(), SslFiletype::PEM)?;
context_builder.set_verify(SslVerifyMode::NONE);

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

Compression and Protocol

compression

Sets preferred compression algorithm. The default is no compression. If not supported by the server, falls back to no compression.Parameters:

compression: Option<Compression> - Compression algorithm

Returns: SelfExample:

use scylla::client::Compression;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .compression(Some(Compression::Snappy))
    .build()
    .await?;

tcp_nodelay

Sets the TCP nodelay flag. The default is true.Parameters:

nodelay: bool - TCP nodelay setting

Returns: SelfExample:

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

tcp_keepalive_interval

Sets the TCP keepalive interval. The default is None (no TCP-layer keepalives).

Setting this to low values (below 1 second) is not recommended as it can negatively impact performance.

Parameters:

interval: Duration - Keepalive interval

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .tcp_keepalive_interval(Duration::from_secs(42))
    .build()
    .await?;

write_coalescing

Enables or disables write coalescing, which delays socket flushes to batch multiple writes. The default is true.Parameters:

enable: bool - Whether to enable write coalescing

Returns: SelfExample:

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

write_coalescing_delay

Controls the write coalescing delay (if enabled). Default is WriteCoalescingDelay::SmallNondeterministic.Parameters:

delay: WriteCoalescingDelay - Delay configuration

Returns: SelfExample:

use scylla::client::WriteCoalescingDelay;

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

Connection Pool

pool_size

Sets the per-node connection pool size. The default is one connection per shard (recommended for ScyllaDB).Parameters:

size: PoolSize - Pool size configuration

Returns: SelfExample:

use std::num::NonZeroUsize;
use scylla::client::PoolSize;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .pool_size(PoolSize::PerHost(NonZeroUsize::new(4).unwrap()))
    .build()
    .await?;

disallow_shard_aware_port

Prevents the driver from connecting to the shard-aware port (19042), even if the node supports it.

This should only be used as a last resort. The shard-aware port improves connection reliability. If you’re experiencing issues, fix the network configuration rather than disabling this feature.

Parameters:

disallow: bool - Whether to disallow shard-aware port

Returns: SelfExample:

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

shard_aware_local_port_range

Specifies the local port range used for shard-aware connections. Default is ShardAwarePortRange::EPHEMERAL_PORT_RANGE.Parameters:

port_range: ShardAwarePortRange - Port range configuration

Returns: SelfExample:

use scylla::routing::ShardAwarePortRange;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .shard_aware_local_port_range(ShardAwarePortRange::new(49200..=50000)?)
    .build()
    .await?;

Keepalive Configuration

keepalive_interval

Sets the interval for CQL-layer keepalive requests. The default is 30 seconds.

Setting this to low values (below 1 second) is not recommended as it can negatively impact performance.

Parameters:

interval: Duration - Keepalive interval

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .keepalive_interval(Duration::from_secs(42))
    .build()
    .await?;

keepalive_timeout

Sets the keepalive timeout. The default is 30 seconds.Parameters:

timeout: Duration - Keepalive timeout

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .keepalive_timeout(Duration::from_secs(42))
    .build()
    .await?;

Keyspace and Schema

use_keyspace

Sets the keyspace to use on all connections. Each connection will send USE <keyspace_name> before sending requests.Parameters:

keyspace_name: impl Into<String> - Keyspace name
case_sensitive: bool - Whether to quote the keyspace name

Returns: SelfExample:

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .use_keyspace("my_keyspace", false)
    .build()
    .await?;

keyspaces_to_fetch

Sets which keyspaces to fetch metadata for. Empty list (default) means all keyspaces.Parameters:

keyspaces: impl IntoIterator<Item = impl Into<String>> - Keyspace names

Returns: SelfExample:

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .keyspaces_to_fetch(["my_keyspace"])
    .build()
    .await?;

fetch_schema_metadata

Sets whether to fetch schema metadata. The default is true.Parameters:

fetch: bool - Whether to fetch schema metadata

Returns: SelfExample:

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

schema_agreement_interval

Sets how often the driver should ask if schema is in agreement. The default is 200 milliseconds.Parameters:

timeout: Duration - Check interval

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .schema_agreement_interval(Duration::from_secs(5))
    .build()
    .await?;

schema_agreement_timeout

Sets the timeout for waiting for schema agreement. The default is 60 seconds.Parameters:

timeout: Duration - Timeout duration

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .schema_agreement_timeout(Duration::from_secs(120))
    .build()
    .await?;

auto_await_schema_agreement

Controls automatic waiting for schema agreement after schema-altering statements. The default is enabled.Parameters:

enabled: bool - Whether to automatically await schema agreement

Returns: SelfExample:

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

refresh_metadata_on_auto_schema_agreement

Sets whether to refresh metadata after reaching schema agreement. The default is true.Parameters:

refresh_metadata: bool - Whether to refresh metadata

Returns: SelfExample:

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

metadata_request_serverside_timeout

Sets server-side timeout for metadata queries. The default is 2 seconds.Parameters:

timeout: Duration - Server-side timeout

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .metadata_request_serverside_timeout(Duration::from_secs(5))
    .build()
    .await?;

cluster_metadata_refresh_interval

Sets the interval for automatic cluster metadata refreshes. The default is 60 seconds.Parameters:

interval: Duration - Refresh interval

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .cluster_metadata_refresh_interval(Duration::from_secs(20))
    .build()
    .await?;

Policies and Profiles

default_execution_profile_handle

Sets the default execution profile for statements that don’t specify their own.Parameters:

profile_handle: ExecutionProfileHandle - Execution profile handle

Returns: SelfExample:

use std::time::Duration;
use scylla::statement::Consistency;
use scylla::client::execution_profile::ExecutionProfile;

let execution_profile = ExecutionProfile::builder()
    .consistency(Consistency::All)
    .request_timeout(Some(Duration::from_secs(2)))
    .build();

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

address_translator

Uses a custom address translator for peer addresses retrieved from the cluster.Parameters:

translator: Arc<dyn AddressTranslator> - Address translator

Returns: SelfExample:

use std::sync::Arc;
use std::collections::HashMap;
use std::net::SocketAddr;
use std::str::FromStr;

let mut translation_rules = HashMap::new();
let addr_before = SocketAddr::from_str("192.168.0.42:19042").unwrap();
let addr_after = SocketAddr::from_str("157.123.12.42:23203").unwrap();
translation_rules.insert(addr_before, addr_after);

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

host_filter

Sets the host filter, which decides whether to open connections to nodes.Parameters:

filter: Arc<dyn HostFilter> - Host filter

Returns: SelfExample:

use std::sync::Arc;
use scylla::policies::host_filter::DcHostFilter;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .host_filter(Arc::new(DcHostFilter::new("my-local-dc".to_string())))
    .build()
    .await?;

timestamp_generator

Sets a timestamp generator for client-side timestamp generation.Parameters:

timestamp_generator: Arc<dyn TimestampGenerator> - Timestamp generator

Returns: SelfExample:

use std::sync::Arc;
use scylla::policies::timestamp_generator::SimpleTimestampGenerator;

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

Tracing Configuration

tracing_info_fetch_attempts

Sets the number of attempts to fetch tracing info. The default is 10 attempts.Cassandra users may want to increase this value.Parameters:

attempts: NonZeroU32 - Number of attempts

Returns: SelfExample:

use std::num::NonZeroU32;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .tracing_info_fetch_attempts(NonZeroU32::new(10).unwrap())
    .build()
    .await?;

tracing_info_fetch_interval

Sets the delay between attempts to fetch tracing info. The default is 3 milliseconds.Cassandra users may want to increase this value.Parameters:

interval: Duration - Interval between attempts

Returns: SelfExample:

use std::time::Duration;

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .tracing_info_fetch_interval(Duration::from_millis(50))
    .build()
    .await?;

tracing_info_fetch_consistency

Sets the consistency level for fetching tracing info. The default is Consistency::One.Parameters:

consistency: Consistency - Consistency level

Returns: SelfExample:

use scylla::statement::Consistency;

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

Identity Configuration

custom_identity

Sets custom identity information sent to the server in the STARTUP message.Parameters:

identity: SelfIdentity<'static> - Custom identity

Returns: SelfExample:

use scylla::client::SelfIdentity;

let app_version = "2.1.3";

let session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .custom_identity(
        SelfIdentity::new()
            .with_custom_driver_version("0.13.0-custom")
            .with_application_name("my-app")
            .with_application_version(app_version)
    )
    .build()
    .await?;

Session - The session created by this builder
ExecutionProfile - Configuration for request execution
SessionConfig - Low-level session configuration

Client

Results

Errors

Statements

Serialization

Deserialization

Policies

Types

​Overview

​Creating a SessionBuilder

​Building a Session

​build

​Connection Configuration

​known_node

​known_node_addr

​known_nodes

​known_nodes_addr

​local_ip_address

​connection_timeout

​hostname_resolution_timeout

​Authentication and Security

​user

​authenticator_provider

​tls_context

​Compression and Protocol

​compression

​tcp_nodelay

​tcp_keepalive_interval

​write_coalescing

​write_coalescing_delay

​Connection Pool

​pool_size

​disallow_shard_aware_port

​shard_aware_local_port_range

​Keepalive Configuration

​keepalive_interval

​keepalive_timeout

​Keyspace and Schema

​use_keyspace

​keyspaces_to_fetch

​fetch_schema_metadata

​schema_agreement_interval

​schema_agreement_timeout

​auto_await_schema_agreement

​refresh_metadata_on_auto_schema_agreement

​metadata_request_serverside_timeout

​cluster_metadata_refresh_interval

​Policies and Profiles

​default_execution_profile_handle

​address_translator

​host_filter

​timestamp_generator

​Tracing Configuration

​tracing_info_fetch_attempts

​tracing_info_fetch_interval

​tracing_info_fetch_consistency

​Identity Configuration

​custom_identity

​Related Types

Build docs developers (and LLMs) love

Overview

Creating a SessionBuilder

Building a Session

build

Connection Configuration

known_node

known_node_addr

known_nodes

known_nodes_addr

local_ip_address

connection_timeout

hostname_resolution_timeout

Authentication and Security

user

authenticator_provider

tls_context

Compression and Protocol

compression

tcp_nodelay

tcp_keepalive_interval

write_coalescing

write_coalescing_delay

Connection Pool

pool_size

disallow_shard_aware_port

shard_aware_local_port_range

Keepalive Configuration

keepalive_interval

keepalive_timeout

Keyspace and Schema

use_keyspace

keyspaces_to_fetch

fetch_schema_metadata

schema_agreement_interval

schema_agreement_timeout

auto_await_schema_agreement

refresh_metadata_on_auto_schema_agreement

metadata_request_serverside_timeout

cluster_metadata_refresh_interval

Policies and Profiles

default_execution_profile_handle

address_translator

host_filter

timestamp_generator

Tracing Configuration

tracing_info_fetch_attempts

tracing_info_fetch_interval

tracing_info_fetch_consistency

Identity Configuration

custom_identity

Related Types