A newer version of this documentation is available.

View Latest

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.

    CentOS 6 does not have a recent enough GCC to build libcouchbase and couchnode (the Node.js Couchbase client). Installing the Developer Toolset 7 will give you the build environment that you need, as well as the runtime libraries necessary for the Node.js SDK.

    Installing the SDK

    To install the SDK, simply use npm:

    npm install couchbase@2.6.11

    Note that npm install couchbase always installs the very latest version of the SDK — which is now at version 3.x.

    Information on new features, fixes, known issues, as well as information on how to install other 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 KV (data) 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.

    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.5.1, use:

    npm install couchbase@2.5.1

    Additional Resources