Struct GenericSessionBuilder 

pub struct GenericSessionBuilder<Kind>
where
    Kind: SessionBuilderKind,
{
    pub config: SessionConfig,
    /* private fields */
}

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 GenericSessionBuilder<DefaultMode>

pub fn new() -> GenericSessionBuilder<DefaultMode>

Creates new SessionBuilder with default configuration

Default configuration

• Compression: None

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

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 known_node_addr( self, node_addr: SocketAddr, ) -> GenericSessionBuilder<DefaultMode>

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 IntoIterator<Item = impl AsRef<str>>, ) -> GenericSessionBuilder<DefaultMode>

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: impl IntoIterator<Item = impl Borrow<SocketAddr>>, ) -> GenericSessionBuilder<DefaultMode>

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 user( self, username: impl Into<String>, passwd: impl Into<String>, ) -> GenericSessionBuilder<DefaultMode>

Set username and password for plain text 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 authenticator_provider( self, authenticator_provider: Arc<dyn AuthenticatorProvider>, ) -> GenericSessionBuilder<DefaultMode>

Set custom authenticator provider to create an authenticator instance during a session creation.

Example

use bytes::Bytes;
use async_trait::async_trait;
use scylla::authentication::{AuthenticatorProvider, AuthenticatorSession, AuthError};

struct CustomAuthenticator;

#[async_trait]
impl AuthenticatorSession for CustomAuthenticator {
    async fn evaluate_challenge(&mut self, token: Option<&[u8]>) -> Result<Option<Vec<u8>>, AuthError> {
        Ok(None)
    }

    async fn success(&mut self, token: Option<&[u8]>) -> Result<(), AuthError> {
        Ok(())
    }
}

struct CustomAuthenticatorProvider;

#[async_trait]
impl AuthenticatorProvider for CustomAuthenticatorProvider {
    async fn start_authentication_session(&self, _authenticator_name: &str) -> Result<(Option<Vec<u8>>, Box<dyn AuthenticatorSession>), AuthError> {
        Ok((None, Box::new(CustomAuthenticator)))
    }
}

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

pub fn address_translator( self, translator: Arc<dyn AddressTranslator>, ) -> GenericSessionBuilder<DefaultMode>

Uses a custom address translator for peer addresses retrieved from the cluster. By default, no translation is performed.

Example

struct IdentityTranslator;

#[async_trait]
impl AddressTranslator for IdentityTranslator {
    async fn translate_address(
        &self,
        untranslated_peer: &UntranslatedPeer,
    ) -> Result<SocketAddr, TranslationError> {
        Ok(untranslated_peer.untranslated_address())
    }
}

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

Example

let mut translation_rules = HashMap::new();
let addr_before_translation = SocketAddr::from_str("192.168.0.42:19042").unwrap();
let addr_after_translation = SocketAddr::from_str("157.123.12.42:23203").unwrap();
translation_rules.insert(addr_before_translation, addr_after_translation);
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .address_translator(Arc::new(translation_rules))
    .build()
    .await?;

pub fn tls_context( self, tls_context: Option<impl Into<TlsContext>>, ) -> GenericSessionBuilder<DefaultMode>

TLS feature

Provide SessionBuilder with TlsContext that will be used to create a TLS connection to the database. If set to None TLS connection won’t be used.

Default is None.

Example

