Execution profiles
Execution profiles allow a user to group various execution options into a ‘profile’. A user defines profiles when
initializing the cluster object. A user can then execute statements with different profiles by specifying the profile
name in calls to Session.execute*
.
Profile names should be strings or symbols. In this release, a profile encapsulates load-balancing policy, retry-policy, consistency-level, and timeout primitive options. Execution profiles are immutable once created.
If a user specifies simple options to Cassandra.cluster
, the options mentioned above are stored in a default
execution profile named :default
. This execution profile is used by default by Session.execute*
methods.
User-defined execution profiles fall back to the same system defaults that past versions of the driver fell back to
for unspecified options:
- load_balancing_policy:
LoadBalancing::Policies::TokenAware.new(LoadBalancing::Policies::DCAwareRoundRobin.new, true)
- retry-policy:
Retry::Policies::Default.new
- consistency:
:local_one
- timeout:
12
In particular, note that user-defined execution profiles do not fall back to options specified in a (possibly
user-defined) :default
profile.
If you declare execution profiles, it is illegal to also include the primitive options mentioned above:
puts "This is bad"
cluster = Cassandra.cluster(timeout: 7, execution_profiles: {
my_profile: Cassandra::Execution::Profile.new(...)
})
To change default execution profile attributes and also declare other execution profiles, you must explicitly declare the :default profile when initializing the cluster:
puts "This is legal"
cluster = Cassandra.cluster(execution_profiles: {
default: Cassandra::Execution::Profile.new(timeout: 7)
my_profile: Cassandra::Execution::Profile.new(...)
})
Unspecified attributes fall back to the system defaults mentioned above.
Finally, options specified to Session.execute*
methods override options specified in the desired execution profile.
Background
- Given
- a running cassandra cluster
Creating and inspecting execution profiles
- Given
- the following example:
require 'cassandra' profile_1 = Cassandra::Execution::Profile.new(load_balancing_policy: Cassandra::LoadBalancing::Policies::RoundRobin.new, retry_policy: Cassandra::Retry::Policies::DowngradingConsistency.new, consistency: :all, timeout: 32 ) cluster = Cassandra.cluster(execution_profiles: {'my_profile' => profile_1}) puts "There are #{cluster.execution_profiles.size} execution profiles in the cluster:" puts "" cluster.execution_profiles.each do |name, profile| puts "Name: #{name}" puts "Load_balancing_policy: #{profile.load_balancing_policy.class}" puts "Retry policy: #{profile.retry_policy.class}" puts "Consistency: #{profile.consistency}" puts "Timeout: #{profile.timeout}" puts "" end
- When
- it is executed
- Then
- its output should contain:
There are 2 execution profiles in the cluster: Name: my_profile Load_balancing_policy: Cassandra::LoadBalancing::Policies::RoundRobin Retry policy: Cassandra::Retry::Policies::DowngradingConsistency Consistency: all Timeout: 32 Name: default Load_balancing_policy: Cassandra::LoadBalancing::Policies::TokenAware Retry policy: Cassandra::Retry::Policies::Default Consistency: local_one Timeout: 12
Configure different load balancing policies with profiles
- Given
- the following example:
require 'cassandra' include Cassandra::LoadBalancing::Policies profiles = { p1: Cassandra::Execution::Profile.new(load_balancing_policy: WhiteList.new(['127.0.0.1'], RoundRobin.new)), p2: Cassandra::Execution::Profile.new(load_balancing_policy: WhiteList.new(['127.0.0.2'], RoundRobin.new)) } cluster = Cassandra.cluster(execution_profiles: profiles) session = cluster.connect puts "Running with default profile" # By default, the driver uses a token-aware, round-robin load balancing policy. ip_list = [] 3.times do rs = session.execute('select rpc_address from system.local') ip_list << rs.first['rpc_address'].to_s end puts ip_list.sort.join("\n") # p2 and p3 set up load-balancing policies that will match only one node. puts "Running with profile p1" 3.times do rs = session.execute('select rpc_address from system.local', execution_profile: :p1) puts rs.first['rpc_address'] end puts "Running with profile p2" 3.times do rs = session.execute('select rpc_address from system.local', execution_profile: :p2) puts rs.first['rpc_address'] end
- When
- it is executed
- Then
- its output should contain:
Running with default profile 127.0.0.1 127.0.0.2 127.0.0.3 Running with profile p1 127.0.0.1 127.0.0.1 127.0.0.1 Running with profile p2 127.0.0.2 127.0.0.2 127.0.0.2