{"id":11705,"date":"2021-08-23T00:00:26","date_gmt":"2021-08-23T07:00:26","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=11705"},"modified":"2025-06-13T21:23:04","modified_gmt":"2025-06-14T04:23:04","slug":"get-started-nodejs-sdk-couchbase","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/get-started-nodejs-sdk-couchbase\/","title":{"rendered":"How to Get Started with the Node.js SDK for Couchbase"},"content":{"rendered":"

In just a few lines of code<\/strong> you can start using Couchbase with Node.js to build your next JavaScript application.<\/p>\n

This hello world<\/em> tutorial walks you through the basic first steps of using the Node.js SDK<\/a> with the latest features of Couchbase 7.0<\/a>. It assumes you have at least some familiarity with both JavaScript and NoSQL databases<\/a> \u2013 but expertise isn’t required.<\/p>\n

Install & Prepare Couchbase<\/h2>\n

Before you dive into developing an application, start by setting up the latest version of Couchbase Server<\/a> or sign up for free a Couchbase Cloud account<\/a>.<\/p>\n

After installation, set up the `travel-sample` Bucket which creates a set of sample documents with flights, hotels, landmarks and more. You’ll find this data handy for testing a range of different kinds of applications.<\/p>\n

Set Up a Basic Node.js Application<\/h2>\n

For the rest of this post, I’ll assume you already have Node.js installed along with your favorite code editing tools. (First-time developers should look up some basic tutorials to get a working environment.)<\/p>\n

Your first step is to create a project folder and initialize the package template with npm init -y<\/code>, as shown below:<\/p>\n

tyler@local:~\/src\/cb-node$ npm init -y\r\nWrote to \/home\/tyler\/src\/cb-node\/package.json:\r\n\r\n{\r\n\"name\": \"cb-node\",\r\n\"version\": \"1.0.0\",\r\n\"description\": \"\",\r\n\"main\": \"index.js\",\r\n\"scripts\": {\r\n\"test\": \"echo \\\"Error: no test specified\\\" && exit 1\"\r\n},\r\n\"keywords\": [],\r\n\"author\": \"\",\r\n\"license\": \"ISC\"\r\n}\r\n<\/pre>\n
<\/div>\n
Add the Couchbase Node.js Module Dependency<\/h2>\n
Next, add the Couchbase Node.js module to the dependencies in package.json<\/code> by running the npm install<\/code> command with the --save<\/code> option, like so:<\/p>\n
$ npm install couchbase --save\r\n> couchbase@3.2.0 install \/home\/tyler\/src\/cb-node\/node_modules\/couchbase\r\n> prebuild-install || node-gyp rebuild\r\n\r\n...\r\n\r\nnpm WARN cb-node@1.0.0 No description\r\nnpm WARN cb-node@1.0.0 No repository field.\r\n\r\n+ couchbase@3.2.0\r\n<\/pre>\n
<\/div>\n
The package.json<\/code> file now has the dependency section:<\/p>\n
\"dependencies\": {\r\n\"couchbase\": \"^3.2.0\"\r\n}\r\n<\/pre>\n
<\/div>\n
Connect to a Couchbase Cluster<\/h2>\n
To test that the modules are all installed properly \u2013 and that you can connect to the cluster \u2013 you need to know the Bucket name in order to connect to and add a user that can access the Couchbase Bucket.<\/p>\n
var couchbase = require(\"couchbase\");\r\n<\/pre>\n
<\/div>\n
For the most simplistic usage, wrap the rest of the example in a connect function:<\/p>\n
couchbase.connect(\r\n  'couchbase:\/\/127.0.0.1',\r\n  {\r\n    username: 'Administrator',\r\n    password: 'Administrator'\r\n  },\r\n...)\r\n<\/pre>\n
<\/div>\n
You also need to select the keyspace \u2013 i.e., Scope or Collection(s)<\/a> \u2013 you want to access, if applicable. In this initial test case, we’ll use a default Collection which ignores Scopes and Collections altogether:<\/p>\n
...\r\n(err, cluster) => {\r\n  var bucket = cluster.bucket('travel-sample')\r\n  var coll = bucket.defaultCollection()\r\n...\r\n<\/pre>\n
<\/div>\n
Get a JSON Document<\/h2>\n
There are thousands of sample JSON<\/a> documents in the travel-sample<\/code> Bucket.<\/p>\n
To request a document using basic key-value operations, use the get<\/code> function and supply a document ID. You can use the web console to browse for a given hotel document to get the ID, as pictured below.<\/p>\n
<\/div>\n
\"A<\/a><\/p>\n
<\/div>\n
Catch the response and error, then print to console to see if it is successful.<\/p>\n
coll.get('hotel_5336', (err, res) => {\r\n  if (err) throw err\r\n  console.log(res.value)\r\n<\/pre>\n
<\/div>\n
If you made it this far and it’s your first Node.js app, congratulations! You now know how to get a document from Couchbase with the most simple syntax. The full code sample is below:<\/p>\n
var couchbase = require('couchbase')\r\n\r\ncouchbase.connect(\r\n  'couchbase:\/\/127.0.0.1',\r\n  {\r\n    username: 'Administrator',\r\n    password: 'Administrator'\r\n  },\r\n  (err, cluster) => {\r\n    var bucket = cluster.bucket('travel-sample')\r\n    var coll = bucket.defaultCollection()\r\n\r\n    coll.get('hotel_5336', (err, res) => {\r\n      if (err) throw err\r\n      console.log(res.value)\r\n    })\r\n  }\r\n)\r\n<\/pre>\n
<\/div>\n
Keep in mind this is a basic example that includes blocking code. In a future article, I’ll cover an example that shows non-blocking async examples instead.<\/p>\n
Create or Upsert a Document Using JavaScript<\/h2>\n
To create a new document you can use the upsert<\/code> function. It’s called upsert<\/code> because it acts like an insert (for new documents) or if there is already a document with the same ID, it will simply update it.<\/p>\n
Ensure that the user you specify has adequate write privileges before trying an `upsert`. The examples below assume full Bucket administrative access to keep things simple.<\/p>\n
At this point, copy your script into a new file for testing the upsert<\/code> functionality independent from the get<\/code> function.<\/p>\n
Upsert<\/code> requires a document ID and a JSON object with the document data. You provide the ID when pushing it to the database. Create the variable to hold the JSON data and add some elements to it.<\/p>\n
newdoc = {\r\n  type: \"hotel\",\r\n  id: 2,\r\n  name: \"Le Grande\",\r\n  city: \"Paris, France\"\r\n}\r\n<\/pre>\n
<\/div>\n
Next, call the upsert<\/code> function along with the new document ID.<\/p>\n
coll.upsert('hotel_2', newdoc, (err, res) => {\r\n  console.log(res)\r\n})\r\n<\/pre>\n
<\/div>\n
Print the output to show that a mutation\/transaction has completed. The CAS<\/code> value is used in other contexts to compare vintage of the data for tracking\/locking different data versions.<\/p>\n
Running the script produces the following transaction summary:<\/p>\n
$ node app.js\r\n\r\nMutationResult {\r\ncas: CbCas<1628915917601505280>,\r\ntoken: CbMutationToken<4:251812459673841:85:travel-sample> }\r\n<\/pre>\n
<\/div>\n
Now you can go back to your original `get` script and drop in the new document ID to test that it can now be retrieved.<\/p>\n
Here is the full script for doing the simple `upsert` in a standalone Node.js script.<\/p>\n
var couchbase = require('couchbase')\r\n\r\ncouchbase.connect(\r\n  'couchbase:\/\/127.0.0.1',\r\n  {\r\n    username: 'Administrator',\r\n    password: 'Administrator'\r\n  },\r\n  (err, cluster) => {\r\n    var bucket = cluster.bucket('travel-sample')\r\n    var coll = bucket.defaultCollection()\r\n\r\n    newdoc = {\r\n      type: \"hotel\",\r\n      id: 2,\r\n      name: \"Le Grande\",\r\n      city: \"Paris, France\"\r\n    }\r\n\r\n    coll.upsert('hotel_2', newdoc, (err, res) => {\r\n      console.log(\"Hotel added\")\r\n      console.log(res)\r\n    })\r\n  }\r\n)\r\n<\/pre>\n
<\/div>\n
Conclusion<\/h2>\n
Thank you for following along with these basic JavaScript with Couchbase examples. I hope this gets you started with building a NoSQL application using Node.js.<\/p>\n
For more SDK-related examples check out the Node.js SDK documentation<\/a>. In future posts, we’ll explore using the functions asynchronously and dig into other Couchbase functions like query and search.<\/p>\n
Catch up with the rest of the Node.js + Couchbase how-to series:<\/em><\/p>\n