A newer version of this documentation is available.

View Latest

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


    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

    On the Windows platform using Node.js versions prior to 6.0, manual installation of OpenSSL and the C SDK (libcouchbase) is required. It is recommended to use Node.js 6.0 and later.

    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);
          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