ClusterOptionsclass enables you to configure Python SDK options for bootstrapping, timeouts, reliability, and performance.
Some settings for the Cluster/Bucket/Collection are currently only accessible via the Cluster connection string, but this may change in future. These parameters are set by appending
Most client settings are related to the
Like all other
OptionBlock s, this is akin to a Python
dict, but with named keyword arguments for discoverability.
Once it is passed in to the Cluster constructor or Cluster.connect, its settings are fixed.
# Create a cluster using the custom client settings. cluster = Cluster.connect(connectionString, ClusterOptions( PasswordAuthenticator(username, password), option1=xxx, option2=yyy...) # [Your code to interact with the cluster]
Timeout settings are configured using an instance of
timeout_options=ClusterTimeoutOptions(kv_timeout=timedelta(seconds=5), query_timeout=timedelta(seconds=10)) options=ClusterOptions(PasswordAuthenticator('username', 'password'), timeout_options=timeout_options) cluster.connect('couchbase://host',options)
The name of the OptionBlock for each section of configuration is analogous to the parameter name in ClusterOptions.
ClusterTimeoutOptions is set via the
ClusterOptions' constructor’s `timeout_options parameter,
ClusterTracingOptions is set via the
tracing_options parameter, and so on.
The following tables cover all possible configuration options and explain their usage and default values. The tables categorize the options into groups for bootstrapping, timeout, reliability, performance, and advanced options.
- Name: Mutation Tokens Enabled
Type: Connection String
(true|True|1)- gets the bootstrap node list from a DNS SRV record.
Mutation tokens allow enhanced durability requirements as well as advanced N1QL querying capabilities. Set this to
falseif you do not require these features and wish to avoid the associated overhead.
- Name: Network Resolution
Type: Connection String
auto- the default (!)
The system property value should be one of
Each node in the Couchbase Server cluster might have multiple addresses associated with it. For example, a node might have one address that should be used when connecting from inside the same virtual network environment where the server is running, and a second address for connecting from outside the server’s network environment.
By default the client will use a simple matching heuristic to determine which set of addresses to use (it will select the set of addresses that contains a seed node’s host and port).
If you wish to override the heuristic, you can set this value to
defaultif the client is running in the same network as the server, or
externalif the client is running in a different network.
- Name: Key-Value Timeout
The Key/Value default timeout is used on operations which are performed on a specific key if not overridden by a custom timeout. This includes all commands like get(), get_from_replica() and all mutation commands.
- Name: View Timeout
The View timeout is used on view operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows. Also, if there is a node failure during the request the internal cluster timeout is set to 60 seconds.
- Name: Query Timeout
The Query timeout is used on all N1QL query operations if not overridden by a custom timeout. Note that it is set to such a high timeout compared to key/value since it can affect hundreds or thousands of rows.
The defaults above have been carefully considered and in general it is not recommended to make changes without expert guidance or careful testing of the change. Some options may be commonly used together in certain envionments or to achieve certain effects.
Though wide area network (WAN) connections are not directly supported, some development and non-critical operations activities across a WAN are convenient. These settings are some you may want to consider adjusting:
Connect Timeout to 30s
Key-Value Timeout to 5s
Config Poll Interval to 10s
Circuit Breaker ErrorThresholdPercentage to 75
A program using the SDK can also use the
waitUntilReady() API call to handle all connection negotiations and realted errors at one place.
It may be useful to block in, for example, a basic console testing application for up to 30 seconds before proceeding in the program to perform data operations.
See the API reference for further details.