let certdir = fs::canonicalize(PathBuf::from("./examples/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: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .tls_context(Some(context_builder.build()))
    .build()
    .await?;

impl<K> GenericSessionBuilder<K>

where K: SessionBuilderKind,

pub fn local_ip_address( self, local_ip_address: Option<impl Into<IpAddr>>, ) -> GenericSessionBuilder<K>

Sets the local ip address all TCP sockets are bound to.

By default, this option is set to None, which is equivalent to:

• INADDR_ANY for IPv4 (Ipv4Addr::UNSPECIFIED)
• in6addr_any for IPv6 (Ipv6Addr::UNSPECIFIED)

Example

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

pub fn shard_aware_local_port_range( self, port_range: ShardAwarePortRange, ) -> GenericSessionBuilder<K>

Specifies the local port range used for shard-aware connections.

A possible use case is when you want to have multiple Session objects and do not want them to compete for the ports within the same range. It is then advised to assign mutually non-overlapping port ranges to each session object.

By default this option is set to ShardAwarePortRange::EPHEMERAL_PORT_RANGE.

For details, see ShardAwarePortRange documentation.

Example

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

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

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 schema_agreement_interval( self, timeout: Duration, ) -> GenericSessionBuilder<K>

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 default_execution_profile_handle( self, profile_handle: ExecutionProfileHandle, ) -> GenericSessionBuilder<K>

Set the default execution profile using its handle

Example

let execution_profile = ExecutionProfile::builder()
    .consistency(Consistency::All)
    .request_timeout(Some(Duration::from_secs(2)))
    .build();
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .default_execution_profile_handle(execution_profile.into_handle())
    .build()
    .await?;

pub fn tcp_nodelay(self, nodelay: bool) -> GenericSessionBuilder<K>

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 tcp_keepalive_interval( self, interval: Duration, ) -> GenericSessionBuilder<K>

Set the TCP keepalive interval. The default is None, which implies that no keepalive messages are sent on TCP layer when a connection is idle. Note: CQL-layer keepalives are configured separately, with Self::keepalive_interval.

Example

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

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

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 crate::client::session::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 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) -> GenericSessionBuilder<K>

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) -> GenericSessionBuilder<K>

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::client::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, ) -> GenericSessionBuilder<K>

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 timestamp_generator( self, timestamp_generator: Arc<dyn TimestampGenerator>, ) -> GenericSessionBuilder<K>

Set the timestamp generator that will generate timestamps on the client-side.

Example

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

pub fn keyspaces_to_fetch( self, keyspaces: impl IntoIterator<Item = impl Into<String>>, ) -> GenericSessionBuilder<K>

Set the keyspaces to be fetched, to retrieve their strategy, and schema metadata if enabled No keyspaces, the default value, means all the keyspaces will be fetched.

Example

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

pub fn fetch_schema_metadata(self, fetch: bool) -> GenericSessionBuilder<K>

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 metadata_request_serverside_timeout( self, timeout: Duration, ) -> GenericSessionBuilder<K>

Set the server-side timeout for metadata queries. The default is Some(Duration::from_secs(2)). It means that the all metadata queries will be set the 2 seconds timeout no matter what timeout is set as a cluster default. This prevents timeouts of schema queries when the schema is large and the default timeout is configured as tight.

Example

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

pub fn keepalive_interval(self, interval: Duration) -> GenericSessionBuilder<K>

Set the keepalive interval. The default is Some(Duration::from_secs(30)), which corresponds to keepalive CQL messages being sent every 30 seconds. Note: this configures CQL-layer keepalives. See also: Self::tcp_keepalive_interval.

Example

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

pub fn keepalive_timeout(self, timeout: Duration) -> GenericSessionBuilder<K>

Set the keepalive timeout. The default is Some(Duration::from_secs(30)). It means that the connection will be closed if time between sending a keepalive and receiving a response to any keepalive (not necessarily the same - it may be one sent later) exceeds 30 seconds.

Example

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

pub fn schema_agreement_timeout( self, timeout: Duration, ) -> GenericSessionBuilder<K>

Sets the timeout for waiting for schema agreement. By default, the timeout is 60 seconds.

Example

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

pub fn auto_await_schema_agreement( self, enabled: bool, ) -> GenericSessionBuilder<K>

Controls automatic waiting for schema agreement after a schema-altering statement is sent. By default, it is enabled.

Example

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

pub fn host_filter( self, filter: Arc<dyn HostFilter>, ) -> GenericSessionBuilder<K>

