Client Settings Using the PHP SDK with Couchbase Server

The PHP SDK may be configured using the connection string when instantiating a CouchbaseCluster object.

Below follows the C settings section:

Configuring Overview

In addition to the initial settings passed to the client via the connection string, you can adjust properties of the client to better function in your specific environment. The lcb_cntl() function is used to retrieve or modify library settings on a per-instance basis. The general syntax for retrieving a setting is:

lcb_U32 curval;
lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_OPTIMEOUT, &curval);

And the general syntax for modifying a setting is:

lcb_U32 newval = 4000000; // Set to 4 seconds
lcb_cntl(instance, LCB_CNTL_SET, LCB_CNTL_OPTIMEOUT, &newval);

By design, this API works similarly to the setsockopt(), getsockopt(), and ioctl() interfaces. It is passed an instance to operate on, a mode constant (what sort of access to perform), a setting constant (which setting to access) and finally the value, which is either written to or read from depending on whether the mode indicates a modification or a retrieval, respectively.

The lcb_cntl() function returns an error code of LCB_SUCCESS if successful, LCB_NOT_SUPPORTED (or LCB_ECTL_UNKNOWN) if the setting is not known. Always check the return code and be prepared to take action if the specific operation is not supported in the specific version of the library.

The constants are well defined and do not change between versions. Thus, if you intend to modify an optional setting and also intend to compile against a possibly older version of the library where the constant is not defined, you can use the raw numeric literal (for example, 0x1E) rather than the symbolic name.

The most recent settings are always found in the <libcouchbase/cntl.h> header file.

Some options are also available in a simplified string format, in which the option names and values are strings. These may be set with the lcb_cntl_string() function or directly embedded into the connection string.

Most of the information in this section applies to any component that uses the C SDK, assuming they accept a connection string as the way to connect to the cluster. Such is the case with the command-line tools or higher level SDKs that build on the C SDK. Some specific options are C-only and are marked as such.

This section provides connection string options as well as those options that can be passed to lcb_cntl_string() and only documents options that have a string alias. Other options are available directly via the lcb_cntl() function. For more details about those options, see the header file and API documentation for the lcb_cntl() function.

The options listed in the following table can be passed to the connection string by using the form couchbase://hosts/bucket?option1=value1&option2=value2 or via the lcb_cntl_string() function. Some options (where specified) are valid only in the connection string. Here’s an example that shows how to use the lcb_cntl_string() function:

lcb_cntl_string(instance, "option", "value")

Connection strings are only available in version 2.4.0 and later. Some options were introduced in a later version (indicated next to the option). Almost all of the options have programmatic lcb_cntl() equivalents, which can be used instead. Some settings are only available via lcb_cntl() and are thus not listed here.

Selected Configuration Options

This list does not contain all possible settings, only the most common ones. See <libcouchbase/cntl.h> for the full list of publically available settings.

Timeout values should be specified using the decimal point, and are interpreted as seconds. To specify fractional second intervals, just use the fractional part of the value. For example, operation_timeout=2.75 will set the timeout to 2750 milliseconds.

Boolean values can be specified using 0 for false, and 1 for true. The strings true and false are also recognized. If this appears as a value type for lcb_cntl() then it is a pointer to an int, where a value of 0 indicates false, and a non-zero value indicates true.

Microsecond values. These values are only applicable for lcb_cntl() and only usable directly with the C library. They indicate the value as a time interval specified in microseconds. The value itself should be a lcb_U32, a pointer to which is passed into lcb_cntl() as its last argument.

These settings may be combined in the connection string in a similar manner as query parameters in a URI; for example, you may use:

couchbase://cb1,cb2,cb3/bucket?operation_timeout=4&http_poolsize=0&fetch_mutation_tokens=1

To modify the operation timeout, disable HTTP socket pooling, and enable mutation tokens.
Table 1. Options reference
Option Name (for use in connection string or lcb_cntl_string()) Macro/Constant name (for direct use with the C SDK’s lcb_cntl()). Description

operation_timeout (Timeout)

LCB_CNTL_OP_TIMEOUT (microseconds)

The operation timeout is the maximum amount of time the library will wait for an operation to receive a response before invoking its callback with a failure status.

An operation might time-out if:

  • A server is taking too long to respond

  • An updated cluster configuration has not been promptly received

When an operation times out, it will fail with the LCB_ETIMEDOUT error code.

Connection String Example
operation_timeout=2.5

config_total_timeout (Timeout)

