Struct scylla::transport::session_builder::SessionBuilder

pub struct SessionBuilder {
    pub config: SessionConfig,
}

SessionBuilder is used to create new Session instances

Example

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

Fields

config: SessionConfig

Implementations

impl SessionBuilder

pub fn new() -> Self

Creates new SessionBuilder with default configuration

Default configuration

• Compression: None

pub fn known_node(self, hostname: impl AsRef<str>) -> Self

Add a known node with a hostname

Examples

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

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

pub fn default_consistency(self, consistency: Consistency) -> Self

Specify a default consistency to be used for queries. It’s possible to override it by explicitly setting a consistency on the chosen query.

pub fn known_node_addr(self, node_addr: SocketAddr) -> Self

Add a known node with an IP address

Example

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

pub fn known_nodes(self, hostnames: &[impl AsRef<str>]) -> Self

Add a list of known nodes with hostnames

Example

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

pub fn known_nodes_addr(self, node_addrs: &[SocketAddr]) -> Self

Add a list of known nodes with IP addresses

Example

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?;

pub fn compression(self, compression: Option<Compression>) -> Self

Set preferred Compression algorithm. The default is no compression. If it is not supported by database server Session will fall back to no encryption.

Example

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

pub fn tcp_nodelay(self, nodelay: bool) -> Self

Set the nodelay TCP flag. The default is true.

Example

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

pub fn use_keyspace(
    self,
    keyspace_name: impl Into<String>,
    case_sensitive: bool
) -> Self

Set keyspace to be used on all connections.
Each connection will send "USE <keyspace_name>" before sending any requests.
This can be later changed with Session::use_keyspace

Example

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

pub fn user(
    self,
    username: impl Into<String>,
    passwd: impl Into<String>
) -> Self

Set username and password for authentication.
If the database server will require authentication

Example

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

pub fn schema_agreement_interval(self, timeout: Duration) -> Self

Set the delay for schema agreement check. How often driver should ask if schema is in agreement The default is 200 milliseconds.

Example

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

pub fn load_balancing(self, policy: Arc<dyn LoadBalancingPolicy>) -> Self

Set the load balancing policy The default is Token-aware Round-robin.

Example

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

pub fn speculative_execution(
    self,
    policy: Arc<dyn SpeculativeExecutionPolicy>
) -> Self

Set the speculative execution policy The default is None

Example

use std::{sync::Arc, time::Duration};
use scylla::{
    Session,
    SessionBuilder,
    transport::speculative_execution::SimpleSpeculativeExecutionPolicy
};

let policy = SimpleSpeculativeExecutionPolicy {
    max_retry_count: 3,
    retry_interval: Duration::from_millis(100),
};

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

pub fn retry_policy(
    self,
    retry_policy: Box<dyn RetryPolicy + Send + Sync>
) -> Self

Sets the RetryPolicy to use by default on queries The default is DefaultRetryPolicy It is possible to implement a custom retry policy by implementing the trait RetryPolicy

Example

use scylla::transport::retry_policy::DefaultRetryPolicy;
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .retry_policy(Box::new(DefaultRetryPolicy::new()))
    .build()
    .await?;

pub async fn build(&self) -> Result<Session, NewSessionError>

Builds the Session after setting all the options

Example

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

pub fn connection_timeout(self, duration: Duration) -> Self

Changes connection timeout The default is 5 seconds. If it’s higher than underlying os’s default connection timeout it won’t effect.

Example

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

pub fn pool_size(self, size: PoolSize) -> Self

Sets the per-node connection pool size. The default is one connection per shard, which is the recommended setting for Scylla.

Example

use std::num::NonZeroUsize;
use scylla::transport::session::PoolSize;

// This session will establish 4 connections to each node.
// For Scylla 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?;

pub fn disallow_shard_aware_port(self, disallow: bool) -> Self

If true, prevents the driver from connecting to the shard-aware port, even if the node supports it.

This is a Scylla-specific option. It has no effect on Cassandra clusters.

By default, connecting to the shard-aware port is allowed and, in general, this setting should not be changed. The shard-aware port (19042 or 19142) makes the process of establishing connection per shard more robust compared to the regular transport port (9042 or 9142). With the shard-aware port, the driver is able to choose which shard will be assigned to the connection.

In order to be able to use the shard-aware port effectively, the port needs to be reachable and not behind a NAT which changes source ports (the driver uses the source port to tell Scylla which shard to assign). However, the driver is designed to behave in a robust way if those conditions are not met - if the driver fails to connect to the port or gets a connection to the wrong shard, it will re-attempt the connection to the regular transport port.

The only cost of misconfigured shard-aware port should be a slightly longer reconnection time. If it is unacceptable to you or suspect that it causes you some other problems, you can use this option to disable the shard-aware port feature completely. However, you should use it as a last resort. Before you do that, we strongly recommend that you consider fixing the network issues.

Example

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

pub fn fetch_schema_metadata(self, fetch: bool) -> Self

Set the fetch schema metadata flag. The default is true.

Example

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

pub fn keepalive_interval(self, interval: Duration) -> Self

Set the keepalive interval. The default is None, it corresponds to no keepalive messages being send.

Example

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

Trait Implementations

impl Default for SessionBuilder

Creates a SessionBuilder with default configuration, same as SessionBuilder::new

fn default() -> Self

Returns the “default value” for a type.