A newer version of this documentation is available.

View Latest

Managing Connections Using the Node.js SDK with Couchbase Server

This section describes how to connect the Node.JS SDK to a Couchbase cluster and bucket. It contains best practices as well as information on the connection string, SSL and other advanced connection options.

You can specify additional options when connecting to the cluster by using the connection string. The connection string indicates to the client where cluster nodes may be found and how to connect to them. The connection string is common to other Couchbase SDKs as well as the command-line client. The connection string uses a URI-like format and is similar to a DSN used in other database systems.

Creating a Cluster Object

The Cluster object serves as an organizational unit for any Bucket objects created. As on the server each bucket is a member of a cluster, likewise in the SDK each Bucket object is a child of a Cluster. To create a cluster, construct it using a connection string, specifying the scheme and host(s) to connect to:

var couchbase = require('couchbase');
var cluster = new couchbase.Cluster('couchbase://');
Any Cluster nodes addresses passed in to establish (bootstrap) the connection should be for data (KV) nodes.


From Couchbase Server 5.0, you will need to authenticate the user, rather than against the bucket, as part of Role-Based Access Control. You will need to use cluster.authenticate:

cluster.authenticate('USERNAME', 'PASSWORD');

Connecting to a Bucket

To connect to a bucket, invoke the Cluster object’s openBucket call. The openBucket method takes a bucket name as an argument. If your bucket is protected by a password, pass it as the second parameter to openBucket. openBucket also accepts a function as its final argument which reports any connection errors which may happen between the creation of the Bucket object and the actual connection.

var bucket = cluster.openBucket('protectedBucket', function(err) {
  if (err) {
    console.error('Got error: %j', err);

From Couchbase Node.js SDK 2.5.0 (using libcouchbase 2.9.2), AlternateAddress is implemented, for connecting to nodes in a NATed environment, such as Docker containers using portmapping. It is on by default, if the server provides a topology that includes a multi-network configuration. Whichever network is selected at bootstrap will be logged.

If using Docker Swarm, or otherwise running the SDK inside the NAT, then you will want to disable with ?network=default in the connection string, or an environmental setting can be made.

Note that any SSL/TLS certificates must be set up at the point where the connections are being made. The Couchbase SDKs will honor any valid SSL/TLS certificates.

Disconnecting from a Bucket

If the Bucket object is no longer needed, you should call the Bucket.disconnect() function. This will disconnect any existing TCP connections between the object and the server.

Scalability and Concurrency

Creating a new Bucket object is relatively expensive, and keeping many idle Bucket objects will negatively impact server performance (if done at a large scale). Typically your application will require only one Bucket instance per Couchbase bucket

Connection Limits

Each Couchbase Data node allows by default, in Couchbase Data Platform 6.0 and earlier, up to 30,000 concurrent key-value connections per port exposed to the user by the Data Service (ports 11210 and 11207). This means that if you are mixing SSL connections (port 11207) and plain connections (port 11210), you can have 30,000 connections on each of these two ports, or up to 60,000 in total. If you are using plain (or SSL) alone, then the limit is 30,000.

From 6.5 onwards, the default value is 65,000 connections to the server — with 5000 of these reserved for system use. Thus, you can use 60,000 connections even if you only use_ one_ of the two ports (plain or SSL).

Connecting with SSL

You can specify additional options when connecting to the cluster by using the connection string. It indicates to the client where cluster nodes may be found and how to connect to them. Note that it is common to other Couchbase SDKs as well as the command-line client. The connection string uses a URI-like format familiar to what is used in other database systems.

Couchbase Sever features the ability to have clients communicate securely via SSL.

To use SSL, you need Couchbase Server Enterprise 3.0 or later (not available in the Community Edition).

  1. Obtain the SSL certificate used by the Cluster

  2. Make the certificate available to the file system of the client host.

  3. Employ the couchbases:// scheme for the connection string.

  4. Specify the local path to the certificate as the value for the certpath field.

To connect to a bucket on an SSL-enabled Cluster at the node, with the certificate saved as /var/cbcert.pem:


Specifying Multiple Hosts

You can specify multiple hosts in the connection string so that the client may be able to connect even if the cluster topology changed. To specify multiple hosts, separate them using a comma:


See Failure Considerations for the C (libcouchbase) SDK in Couchbase for more information about handling cluster topology changes.

You are not required to enumerate or pass all Couchbase cluster nodes to the client. The client only needs to know about a single node which is a member of the cluster. Once the client has connected to the node, it will query that node about the cluster topology, which in turn contains information about all Couchbase nodes and the services they contain.

Using DNS SRV records

As an alternative to specifying multiple hosts in your program, you can get the actual bootstrap node list from a DNS SRV record. The following steps are necessary to make it work:

  1. Set up your DNS server to respond properly from a DNS SRV request.

  2. Enable it on the SDK and point it towards the DNS SRV entry.

Your DNS server should be set up like this (one row for each bootstrap node):

_couchbase._tcp.example.com.  3600  IN  SRV  0  0  11210  node1.example.com.
_couchbase._tcp.example.com.  3600  IN  SRV  0  0  11210  node2.example.com.
_couchbase._tcp.example.com.  3600  IN  SRV  0  0  11210  node3.example.com.
The ordering, priorities, and weighting are completely ignored and should not be set on the records to avoid ambiguities.

If you plan to use secure connections, you use _couchbases instead:

_couchbases._tcp.example.com.  3600  IN  SRV  0  0  11207  node1.example.com.
_couchbases._tcp.example.com.  3600  IN  SRV  0  0  11207  node2.example.com.
_couchbases._tcp.example.com.  3600  IN  SRV  0  0  11207  node3.example.com.

In the above example, you would specify couchbase://example.com as the bootstrap host, and the library would check for the record. If no such record exists, it will treat example.com as an ordinary bootstrap node and try to bootstrap from it. Note that if you pass more than one bootstrap host, DNS SRV lookup will not be attempted, and the hosts will be interepreted as normal Couchbase nodes.

Configuration Cache

In environments when lots of short-lived connections are made to Couchbase (for example, a small command-line utility or a fork-and-execute CGI application) the overhead in actually bootstrapping the client may be significant. This is because the client must retrieve the configuration from the cluster, and involves several additional TCP requests and in many cases an additional TCP connection.

You can bypass the initial network bootstrap phase by using the config_cache directive in the connection string. The config_cache option accepts a path to a local file (the file should not exist when using for the first time). When performing the bootstrap process, the client will first check the contents of the given file to see if it contains an existing cluster configuration, and if it does, will use the file as the bootstrap source. If the file does not contain a configuration the client will then retrieve the configuration from the network and then write it to the file, so that future attempts will use the configuration file.

The config_cache feature is intended only for short-lived connections. During a cluster-side topology change the client will need to retrieve the configuration from the network as the file-based configuration will become invalid.

Additional Options

You can pass additional options in the connection string using the URL query format: couchbase://location-info?option1=value1&option2=value2&optionN=valueN. A list of options may be found in Client Settings