Sets the host filter. The host filter decides whether any connections should be opened to the node or not. The driver will also avoid those nodes when re-establishing the control connection.

See the host filter module for a list of pre-defined filters. It is also possible to provide a custom filter by implementing the HostFilter trait.

Example

// The session will only connect to nodes from "my-local-dc"
let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .host_filter(Arc::new(DcHostFilter::new("my-local-dc".to_string())))
    .build()
    .await?;

pub fn refresh_metadata_on_auto_schema_agreement( self, refresh_metadata: bool, ) -> GenericSessionBuilder<K>

Set the refresh metadata on schema agreement flag. The default is true.

Example

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

pub fn tracing_info_fetch_attempts( self, attempts: NonZero<u32>, ) -> GenericSessionBuilder<K>

Set the number of attempts to fetch TracingInfo in Session::get_tracing_info. The default is 5 attempts.

Tracing info might not be available immediately on queried node - that’s why the driver performs a few attempts with sleeps in between.

Cassandra users may want to increase this value - the default is good for Scylla, but Cassandra sometimes needs more time for the data to appear in tracing table.

Example

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

pub fn tracing_info_fetch_interval( self, interval: Duration, ) -> GenericSessionBuilder<K>

Set the delay between attempts to fetch TracingInfo in Session::get_tracing_info. The default is 3 milliseconds.

Tracing info might not be available immediately on queried node - that’s why the driver performs a few attempts with sleeps in between.

Cassandra users may want to increase this value - the default is good for Scylla, but Cassandra sometimes needs more time for the data to appear in tracing table.

Example

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

pub fn tracing_info_fetch_consistency( self, consistency: Consistency, ) -> GenericSessionBuilder<K>

Set the consistency level of fetching TracingInfo in Session::get_tracing_info. The default is Consistency::One.

Example

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

pub fn write_coalescing(self, enable: bool) -> GenericSessionBuilder<K>

If true, the driver will inject a delay controlled by SessionBuilder::write_coalescing_delay() before flushing data to the socket. This gives the driver an opportunity to collect more write requests and write them in a single syscall, increasing the efficiency.

However, this optimization may worsen latency if the rate of requests issued by the application is low, but otherwise the application is heavily loaded with other tasks on the same tokio executor. Please do performance measurements before committing to disabling this option.

This option is true by default.

Example

let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .write_coalescing(false) // Enabled by default
    .build()
    .await?;

pub fn write_coalescing_delay( self, delay: WriteCoalescingDelay, ) -> GenericSessionBuilder<K>

Controls the write coalescing delay (if enabled).

This option has no effect if SessionBuilder::write_coalescing() is set to false.

This option is WriteCoalescingDelay::SmallNondeterministic by default.

Example

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

pub fn cluster_metadata_refresh_interval( self, interval: Duration, ) -> GenericSessionBuilder<K>

Set the interval at which the driver refreshes the cluster metadata which contains information about the cluster topology as well as the cluster schema.

The default is 60 seconds.

In the given example, we have set the duration value to 20 seconds, which means that the metadata is refreshed every 20 seconds.

Example

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

pub fn custom_identity( self, identity: SelfIdentity<'static>, ) -> GenericSessionBuilder<K>

Set the custom identity of the driver/application/instance, to be sent as options in STARTUP message.

By default driver name and version are sent; application name and version and client id are not sent.

Example

    let (app_major, app_minor, app_patch) = (2, 1, 3);
    let app_version = format!("{app_major}.{app_minor}.{app_patch}");

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

Trait Implementations

impl<Kind> Clone for GenericSessionBuilder<Kind>

where Kind: Clone + SessionBuilderKind,

fn clone(&self) -> GenericSessionBuilder<Kind>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for GenericSessionBuilder<DefaultMode>

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

fn default() -> GenericSessionBuilder<DefaultMode>

Returns the “default value” for a type.