Client Settings
Client settings
Refer to the API doc on lcb_cntl()
and the settings list.
I/O Options
This section provides basic settings that will come in handy while configuring network related operations.
- Name: DNS SRV
-
Connection String Option:
dnssrv
Default:
true
(when only one node specified in server list) Possible values:-
on
ortrue
— turn feature on -
off
orfalse
— turn feature offGets the bootstrap node list from a DNS SRV record. See the Connection Management section for more information on how to use it properly.
This setting is only available on the connection string. std::string connection_string { "couchbase://localhost?dnssrv=off" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size());
-
- Name: Mutation Tokens Enabled
-
Connection String Options:
enable_mutation_tokens
Enumeration Symbol:LCB_CNTL_ENABLE_MUTATION_TOKENS
Default:
true
Possible values:
-
on
ortrue
— turn feature on -
off
orfalse
— turn feature offMutation 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.std::string connection_string { "couchbase://localhost?enable_mutation_tokens=off" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "enable_mutation_tokens", "off"); int enable = 1; lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_ENABLE_MUTATION_TOKENS, &enable); lcb_cntl_set32(instance, LCB_CNTL_ENABLE_MUTATION_TOKENS, enable);
-
- Name: Socket Keepalive
-
Connection String Option:
tcp_keepalive
Enumeration Symbol:LCB_CNTL_TCP_KEEPALIVE
Default:
true
Possible values:
-
on
ortrue
— turn feature on -
off
orfalse
— turn feature offIf enabled, the client periodically sends a TCP keepalive to the server to prevent firewalls and other network equipment from dropping idle TCP connections.
std::string connection_string { "couchbase://localhost?tcp_keepalive=on" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "tcp_keepalive", "on"); int enable = 1; lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_TCP_KEEPALIVE, &enable); lcb_cntl_set32(instance, LCB_CNTL_TCP_KEEPALIVE, enable);
-
- Name: Config Poll Interval
-
Cluster Option:
config_poll_interval
Enumeration Symbol:LCB_CNTL_CONFIG_POLL_INTERVAL
Default:
2.5
(2500 milliseconds)The interval at which the client fetches cluster topology information in order to proactively detect changes.
// all examples below set configuration poll to 4.5 seconds std::string connection_string { "couchbase://localhost?config_poll_interval=4.5" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "config_poll_interval", "4.5"); auto timeout_in_seconds = std::chrono::milliseconds(4500); auto timeout_in_microseconds = std::chrono::duration_cast<std::chrono::microseconds>(timeout_in_seconds); std::uint32_t timeout = std::static_cast<std::uint32_t>(timeout_in_microseconds.count()); lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_TCP_KEEPALIVE, &timeout); std::uint32_t timeout = 4500000; // in microseconds lcb_cntl_set32(instance, LCB_CNTL_TCP_KEEPALIVE, timeout);
Timeout Options
The default timeout values are suitable for most environments, and should be adjusted only after profiling the expected latencies in your deployment environment. If you get a timeout exception, it may be a symptom of another issue; increasing the timeout duration is sometimes not the best long-term solution.
Most timeouts can be overridden on a per-operation basis (for example, by passing a custom options block to a "get" or "query" method). The values set here are used as the defaults when no per-operation timeout is specified.
// 5 seconds 200 milliseconds
std::string connection_string { "couchbase://localhost?query_timeout=5.2" };
Timeout Options Reference
- Name: Key-Value Timeout
-
Connection String Option:
operation_timeout
Enumeration Symbol:LCB_CNTL_OP_TIMEOUT
Default:
2.5
(2500 milliseconds), but see TIP, belowThe 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
,lookup_in
, and all mutation commands, but does not include operations that are performed with enhanced durability requirements.Durable Write operations have their own timeout setting, persistence_timeout_floor
, see below.// all examples below set operation timeout to 4.5 seconds std::string connection_string { "couchbase://localhost?operation_timeout=4.5" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "operation_timeout", "4.5"); auto timeout_in_seconds = std::chrono::milliseconds(4500); auto timeout_in_microseconds = std::chrono::duration_cast<std::chrono::microseconds>(timeout_in_seconds); std::uint32_t timeout = std::static_cast<std::uint32_t>(timeout_in_microseconds.count()); lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_OP_TIMEOUT, &timeout); std::uint32_t timeout = 4500000; // in microseconds lcb_cntl_set32(instance, LCB_CNTL_OP_TIMEOUT, timeout); // also could be set per operation, for instance here we set timeout for GET command lcb_cmdget_timeout(cmd, timeout);
- Name: Key-Value Durable Operation Timeout
-
Connection String Option:
persistence_timeout_floor
Enumeration Symbol:LCB_CNTL_PERSISTENCE_TIMEOUT_FLOOR
Default:
1.5
(1500 milliseconds)Generally the library derives persistence timeout from operation timeout, and the application should not care about this. This setting controls the minimum value for Key-Value operation with requested durability level. It is guaranteed that the library will not use timeout below this floor value.
The persistence_timeout_floor
property is not part of the stable API and may change or be removed at any time.// all examples below set operation timeout to 4.5 seconds std::string connection_string { "couchbase://localhost?persistence_timeout_floor=4.5" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "persistence_timeout_floor", "4.5"); auto timeout_in_seconds = std::chrono::milliseconds(4500); auto timeout_in_microseconds = std::chrono::duration_cast<std::chrono::microseconds>(timeout_in_seconds); std::uint32_t timeout = std::static_cast<std::uint32_t>(timeout_in_microseconds.count()); lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_PERSISTENCE_TIMEOUT_FLOOR, &timeout); std::uint32_t timeout = 4500000; // in microseconds lcb_cntl_set32(instance, LCB_CNTL_PERSISTENCE_TIMEOUT_FLOOR, timeout);
- Name: View Timeout
-
Connection String Option:
views_timeout
Enumeration Symbol:LCB_CNTL_VIEW_TIMEOUT
Default:
75.0
(75000 milliseconds)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.
// all examples below set operation timeout to 4.5 seconds std::string connection_string { "couchbase://localhost?views_timeout=4.5" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "views_timeout", "4.5"); auto timeout_in_seconds = std::chrono::milliseconds(4500); auto timeout_in_microseconds = std::chrono::duration_cast<std::chrono::microseconds>(timeout_in_seconds); std::uint32_t timeout = std::static_cast<std::uint32_t>(timeout_in_microseconds.count()); lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_VIEW_TIMEOUT, &timeout); std::uint32_t timeout = 4500000; // in microseconds lcb_cntl_set32(instance, LCB_CNTL_VIEW_TIMEOUT, timeout); // also could be set per operation, for instance here we set timeout for VIEW command lcb_cmdview_timeout(cmd, timeout);
- Name: Query Timeout
-
Connection String Option:
query_timeout
Enumeration Symbol:LCB_CNTL_QUERY_TIMEOUT
Default:
75.0
(75000 milliseconds)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.
// all examples below set operation timeout to 4.5 seconds std::string connection_string { "couchbase://localhost?query_timeout=4.5" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "query_timeout", "4.5"); auto timeout_in_seconds = std::chrono::milliseconds(4500); auto timeout_in_microseconds = std::chrono::duration_cast<std::chrono::microseconds>(timeout_in_seconds); std::uint32_t timeout = std::static_cast<std::uint32_t>(timeout_in_microseconds.count()); lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_QUERY_TIMEOUT, &timeout); std::uint32_t timeout = 4500000; // in microseconds lcb_cntl_set32(instance, LCB_CNTL_QUERY_TIMEOUT, timeout); // also could be set per operation, for instance here we set timeout for VIEW command lcb_cmdquery_timeout(cmd, timeout);
- Name: Analytics Timeout
-
Connection String Option:
analytics_timeout
Enumeration Symbol:LCB_CNTL_ANALYTICS_TIMEOUT
Default:
75.0
(75000 milliseconds)The Analytics timeout is used on all Analytics 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.
// all examples below set operation timeout to 4.5 seconds std::string connection_string { "couchbase://localhost?analytics_timeout=4.5" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "analytics_timeout", "4.5"); auto timeout_in_seconds = std::chrono::milliseconds(4500); auto timeout_in_microseconds = std::chrono::duration_cast<std::chrono::microseconds>(timeout_in_seconds); std::uint32_t timeout = std::static_cast<std::uint32_t>(timeout_in_microseconds.count()); lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_ANALYTICS_TIMEOUT, &timeout); std::uint32_t timeout = 4500000; // in microseconds lcb_cntl_set32(instance, LCB_CNTL_ANALYTICS_TIMEOUT, timeout); // also could be set per operation, for instance here we set timeout for VIEW command lcb_cmdanalytics_timeout(cmd, timeout);
- Name: Search Timeout
-
Connection String Option:
search_timeout
Enumeration Symbol:LCB_CNTL_SEARCH_TIMEOUT
Default:
75.0
(75000 milliseconds)The Search timeout is used on all FTS 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.
// all examples below set operation timeout to 4.5 seconds std::string connection_string { "couchbase://localhost?search_timeout=4.5" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "search_timeout", "4.5"); auto timeout_in_seconds = std::chrono::milliseconds(4500); auto timeout_in_microseconds = std::chrono::duration_cast<std::chrono::microseconds>(timeout_in_seconds); std::uint32_t timeout = std::static_cast<std::uint32_t>(timeout_in_microseconds.count()); lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_SEARCH_TIMEOUT, &timeout); std::uint32_t timeout = 4500000; // in microseconds lcb_cntl_set32(instance, LCB_CNTL_SEARCH_TIMEOUT, timeout); // also could be set per operation, for instance here we set timeout for VIEW command lcb_cmdsearch_timeout(cmd, timeout);
- Name: Management Timeout
-
Connection String Option:
http_timeout
Enumeration Symbol:LCB_CNTL_HTTP_TIMEOUT
Default:
75.0
(75000 milliseconds)The default is quite high because some operations (such as flushing a bucket, for example) might take a long time.
// all examples below set operation timeout to 4.5 seconds std::string connection_string { "couchbase://localhost?http_timeout=4.5" }; lcb_createopts_connstr(create_options, connection_string.c_str(), connection_string.size()); lcb_cntl_string(instance, "http_timeout", "4.5"); auto timeout_in_seconds = std::chrono::milliseconds(4500); auto timeout_in_microseconds = std::chrono::duration_cast<std::chrono::microseconds>(timeout_in_seconds); std::uint32_t timeout = std::static_cast<std::uint32_t>(timeout_in_microseconds.count()); lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_HTTP_TIMEOUT, &timeout); std::uint32_t timeout = 4500000; // in microseconds lcb_cntl_set32(instance, LCB_CNTL_HTTP_TIMEOUT, timeout); // also could be set per operation, for instance here we set timeout for VIEW command lcb_cmdhttp_timeout(cmd, timeout);
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. 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.