Client Settings

The ClusterOptions class 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 parameter=value to the connection string, with the first parameter being followed by a ? and subsequent parameters being preceded by a &, e.g. couchbases://host?network=external&enable_mutation_tokens=false.

Most client settings are related to the ClusterOptions. 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.

Beyond the connection string, most settings are changed by calls to libcouchbase — refer to the API doc on lcb_cntl() and the settings list.

Creating a cluster with custom settings

# 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

Timeout settings are configured using an instance of ClusterTimeoutOptions.

Creating a new timeout config:

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. For example, ClusterTimeoutOptions is set via the ClusterOptions' constructor’s `timeout_options parameter, ClusterTracingOptions is set via the tracing_options parameter, and so on.

Configuration Options

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

Parameter: enable_mutation_tokens

(false|False|0)
(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 false if you do not require these features and wish to avoid the associated overhead.

Name: Network Resolution

Type: Connection String

Parameter: network

Values:

auto - the default (!)
default
external

The system property value should be one of auto, default, or external (lower case).

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 default if the client is running in the same network as the server, or external if the client is running in a different network.

Timeout Options Reference

Name: Key-Value Timeout: Type: ClusterTimeoutOptions

Parameter: kv_timeout: timedelta

Default: timedelta(seconds=2.5)

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: Type: ClusterTimeoutOptions

Parameter: views_timeout: timedelta

Default: timedelta(seconds=75)

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: Type: ClusterTimeoutOptions

Parameter: query_timeout: timedelta

Default: timedelta(seconds=75)

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.

Commonly Used Options

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.

Constrained Network Environments

Though wide area network (WAN) connections are not directly supported, some development and non-critical operations activities across a WAN are convenient. Most likely for connecting to Couchbase Capella, or Server running in your own cloud account, whilst developing from a laptop or other machine not located in the same data center. 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 related 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.