Load balancing¶

Introduction¶

The driver uses a load balancing policy to determine which node(s) and shard(s) to contact when executing a query. Load balancing policies implement the LoadBalancingPolicy trait, which contains methods to generate a load balancing plan based on the query information and the state of the cluster.

Load balancing policies do not influence to which nodes connections are being opened. For a node connection blacklist configuration refer to scylla::transport::host_filter::HostFilter, which can be set session-wide using SessionBuilder::host_filter method.

In this chapter, “target” will refer to a pair <node, optional shard>.

Plan¶

When a query is prepared to be sent to the database, the load balancing policy constructs a load balancing plan. This plan is essentially a list of targets to which the driver will try to send the query. The first elements of the plan are the targets which are the best to contact (e.g. they might be replicas for the requested data or have the best latency).

Policy¶

The Scylla/Cassandra driver provides a default load balancing policy (see Default Policy for details), but you can also implement your own custom policies that better suit your specific use case. To use a custom policy, you simply need to implement the LoadBalancingPolicy trait and pass an instance of your custom policy to the used execution profile.

Our recommendation is to use Default Policy with token- awareness enabled and latency-awareness disabled.

Configuration¶

Load balancing policies can be configured via execution profiles. In the code sample provided, a new execution profile is created using ExecutionProfile::builder(), and the load balancing policy is set to the DefaultPolicy using .load_balancing_policy(policy).

The newly created execution profile is then converted to a handle using .into_handle(), and passed as the default execution profile to the SessionBuilder using .default_execution_profile_handle(handle).

use scylla::SessionBuilder;
use scylla::load_balancing::DefaultPolicy;
use scylla::transport::ExecutionProfile;
use scylla::transport::session::Session;
use std::sync::Arc;

let policy = Arc::new(DefaultPolicy::default());

let profile = ExecutionProfile::builder()
    .load_balancing_policy(policy)
    .build();
let handle = profile.into_handle();

let session: Session = SessionBuilder::new()
    .known_node(&uri)
    .default_execution_profile_handle(handle)
    .build()
    .await?;

In addition to being able to configure load balancing policies through execution profiles at the session level, the driver also allow for setting execution profile handles on a per-query basis. This means that for each query, a specific execution profile can be selected with a customized load balancing settings.

LoadBalancingPolicy trait¶