Initialization

Detailed Description

To communicate with a Couchbase cluster, a new library handle instance is created in the form of an lcb_INSTANCE. To create such an object, the lcb_create() function is called, passing it a structure of type lcb_create_st. The structure acts as a container for a union of other structures which are extended as more features are added. This container is forwards and backwards compatible, meaning that if the structure is extended, you code and application will still function if using an older version of the structure. The current sub-field of the lcb_create_st structure is the v3 field.

Connecting to the cluster involes the client knowing the necessary information needed to actually locate its services and connect to it.

A connection specification consists of:

1. One or more hosts which comprise the cluster
2. The name of the bucket to access and perform operations on
3. The credentials of the bucket

All these options are specified within the form of a URI in the form of

couchbase://$HOSTS/$BUCKET?$OPTIONS

Note

If any of the fields (hosts, bucket, options) contain the / character then it must be url-encoded; thus a bucket named foo/bar would be specified as couchbase:///foo%2Fbar

Hosts

In the most typical use case, you would specify a list of several hostnames delimited by a comma (,); each host specified should be a member of the cluster. The library will use this list to initially connect to the cluster.

Note that it is not necessary to specify all the nodes of the cluster as in a normal situation the library will only initially connect to one of the nodes. Passing multiple nodes increases the chance of a connection succeeding even if some of the nodes are currently down. Once connected to the cluster, the client will update itself with the other nodes actually found within the cluster and discard the list passed to it

You can specify multiple hosts like so:

couchbase://foo.com,bar.com,baz.com

Or a single host:

couchbase://localhost

Specifying Ports and Protocol Options

The default couchbase:// scheme will assume all hosts and/or ports specify the memcached port. If no port is specified, it is assumed that the port is _11210). For more extended options there are additional schemes available:

• couchbases:// - Will assume all ports refer to the SSL-enabled memcached ports. This setting implicitly enables SSL on the instance as well. If no ports are provided for the hosts, the implicit port for each host will be 11207.
• http:// - Will assume all ports refer to the HTTP REST API ports used by Couchbase 2.2 and lower. These are also used when connecting to a memcached bucket. If no port is specified it will be assumed the port is 8091.

Bucket

A bucket may be specified by using the optional path component of the URI For protected buckets a password will still need to be supplied out of band.

• couchbase://1.1.1.1,2.2.2.2,3.3.3.3/users - Connect to the users bucket.

Options

Warning

The key-value options here are considered to be an uncommitted interface as their names may change.

Options can be specified as the query part of the connection string, for example:

couchbase://cbnode.net/beer?operation_timeout=10000000.

Options may either be appropriate key parameters for lcb_cntl_string() or one of the following:

• boostrap_on - specify bootstrap protocols. Values can be http to force old-style bootstrap mode for legacy clusters, cccp to force bootstrap over the memcached port (For clusters 2.5 and above), or all to try with cccp and revert to http
• truststorepath - Specify the path (on the local filesystem) to the server's SSL certificate truststore. Only applicable if SSL is being used (i.e. the scheme is couchbases). The trust store is optional, and when missing, the library will use certpath as location for verification, and expect any extra certificates to be concatenated in there.
• certpath - Specify the path (on the local filesystem) to the server's SSL certificate. Only applicable if SSL is being used (i.e. the scheme is couchbases)
• keypath - Specify the path (on the local filesystem) to the client SSL private key. Only applicable if SSL client certificate authentication is being used (i.e. the scheme is couchbases and certpath contains client certificate). Read more in the server documentation: https://developer.couchbase.com/documentation/server/5.0/security/security-certs-auth.html

Bucket Identification and Credentials

The most common settings you will wish to modify are the bucket name and the credentials field (user and passwd). If a bucket is not specified it will revert to the default bucket (i.e. the bucket which is created when Couchbase Server is installed).

The user and passwd fields authenticate for the bucket. This is only needed if you have configured your bucket to employ SASL auth. You can tell if the bucket has been configured with SASL auth by

1. Logging into the Couchbase Administration Console
2. Going to the Data Buckets tab
3. Locate the row for your bucket
4. Expand the row into the detailed view (by clicking on the arrow at the left of the row)
5. Click on Edit
6. Inspect the Access Control section in the pop-up

The bucket name is specified as the path portion of the URI.

For security purposes, the user and passwd cannot be specified within the URI

Note

You may not change the bucket or credentials after initializing the handle.

Bootstrap Options

The default configuration process will attempt to bootstrap first from the new memcached configuration protocol (CCCP) and if that fails, use the "HTTP" protocol via the REST API.

The CCCP configuration will by default attempt to connect to one of the nodes specified on the port 11201. While normally the memcached port is determined by the configuration itself, this is not possible when the configuration has not been attained. You may specify a list of alternate memcached servers by using the 'mchosts' field.

If you wish to modify the default bootstrap protocol selection, you can use the bootstrap_on option to specify the desired bootstrap specification to use for configuration (note that the ordering of this array is ignored). Using this mechanism, you can disable CCCP or HTTP.

To force only "new-style" bootstrap, you may use bootstrap_on=cccp. To force only "old-style" bootstrap, use bootstrap_on=http. To force the default behavior, use bootstrap_on=all

Function Documentation

lcb_create()

lcb_STATUS lcb_create	(	lcb_INSTANCE **	instance,
		const lcb_CREATEOPTS *	options )

Create an instance of lcb.

Parameters

instance	Where the instance should be returned
options	How to create the libcouchbase instance