LCB_CNTL_CONFIGURATION_TIMEOUT (microseconds)

This is how long the client will wait to obtain the initial configuration. This affects the maximum amount of time that the call to lcb_wait() will take after having called lcb_connect(). If lcb_get_bootstrap_status is returning with LCB_ETIMEDOUT and you are running on a slow network, modifying this setting may increase the chances of success.

See also config_node_timeout.

Connection String Example
config_total_timeout=5

config_node_timeout (Timeout)

LCB_CNTL_CONFIG_NODE_TIMEOUT (microseconds)

The per-node configuration timeout sets the amount of time to wait for each node within the bootstrap/configuration process. This interval is a subset of the config_total_timeout option mentioned above and is intended to ensure that the bootstrap process does not wait too long for a given node.

Nodes that are physically offline may never respond, and it may take a long time until they are detected as being offline. See CCBC-261 and CCBC-313 for more reasons.

Connection String Example
config_node_timeout=2

views_timeout (Timeout)

LCB_CNTL_VIEW_TIMEOUT (Microseconds)

The I/O timeout for view operations.

Connection String Example
views_timeout=75

n1ql_timeout (Timeout). Since 2.5.3

LCB_CNTL_N1QL_TIMEOUT (Microseconds)

The I/O timeout for N1QL queries.

Connection String Example
n1ql_timeout=75

durabilty_timeout (Timeout)

LCB_CNTL_DURABILITY_TIMEOUT (microseconds)

The default timeout for lcb_durability_poll() This is the time the client will spend sending repeated probes to a given key’s vBucket masters and replicas before they are deemed not to have satisfied the durability requirements.

Connection String Example
durability_timeout=5

durabilty_interval (Timeout)

LCB_CNTL_DURABILITY_INTERVAL (Microseconds)

This is the time the client will wait between repeated probes to a given server.

Connection String Example
durability_interval=0.0001

randomize_nodes (Boolean)

connection string only

This option controls whether the connection attempts for configuration retrievals should be done in the supplied order or whether they should be randomized. This setting is off by default. To affect the order of the initial connection, this option must be supplied in the connection string.

For the initial connection, the default order is the list of hosts provided in the structure. For subsequent connections, this is the order of nodes as received by the server.

Connection String Example
randomize_nodes=1

config_cache (Path)

LCB_CNTL_CONFIGCACHE (Path, a pointer to char buffer).

The configuration cache allows bootstrapping from a cluster without using the initial bootstrap connection, considerably reducing latency. If the file passed does not exist, the normal bootstrap process is performed, and the file is written to with the current information.

The leading directories for the file must exist. Otherwise, the file will never be created.
Configuration cache is not supported for memcached buckets
Connection String Example
config_cache=/tmp/cb_config_cache

config_cache_ro (Path). Since 2.4.8

LCB_CNTL_CONFIGCACHE_RO (Path)

This is identical to the config_cache option, except that it guarantees that the library will never overwrite or otherwise modify the path specified.

Connection String Example
config_cache_ro=1

detailed_errcodes (Boolean)

LCB_CNTL_DETAILED_ERRCODES (Boolean)

Sets the behavior for reporting network errors. By default network errors are returned as LCB_NETWORK_ERROR. Return codes for compatibility reasons. More detailed error codes may be available by enabling this option that will return appropriate error codes with a category LCB_ERRTYPE_NETWORK.

Using this option means your programming model is centered around the various LCB_EIF* macros (see <libcouchbase/error.h>) rather than individual codes.

For users of higher level languages (wrapping the library), this may result in different exceptions being thrown, but may also help debug network issues.

Connection String Example
detailed_errcodes=1

http_poolsize (Integer)

LCB_CNTL_HTTP_POOLSIZE

Set the maximum pool size for pooled HTTP (view or N1QL request) sockets. A setting of 0 disables pooling.

Connection String Example
http_poolsize=0

error_thresh_delay (Timeout)

LCB_CNTL_CONFDELAY_ERRTHRESH (microseconds)

This option controls refreshing the configuration upon the receipt of errors. The client throttles how many requests for a new configuration it will send in a given interval—this is to avoid sending many successive requests in the event of a non-transient error condition.

This setting controls the duration of this interval. The value can be adjusted upwards if operating in an environment where it is normal to receive many timeouts, such as in a resource-contented server or network. It can be adjusted downwards if timeouts are expected only in situations where the cluster has changed state.

Connection String Example
error_thresh_delay=7.5

bootstrap_on (String; see description)

