A newer version of this documentation is available.

View Latest


Connecting your client SDK to a Couchbase cluster.
Connecting to Couchbase, in pseudo code
client = (new Cluster(‘couchbase://node’)).openBucket(‘travel-sample’)
client = new Bucket(‘couchbase://node/bucket?option1=value1&option2=value2’)
client = new Bucket(‘couchbase://node://bucket’, ‘bucketPassword’)

Connecting to cluster is done by creating a new SDK instance (or handle, or object) and providing the cluster address and bucket name as input parameters.

The cluster address specifies how to contact the Couchbase cluster, and the bucket name specifies which data bucket should be accessed.

Once an SDK instance is connected, it may be used to access data.

Information about the cluster location and bucket to use may be specified by a connection string. A connection string is a URI-like string which specifies the cluster node(s) and the bucket to connect to. It may also specify additional options.

The connection string uses a scheme (couchbase://) followed by the host (which is an IP or hostname of any KV cluster node) and a bucket (as the connection string’s path). Additional connection options can be specified in a URL-style format.

If using multidimensional scaling, it is recommended to specify only data (KV) nodes in the connection string.

See Advanced connection details for a detailed overview of the connection process, and tips to ensure best performance and application behavior.

Connecting from an SDK

Most Couchbase SDKs will accept a connection string, however the other object names, verbs, and options are very SDK specific.

Provided below is an example in Python. Links to examples for other SDKs are found below.

Connecting to a cluster, in Python
from couchbase.bucket import Bucket
cb = Bucket('couchbase://')
cb.upsert('docid', {'new': 'document', 'fields': []})

node.js | Java | Go | .NET | C | Python

Connecting from the command line

You may direct the cbc command line utility to a cluster by specifying the connection string via the -U option, for example:

$ cbc cat airport_4542 -U couchbase://

Connection string examples

Connect to localhost, default bucket
Connect to localhost non-default bucket
Connect remote IP, non-default bucket
Connect to remote hostname
Connect to multiple nodes
See Advanced connection details for more information on connecting to multiple nodes.
Connect with options

Additional options may be found in the connection string reference for your SDK.