Returns

LCB_SUCCESS on success

Examples

Create an instance using the default values:

lcb_INSTANCE *instance;
lcb_STATUS err = lcb_create(&instance, NULL);
if (err != LCB_SUCCESS) {
   fprintf(stderr, "Failed to create instance: %s\n", lcb_strerror_short(err));
   exit(EXIT_FAILURE);
}

Specify server list

struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 3;
options.v.v3.connstr = "couchbase://host1,host2,host3";
err = lcb_create(&instance, &options);

Create a handle for data requests to protected bucket

struct lcb_create_st options;
memset(&options, 0, sizeof(options));
options.version = 3;
options.v.v3.host = "couchbase://example.com,example.org/protected"
options.v.v3.passwd = "secret";
err = lcb_create(&instance, &options);

Stability

Committed

See also

lcb_create_st3

Examples

example/analytics/analytics.c, example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/fts/fts.c, example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/subdoc/subdoc-multi.cc, example/subdoc/subdoc-simple.cc, example/subdoc/subdoc-xattrs.c, example/threads-private/threads-private.c, example/threads-shared/threads-shared.c, example/tracing/tracing.c, and example/tracing/views.c.

lcb_connect()

lcb_STATUS lcb_connect

(

lcb_INSTANCE *

instance

)

Schedule the initial connection This function will schedule the initial connection for the handle.

This function must be called before any operations can be performed.

lcb_set_bootstrap_callback() or lcb_get_bootstrap_status() can be used to determine if the scheduled connection completed successfully.

Synchronous Usage

lcb_STATUS rc = lcb_connect(instance);
if (rc != LCB_SUCCESS) {
   your_error_handling(rc);
}
lcb_wait(instance, LCB_WAIT_DEFAULT);
rc = lcb_get_bootstrap_status(instance);
if (rc != LCB_SUCCESS) {
   your_error_handler(rc);
}

Stability

Committed

Examples

example/analytics/analytics.c, example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/fts/fts.c, example/libeventdirect/main.c, example/minimal/minimal.c, example/minimal/query.c, example/subdoc/subdoc-multi.cc, example/subdoc/subdoc-simple.cc, example/subdoc/subdoc-xattrs.c, example/threads-private/threads-private.c, example/threads-shared/threads-shared.c, example/tracing/tracing.c, and example/tracing/views.c.

lcb_set_bootstrap_callback()

lcb_bootstrap_callback lcb_set_bootstrap_callback	(	lcb_INSTANCE *	instance,
		lcb_bootstrap_callback	callback )

Set the callback for notification of success or failure of initial connection.

Parameters

instance	the instance
callback	the callback to set. If NULL, return the existing callback

Returns

The existing (and previous) callback.

See also

lcb_connect()

lcb_get_bootstrap_status()

Examples

example/libeventdirect/main.c.

lcb_get_bootstrap_status()

lcb_STATUS lcb_get_bootstrap_status

(

lcb_INSTANCE *

instance

)

Gets the initial bootstrap status.

This is an alternative to using the lcb_bootstrap_callback() and may be used after the initial lcb_connect() and lcb_wait() sequence.

Parameters

instance

Returns

LCB_SUCCESS if properly bootstrapped or an error code otherwise.

Attention

Calling this function only makes sense during instantiation.

Stability

Committed

Examples

example/analytics/analytics.c, example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/fts/fts.c, example/minimal/minimal.c, example/minimal/query.c, example/subdoc/subdoc-multi.cc, example/subdoc/subdoc-simple.cc, example/subdoc/subdoc-xattrs.c, example/tracing/tracing.c, and example/tracing/views.c.

lcb_set_auth()

void lcb_set_auth	(	lcb_INSTANCE *	instance,
		lcb_AUTHENTICATOR *	auth )

Sets the authenticator object for the instance.

This may be done anytime, but should probably be done before calling lcb_connect() for best effect.

Parameters

instance	the handle
auth	the authenticator object used. The library will increase the refcount on the authenticator object.

Typedef Documentation

lcb_INSTANCE

typedef struct lcb_st lcb_INSTANCE

Library handle representing a connection to a cluster and its data buckets.

The contents of this structure are opaque.

See also

lcb_create

lcb_destroy

lcb_bootstrap_callback

typedef void(* lcb_bootstrap_callback) (lcb_INSTANCE *instance, lcb_STATUS err)

Bootstrap callback.

Invoked once the instance is ready to perform operations

Parameters

instance	The instance which was bootstrapped
err	The error code received. If this is not LCB_SUCCESS then the instance is not bootstrapped and must be recreated

Attention

This callback only receives information during instantiation.

Stability

Committed

Enumeration Type Documentation

lcb_BTYPE

enum lcb_BTYPE

Type of the bucket.

See also

https://developer.couchbase.com/documentation/server/current/architecture/core-data-access-buckets.html

Enumerator
LCB_BTYPE_UNSPEC	Unknown or unspecified.
LCB_BTYPE_COUCHBASE	Data persisted and replicated.
LCB_BTYPE_EPHEMERAL	Data not persisted, but replicated.
LCB_BTYPE_MEMCACHED	Data not persisted and not replicated.

lcb_INSTANCE_TYPE

enum lcb_INSTANCE_TYPE

Handle types.

See also

lcb_create_st3::type

Enumerator
LCB_TYPE_BUCKET	Handle for data access (default)
LCB_TYPE_CLUSTER	Handle for administrative access.