You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
:description: The Couchbase Node.js SDK enables you to interact with a Couchbase Server or Capella cluster from the Node.js runtime, using Typescript or JavaScript.
7
+
5
8
6
9
[abstract]
7
-
The Couchbase Node.js SDK enables you to interact with a Couchbase Server cluster from the link:https://nodejs.org/[Node.js runtime].
10
+
{description}
8
11
9
12
The Couchbase SDK API 3 (implemented by Node.js SDK 3._x_ and 4._x_) is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for Couchbase Server features like xref:concept-docs:collections.adoc[Collections and Scopes] (available from Couchbase Server 7.0).
10
13
11
-
SDK API 3 also brings in link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises[promises], to reduce the complexity of asynchronous javascript in client applications, as well as extending the management APIs and bringing better debugging and logging options.
12
-
13
14
Node.js SDK 4._x_ implements the same SDK API 3 bindings, but the internals are completely rewritten --
14
15
using the Couchbase++ library rather than libcouchbase -- to allow upcoming new features such as transactions, and fix some long-standing bugs.
15
16
Please note any xref:project-docs:migrating-sdk-code-to-3.n.adoc#sdk4-specifics[caveats] in the migration guide.
16
17
17
-
// tag::prep[]
18
-
// end::prep[]
19
18
20
-
// tag::install[]
19
+
== Hello Couchbase
21
20
22
-
== Creating a New Node.js Project
23
-
// This section is optional
21
+
On this page we show you how to quickly get up and running -- installing the Couchbase Node.js SDK, and trying out the Hello World code example against Couchbase Capella, or against a local Couchbase cluster.
24
22
25
-
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:
23
+
We will go through the code sample step by step, but for those in a hurry to see it, here it is:
26
24
27
-
[source,console]
25
+
[{tabs}]
26
+
====
27
+
Couchbase Capella Sample::
28
+
+
29
+
--
30
+
If you are connecting to https://docs.couchbase.com/cloud/index.html[Couchbase Capella], be sure to get the correct endpoint as well as user, password, and `couchbasecloudbucket` -- and see the <<cloud-connections, Cloud section>>, below.
The command above will make our directory and change our current working directory.
33
-
34
-
[source,console]
38
+
Local Server with TS::
39
+
+
40
+
--
41
+
[source,typescript,indent=0]
35
42
----
36
-
$ npm init -y
43
+
include::../examples/start-using.ts[tags=**]
37
44
----
45
+
--
38
46
39
-
If a directory does not already have a `package.json` at its root, this means it is not initialized. The command above will accomplish this.
40
-
41
-
Note: We have used the `-y` flag to take the initialization defaults. To change any of these defaults, just open the `package.json` and manually make any changes.
42
-
43
-
[source,json,indent=0]
47
+
Local Server with JS::
48
+
+
49
+
--
50
+
[source.try-it,nodejs,indent=0]
44
51
----
45
-
include::../examples/example-package.json[]
52
+
include::../examples/start-using.js[tags=**]
46
53
----
54
+
--
55
+
====
47
56
48
-
== Installing the SDK
49
57
50
-
The Couchbase Node.js Client will run on any https://nodejs.org/en/download/[supported LTS version of Node.js].
58
+
== Quick Installation
51
59
52
60
[source,console]
53
61
----
54
62
$ npm install couchbase --save
55
63
----
56
64
57
-
Note: This will download the latest Couchbase Node.js SDK, and add a dependency to your `package.json`.
58
-
65
+
This will download the latest Couchbase Node.js SDK, and add a dependency to your `package.json`.
Information on new features, fixes, known issues, as well as information on how to install older release versions is in the xref:project-docs:sdk-release-notes.adoc[release notes].
67
+
Information on new features, fixes, known issues, as well as information on how to install older release versions is in the xref:project-docs:sdk-release-notes.adoc[release notes], and a fuller installation guide can be found xref:project-docs:sdk-full-installation.adoc[here].
75
68
76
69
=== TypeScript Support
77
70
78
-
NOTE: Follow this section only if you intend to use `TypeScript` instead of `JavaScript`.
79
-
80
-
Since release 3.2, the Node.js SDK has added full support for the link:https://www.typescriptlang.org/[TypeScript] programming language.
71
+
If you intend to use `TypeScript` instead of `JavaScript`, then also do the following:
81
72
82
73
[source,console]
83
74
----
84
75
$ npm install -g typescript ts-node
85
76
----
86
77
87
-
This will install TypeScript globally on your machine and allow you to run commands with the `tsc` cli. You will have noticed that we also install link:https://typestrong.org/ts-node/[ts-node] which is a handy execution utility that will help us run the example later on.
88
-
89
-
Before we can get started, run `tsc --init` in the `node-couchbase-project` directory
90
-
to generate a `tsconfig.json` file. This will set you up with some initial configurations, which should suffice for our purposes.
91
-
92
-
Should you wish to make changes in future you can simply edit the file:
93
-
94
-
[source,json,indent=0]
95
-
----
96
-
include::../examples/example-tsconfig.json[]
97
-
----
98
-
99
-
Note that the example above does not include the generated comments for readability.
78
+
Further details can be found in the xref:project-docs:sdk-full-installation.adoc[full installation page].
100
79
101
80
102
-
== Hello Couchbase
81
+
== Step by Step
103
82
104
83
At this point we want to transition from the terminal to your code editor of choice and point to the directory we have just created named `node-couchbase-project`.
105
84
@@ -392,54 +371,20 @@ GetResult {
392
371
----
393
372
394
373
395
-
== Full Example
396
-
397
-
If you want to copy and paste to run the full example, here it is:
398
-
399
-
[{tabs}]
400
-
====
401
-
JS::
402
-
+
403
-
--
404
-
[source.try-it,nodejs,indent=0]
405
-
----
406
-
include::../examples/start-using.js[tags=**]
407
-
----
408
-
--
409
-
410
-
TS::
411
-
+
412
-
--
413
-
[source,typescript,indent=0]
414
-
----
415
-
include::../examples/start-using.ts[tags=**]
416
-
----
417
-
--
418
-
419
-
Couchbase Capella Sample::
420
-
+
421
-
--
422
-
If you are connecting to https://docs.couchbase.com/cloud/index.html[Couchbase Capella], be sure to get the correct endpoint as well as user, password, and `couchbasecloudbucket` -- and see the <<cloud-connections, Cloud section>>, below.
* If you have a consumer-grade router which has problems with DNS-SRV records review our xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide].
376
+
== Next Steps
439
377
378
+
Now you're up and running, try one of the following:
440
379
380
+
* Our xref:hello-world:sample-application.adoc[Travel Sample Application] demonstrates all the basics you need to know;
381
+
* Explore xref:howtos:kv-operations.adoc[Key Value Operations] against a document database;
382
+
* Or xref:howtos:n1ql-queries-with-sdk.adoc[Query] with our SQL-based N1QL language;
383
+
// * Try longer-running queries with our xref:howtos:analytics-using-sdk.adoc[Analytics Service];
384
+
// * A xref:howtos:full-text-searching-with-sdk.adoc[Full Text Search];
385
+
* Or read up on xref:concept-docs:data-services.adoc[which service fits your use case].
441
386
442
-
== Additional Resources
387
+
=== Additional Resources
443
388
444
389
The API reference is generated for each release and the latest can be found https://docs.couchbase.com/sdk-api/couchbase-node-client/index.html[here].
445
390
@@ -450,5 +395,14 @@ The xref:project-docs:migrating-sdk-code-to-3.n.adoc[Migrating from SDK API 2 to
450
395
Couchbase welcomes community contributions to the Node.js SDK.
451
396
The Node.js SDK source code is available on https://github.com/couchbase/couchnode[GitHub].
452
397
453
-
https://ottomanjs.com/[Ottoman] is an ODM built for Couchbase and Node.js.
454
-
Ottoman's goal is to provide a better development experience while using Couchbase, bringing to developers a reliable tool to build systems that are easy to design, maintain, and scale.
398
+
// https://ottomanjs.com/[Ottoman] is an ODM built for Couchbase and Node.js.
399
+
// Ottoman's goal is to provide a better development experience while using Couchbase, bringing to developers a reliable tool to build systems that are easy to design, maintain, and scale.
400
+
401
+
=== Troubleshooting
402
+
403
+
* Couchbase Server is designed to work in the same WAN or availability zone as the client application.
404
+
If you're running the SDK on your laptop against a Capella cluster, see further information on:
405
+
** Notes on xref:ref:client-settings.adoc#constrained-network-environments[Constrained Network Environments].
** If you have a consumer-grade router which has problems with DNS-SRV records review our xref:howtos:troubleshooting-cloud-connections.adoc#troubleshooting-host-not-found[Troubleshooting Guide].
408
+
* Our https://forums.couchbase.com/c/node-js-sdk/12[community forum] is a great source of help.
:description: Installation instructions for the Couchbase Node.js Client.
3
+
:navtitle: Full Installation
4
+
:page-partial:
5
+
:page-topic-type: project-doc
6
+
:page-toclevels: 2
7
+
8
+
[abstract]
9
+
{description}
10
+
11
+
12
+
The Couchbase Node.js Client will run on any https://github.com/nodejs/Release[supported LTS version of Node.js] -- currently, 12.x, 14.x, 16.x, and 18.x.
13
+
14
+
== Installing the SDK
15
+
16
+
The Couchbase Node.js Client will run on any https://nodejs.org/en/download/[supported LTS version of Node.js].
17
+
18
+
[source,console]
19
+
----
20
+
$ npm install couchbase --save
21
+
----
22
+
23
+
Note: This will download the latest Couchbase Node.js SDK, and add a dependency to your `package.json`.
Information on new features, fixes, known issues, as well as information on how to install older release versions is in the xref:project-docs:sdk-release-notes.adoc[release notes].
41
+
42
+
=== TypeScript Support
43
+
44
+
NOTE: Follow this section only if you intend to use `TypeScript` instead of `JavaScript`.
45
+
46
+
Since release 3.2, the Node.js SDK has added full support for the link:https://www.typescriptlang.org/[TypeScript] programming language.
47
+
48
+
[source,console]
49
+
----
50
+
$ npm install -g typescript ts-node
51
+
----
52
+
53
+
This will install TypeScript globally on your machine and allow you to run commands with the `tsc` cli. You will have noticed that we also install link:https://typestrong.org/ts-node/[ts-node] which is a handy execution utility that will help us run the example later on.
54
+
55
+
Before we can get started, run `tsc --init` in the `node-couchbase-project` directory
56
+
to generate a `tsconfig.json` file. This will set you up with some initial configurations, which should suffice for our purposes.
57
+
58
+
Should you wish to make changes in future you can simply edit the file:
59
+
60
+
[source,json,indent=0]
61
+
----
62
+
include::../examples/example-tsconfig.json[]
63
+
----
64
+
65
+
Note that the example above does not include the generated comments for readability.
These pages cover the 4._x_ and 3._x_ versions of the Couchbase Node.js SDK.
14
14
15
-
For release notes, download links, and installation methods for 2.6 and earlier releases of the Couchbase Node.js Client, please see the xref:2.6@nodejs-sdk::sdk-release-notes.adoc[2.x Node.js Release Notes & Download Archive].
15
+
For release notes, download links, and installation methods for 2.6 and earlier releases of the Couchbase Node.js Client, please see the https://docs-archive.couchbase.com/nodejs-sdk/2.6/sdk-release-notes.html[2.x Node.js Release Notes & Download Archive].
16
16
17
-
The Couchbase Node.js Client will run on any https://github.com/nodejs/Release[supported LTS version of Node.js] -- currently, 12.x, 14.x, and 16.x.
0 commit comments