Setup<\/h4>\nRequirements<\/h5>\n
To complete this tutorial, you must have the following:<\/p>\n
- \n
- A Couchbase Capella account<\/span><\/a> – free trials are available with a simple sign-up<\/span><\/li>\n
- Capella Cluster <\/span>deployed<\/span><\/a> and <\/span>configured for access<\/span><\/a><\/li>\n
- npm<\/a> – Node.js package manager<\/li>\n<\/ul>\n
Install latest long-term support (LTS) release of Node.<\/a><\/h5>\n
Download and install Node’s latest long-term support (LTS) release if you haven’t already.<\/p>\n
If you\u2019re installing Node for the first time, we recommend using the <\/span>Node Version Manager (nvm)<\/span><\/a> for getting started with Node.<\/span><\/p>\n
- \n
- Follow the instructions for <\/span>installing nvm<\/span><\/a><\/li>\n
- Install the latest Node LTS release<\/span><\/li>\n<\/ol>\n
$ nvm install --lts<\/pre>\n
Create a Node.JS Project<\/h5>\n
Creating a Node.js project is as easy as making a directory and initializing it with npm. The next two commands will do that for us. Open up a terminal and run the following command:<\/p>\n
$ mkdir node-couchbase-project && cd $_<\/pre>\n
The command above will make our directory and change our current working directory. The next command initializes the project directory:<\/p>\n
$ npm init -y<\/pre>\n
If a directory does not already have a package.json<\/em> at its root, this means it is not initialized. The command above will accomplish this.<\/p>\n
Note: We have used the -y<\/em> flag to take the initialization defaults. To change any of these defaults, just open the package.json<\/em> and manually make any changes.<\/p>\n
{\r\n\"name\": \"node-couchbase-project\",\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}<\/pre>\nInstall the Couchbase Node.js SDK<\/h5>\n
The Couchbase Node.js SDK enables you to interact with a Couchbase Server cluster from the Node.js language. The Couchbase Node.js Client will run on any supported LTS version of Node.js<\/a>.<\/p>\n
To install the latest Couchbase Node.js SDK, run the following command:<\/p>\n
$ npm install couchbase --save<\/pre>\n
Use the –save<\/em> option to have the Couchbase module added as a dependency to the project. This will help automate the installation of packages if you want to distribute your work in the future.<\/p>\n
Connecting to Couchbase with built-in Node.js SDK<\/h4>\n
After installing the Couchbase SDK<\/a>, the next step is to use the built-in SDK examples to connect to your cluster.<\/p>\n
Find cluster connection settings<\/h5>\n
Go to the cluster\u2019s Connect tab in the Couchbase Capella UI using these steps:<\/p>\n
- \n
- Go to the Clusters tab in the main navigation<\/li>\n
- Find and click on your cluster (docs-cluster13feb1 in the following screenshot). This opens the cluster with its Overview tab selected.<\/li>\n
- Click the Connect tab in the left sidebar<\/li>\n<\/ul>\n
![\"\"](\"https:\/\/www.couchbase.com\/blog\/wp-content\/uploads\/2022\/01\/findcluster.png\")
<\/p>\nIn the Connection section, two endpoints are listed: One labeled Public<\/em> and one labeled Private<\/em>.<\/p>\n
When connecting to the cluster over a wide area network\u2014such as when you\u2019re connecting to the cluster over the Internet from an application on your laptop\u2014you will use the public endpoint.<\/p>\n
When connecting to the cluster from within your cloud provider using a peering connection, you will use the private endpoint.<\/p>\n
However, you will not need to copy the public endpoint for this post because it is automatically included in the built-in SDK examples we will use.<\/p>\n
Open SDK examples<\/h4>\n
Click SDK Examples. This opens the SDK Examples fly-out menu, showing the options in this screenshot:<\/p>\n
![\"\"](\"https:\/\/www.couchbase.com\/blog\/wp-content\/uploads\/2022\/01\/sdkexamples.png\")
<\/p>\nEach of the supported Couchbase SDK languages is represented by a tab. Under each tab, a snippet of the example code is provided. The example code is pre-populated with the cluster\u2019s public endpoint and, with a few modifications, can quickly be used for connecting to the cluster.<\/p>\n
Copy the example code.<\/h5>\n
Click on the tab for your desired SDK language, and copy the example code. If you\u2019re following the examples in this guide, click the Node.js tab, and copy the example JavaScript code.<\/p>\n
Paste the example code into a text editor and update your connection details.<\/p>\n
The SDK example code automatically comes pre-populated with the cluster\u2019s public endpoint and default bucket name.<\/p>\n
Update the username<\/em> and password<\/em> connection settings to the database credentials you created when you <\/span>configured database access<\/span><\/a> earlier.<\/span><\/p>\n
Changing the bucket (optional)<\/h5>\n
The bucketName<\/em> is the name of a bucket on the cluster you will connect to. The example code comes pre-populated with the name of the default bucket: couchbasecloudbucket<\/em>. This bucket will suffice for this tutorial, but if you choose to <\/span>create a new bucket<\/span><\/a> for this exercise, you\u2019ll need to specify the new bucket\u2019s name in the example code.<\/span><\/p>\n
Database credentials must allow access to any new bucket that you add. If you configured the database credential to have read\/write permissions on all buckets (as recommended), you can specify any bucket when testing out the connection.<\/p>\n
The following is an example of a completed Node.js configuration:<\/p>\n
var couchbase = require('couchbase');\r\n\r\n\/\/ Update this to your cluster\r\n\r\nconst endpoint = '408f6eee-c52d-4d44-a155-691f9c511931.dataplane.couchbase.com'\r\nconst username = 'admin'\r\nconst password = 'P@ssw0rd'\r\nconst bucketName = 'couchbasecloudbucket'\r\n\r\n\/\/ User Input ends here.\r\n\r\n\/\/ Initialize the Connection\r\nvar cluster = new couchbase.Cluster('couchbases:\/\/' +endpoint+'?ssl=no_verify&console_log_level=5', {username: username, password: password});\r\nvar bucket = cluster.bucket(bucketName);\r\nvar collection = bucket.defaultCollection();\r\n\r\nfunction start(){\r\nconsole.log('start');\r\nreturn new Promise( (resolve, reject) => { resolve(); });\r\n}\r\n\r\nasync function run(){\r\n\/\/ Create a N1QL Primary Index (but ignore if it exists)\r\ntry {\r\nawait cluster.queryIndexes().createPrimaryIndex(bucketName, {ignoreExists: true});\r\n} catch (e) {\r\n}\r\n\r\n\/\/ Create and store a document\r\ntry {\r\nawait collection.upsert('user:king_arthur', {\r\n'name': 'Arthur', 'email': 'kingarthur@couchbase.com', 'interests': ['Holy Grail', 'African Swallows']\r\n});\r\n} catch (e) {\r\nthrow(e);\r\n}\r\n\r\n\/\/ Load the Document and print it\r\n\/\/ Prints Content and Metadata of the stored Document\r\ntry {\r\nlet getResult = await collection .get('user:king_arthur');\r\nconsole.log('Got: ');\r\nconsole.log(getResult);\r\n} catch (e) {\r\nconsole.log(e);\r\nthrow(e);\r\n}\r\n\r\n\/\/ Perform a N1QL Query\r\nconst options = { parameters: ['African Swallows'] };\r\ntry {\r\nlet queryResult = await cluster.query('SELECT name FROM '+bucketName +' WHERE $1 in interests LIMIT 1', options);\r\nqueryResult.rows.forEach((row) => {\r\nconsole.log('Query row: ', row)\r\n});\r\n} catch (e) {\r\nconsole.log(e);\r\nthrow(e);\r\n}\r\n}\r\nstart().then(run).then(() => { console.log(\"closing...\"); cluster.close();});<\/pre>\nOnce you\u2019ve finished updating the example code with your connection details, save it in your project directory. Be sure to use the appropriate file extension for the SDK language.<\/p>\n
If you\u2019re following the examples in this guide, save the file as connection-script.js<\/em> in the node-couchbase-project<\/em> directory that you created earlier when you installed the Couchbase Node.js SDK.<\/p>\n
Connect to the cluster.<\/h5>\n
From the project directory, run the connection script using the following command:<\/p>\n
node connection-script.js<\/pre>\n
The results you should expect are as follows:<\/p>\n
Got:\r\n{\r\ncas: CbCas { '0': <Buffer 08 00 64 71 50 c3 25 16> },\r\nvalue: {\r\nname: 'Arthur',\r\nemail: 'kingarthur@couchbase.com',\r\ninterests: [ 'Holy Grail', 'African Swallows' ]\r\n}\r\n}\r\nQuery row: { name: 'Arthur' }<\/pre>\nIf you received the results above, the connection was successful, and a document was written to the bucket.<\/p>\n
Congratulations on completing this quickstart guide! Be sure to try this out on Couchbase Capella to see how easy it can be.<\/p>\n
Resources<\/span><\/h4>\n
Capella<\/span><\/h5>\n
To learn more about <\/span>Couchbase Capella<\/span><\/a>, our database-as-a-service offering:<\/span><\/p>\n
- \n
- Sign up for a <\/span>free 30-day trial<\/span><\/a> if you haven’t already<\/span><\/li>\n
- Connect your trial cluster to the Playground<\/span><\/a> or connect a project to test it out for yourself<\/span><\/li>\n
- Take a look at the <\/span>Capella Learning Path<\/span><\/a>!<\/span><\/li>\n<\/ul>\n
Tutorials<\/span><\/h5>\n
The <\/span>Couchbase Developer Portal<\/span><\/a> has tons of <\/span>tutorials\/quickstart guides<\/span><\/a> and <\/span>learning paths<\/span><\/a> to help you get started, including:<\/span><\/p>\n
- \n
- Node.js and Express Tutorial<\/span><\/a><\/li>\n
- Ottoman.js and Express Tutorial<\/span><\/a><\/li>\n
- Next.js Tutorial<\/span><\/a><\/li>\n<\/ul>\n
Training<\/span><\/h5>\n
We have several training options available depending on your need and level:<\/span><\/p>\n
- Ottoman.js and Express Tutorial<\/span><\/a><\/li>\n
- Connect your trial cluster to the Playground<\/span><\/a> or connect a project to test it out for yourself<\/span><\/li>\n
- Sign up for a <\/span>free 30-day trial<\/span><\/a> if you haven’t already<\/span><\/li>\n
- Install the latest Node LTS release<\/span><\/li>\n<\/ol>\n
- Capella Cluster <\/span>deployed<\/span><\/a> and <\/span>configured for access<\/span><\/a><\/li>\n