Install and Start Using the Node.js SDK with Couchbase Server

Preparing for Installation

Install Couchbase Server first, if you haven’t done so already. Refer to the installation guide for server installation instructions.

The SDK installation process will build libcouchbase (LCB) and other dependencies for you, so you will need the build tools for your platform, such as Visual Studio or GCC (more details in the LCB installation pages).

The Couchbase Node.js Client will run on any supported LTS version of Node.js — currently, 6.x, 8.x, and 10.x. On the Windows platform, it may be necessary to update the version of Node.js that Visual Studio points to.

The latest versions of Node.js can be downloaded from the Node.js website, and Nodesource provides instructions for each Linux distribution that Couchbase supports.

Installing the SDK

To install the SDK, simply use npm:

npm install couchbase

Information on new features, fixes, known issues, as well as information on how to install older release versions is in the release notes.

Hello Couchbase

Once you’ve installed the SDK, you can run this simple code snippet showcasing some of its features. Before running, be sure to replace localhost with the hostname of a node in your cluster, if running the SDK on a different host.

var couchbase = require('couchbase')
var cluster = new couchbase.Cluster('couchbase://localhost/');
cluster.authenticate('USERNAME', 'PASSWORD');
var bucket = cluster.openBucket('bucketname');
var N1qlQuery = couchbase.N1qlQuery;

bucket.manager().createPrimaryIndex(function() {
  bucket.upsert('user:king_arthur', {
    'email': 'kingarthur@couchbase.com', 'interests': ['Holy Grail', 'African Swallows']
  },
  function (err, result) {
    bucket.get('user:king_arthur', function (err, result) {
      console.log('Got result: %j', result.value);
      bucket.query(
      N1qlQuery.fromString('SELECT * FROM bucketname WHERE $1 in interests LIMIT 1'),
      ['African Swallows'],
      function (err, rows) {
        console.log("Got rows: %j", rows);
      });
    });
  });
});

The above shows how to upsert (insert-or-update) a single document and execute a query searching for specific criteria, in this case, any user who has an interest in African Swallows.

The code creates a Cluster object representing a Couchbase cluster. A connection to a data bucket is established using Cluster.openBucket, returning a Bucket object. The returned Bucket object is then used to perform document operations, and then executes a query.

Additional Resources

Using an external C SDK

The node.js SDK comes with an embedded version of the C SDK in order to streamline the installation experience. It may be necessary to use an external version of the C SDK if you wish to:

  • Use SSL connections with Couchbase

  • Use a version of the C SDK contains bug fixes not available in the embedded version

  • Develop the SDK itself and wish to speed up build times

To install the Node.js SDK using an external C SDK installation, install the libcouchbase library first, and point npm to it during the install.

# Assuming you have libcouchbase installed in /usr/local
# such that /usr/local/lib/libcouchbase.so (or .dylib) exists:
npm install couchbase --compile --couchbase-root=/usr/local

Installing previous versions

You can install a previous release of the SDK using npm install couchbase@x.y.z

where x.y.z is the version. For example, to install version 2.0.1, use:

npm install couchbase@2.0.1