connection string only

Controls how the client attempts to retrieve the configuration from the cluster. By default, the client attempts to connect to the data (memcached) port of each node listed and attempts to retrieve the configuration from there. If the retrieval fails, the client attempts the same process using the HTTP REST API port (8091) of each node.

This setting can be used to have the client forcefully use a single mode. This might be helpful for quick initialization of memcached buckets, which can only send configurations over HTTP. It can also be used in the case of potential issues encountered with either mode.

Possible values for this setting are:

  • http, to force bootstrap over HTTP only

  • cccp, to force bootstrap over memcached only

  • both, which attempts both (as above). This option can only be set from within the connection string.

Connection String Example
bootstrap_on=http

fetch_mutation_tokens (Boolean). Since 2.5.2

LCB_CNTL_FETCH_MUTATION_TOKENS (Boolean)

Whether the server should send an additional 16 bytes of metadata for each mutation response. This option is off by default but is required for Enhanced Durability. This option should be set either in the connection string, or immediately calling lcb_create(). For non-C applications, this must always be in the connection string.

Connection String Example
fetch_mutation_tokens=1

dur_mutation_tokens (Boolean). Since 2.5.2

LCB_CNTL_DURABILITY_MUTATION_TOKENS (Boolean)

Determines if Enhanced Durability is used automatically. It is enabled by default if fetch_synctokens is also enabled. Applications can take advantage of this new feature without modifying any code other than enabling these settings.

If you are checking durability constraints across client instances, and fetch_synctokens is enabled, then this setting should be disabled. Otherwise, the client will fail to retrieve the lcb_SYNCTOKEN (see more about this in the Enhanced Durability section). Alternatively, you can supply the sync token directly in the command structure.
Connection String Example
dur_mutation_tokens=1

Connection String

This section provides a reference point for various schemes and port parameters that they represent (in case alternate ports are required).

Unless debugging a specific network reachability issue or operating in an environment with non-default ports or using SSL, you need only use the simple form:

couchbase://host1,host2,host3...hostN/bucket
Table 2. Schemes
Scheme Documentation

couchbase://

This is the most common scheme and indicates that the client performs a normal bootstrap process. It will first attempt to bootstrap from "CCCP" using the memcached port. If that fails, the client attempts HTTP bootstrap or the REST API port.

If ports are passed to this scheme (e.g. couchbase://host1:4444,host2:5555,host3:6666), then they have to be memcached ports. The ports cannot be HTTP ports and use the HTTP scheme. The default port for memcached is 11210 and the default port for HTTP is 8091.

couchbase://host1,host2/mybucket
couchbase://localhost:12000/mybucket

couchbases://

This is the scheme used to connect to the cluster via SSL. When using this scheme, you must also pass the path to the local copy of the cluster’s certificate (e.g. couchbases://host1,host2,host3/bucket?certpath=/path/to/cert.pem). If specifying ports for the hosts, the ports should point to the SSL-enabled Memcached port for the node. The default Memcached SSL port is 11207. Currently bootstrapping over HTTP with SSL is unsupported.

couchbases://sslhost1,sslhost2,sslhost3/mybucket?certpath=/home/app/cbcert.pem

http://

This is the scheme used to connect to the cluster using the HTTP protocol and can be used in cases where there is a deliberate intent to connect to an alternate HTTP REST API port. Note that when using this scheme, the commonly used legacy idioms of http://host:8091 or http://host will be converted into a simple couchbase://host. The bootstrap process will function identically to the couchbase:// scheme. If using non-default ports, then only HTTP bootstrap will be performed

http://localhost:8091/mybucket

memcached:// (Experimental)

This scheme may be used to connect to a standalone memcached server. The scheme allows the client to communicate with any implementation of the memcached binary protocol, and as such may be used to communicate with http://memcached.org's implementation. When specifying this scheme, you must specify each host in the cluster (including its port, if needed):

memcached://node1:11211,node2:11211,node3:11211/binary-username

The bucket field becomes the binary protocol username.

couchbase+explicit:// (Experimental)

This scheme is experimental but provides the highest degree of flexibility. host:port pairs are specified, with a third specifier indicating the type of connection explicitly. The format is host:port=type where type is one of mcd (for couchbase Memcached), mcds (for SSL-enabled Memcached), http (for the HTTP REST API) and mccompat (for standalone Memcached)

couchbase+explicit://host1:8091=http,host1:11210=mcd,host2:8091=http,host2:12000=mcd/mybucket