Start Using the SDK
Edit this article in GitHub
Version 2.3

Start Using the SDK

Installing the Server

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

Installing the SDK

To install the SDK, simply use npm. On non-windows platforms you will also need to install node-gyp:

npm install couchbase 

Some features such as SSL support require using a manually installed version of the C SDK.

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