Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Client Settings

  • reference
    +
    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 or true — turn feature on

    • off or false — turn feature off

      Gets 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 or true — turn feature on

    • off or false — turn feature off

      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.

      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 or true — turn feature on

    • off or false — turn feature off

      If 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, below

    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, 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.