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. |
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 | ||||
---|---|---|---|---|---|---|
|
|
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:
When an operation times out, it will fail with the Connection String Example
operation_timeout=2.5 |
||||
|
|
This is how long the client will wait to obtain the initial configuration.
This affects the maximum amount of time that the call to See also Connection String Example
config_total_timeout=5 |
||||
|
|
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 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 |
||||
|
|
The I/O timeout for view operations. Connection String Example
views_timeout=75 |
||||
|
|
The I/O timeout for N1QL queries. Connection String Example
n1ql_timeout=75 |
||||
|
|
The default timeout for Connection String Example
durability_timeout=5 |
||||
|
|
This is the time the client will wait between repeated probes to a given server. Connection String Example
durability_interval=0.0001 |
||||
|
|
Controls whether hostname lookups should prefer IPv4 or IPv6. Can be set to allow, disable (the default), or only. See http://docs.couchbase.com/sdk-api/couchbase-c-client-2.10.3/group__lcb-cntl-settings.html.adoc#gaa63aaa3ed8ca23f4af41fa09df09d05d for more info. |
||||
|
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 |
||||
|
|
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.
Connection String Example
config_cache=/tmp/cb_config_cache |
||||
|
|
This is identical to the Connection String Example
config_cache_ro=1 |
||||
|
|
Sets the behavior for reporting network errors.
By default network errors are returned as Using this option means your programming model is centered around the various 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 |
||||
|
|
Set the maximum pool size for pooled HTTP (view or N1QL request) sockets.
A setting of Connection String Example
http_poolsize=0 |
||||
|
|
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 |
||||
|
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:
Connection String Example
bootstrap_on=http |
||||
|
|
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 Connection String Example
fetch_mutation_tokens=1 |
||||
|
|
Determines if Enhanced Durability is used automatically.
It is enabled by default if
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 |
Scheme | Documentation |
---|---|
|
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,host2/mybucket couchbase://localhost:12000/mybucket |
|
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://sslhost1,sslhost2,sslhost3/mybucket?certpath=/home/app/cbcert.pem |
|
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://localhost:8091/mybucket |
|
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. |
|
This scheme is experimental but provides the highest degree of flexibility.
couchbase+explicit://host1:8091=http,host1:11210=mcd,host2:8091=http,host2:12000=mcd/mybucket |