1# Couchbase Node.js Client
2
3The Node.js SDK library allows you to connect to a Couchbase cluster from 
4Node.js. It is a native Node.js module and uses the very fast libcouchbase 
5library to handle communicating to the cluster over the Couchbase binary
6protocol.
7
8
9## Useful Links
10
11Source - [http://github.com/couchbase/couchnode](http://github.com/couchbase/couchnode)
12
13Bug Tracker - [http://www.couchbase.com/issues/browse/JSCBC](http://www.couchbase.com/issues/browse/JSCBC)
14
15Couchbase Developer Portal - [https://docs.couchbase.com/](https://docs.couchbase.com/nodejs-sdk/2.6/start-using-sdk.html)
16
17Release Notes - [https://docs.couchbase.com/nodejs-sdk/2.6/relnotes-nodejs-sdk.html](https://docs.couchbase.com/nodejs-sdk/2.6/relnotes-nodejs-sdk.html)
18
19## Installing
20
21To install the lastest release using npm, run:
22```bash
23npm install couchbase
24```
25
26To install the development version directly from github, run:
27```bash
28npm install "git+https://github.com/couchbase/couchnode.git#master"
29```
30
31
32## Introduction
33
34Connecting to a Couchbase bucket is as simple as creating a new `Cluster` 
35instance to represent the `Cluster` you are using, and then using the
36`bucket` and `collection` commands against this to open a connection to
37open your specific bucket and collection.  You are able to execute most
38operations immediately, and they will be queued until the connection is
39successfully established.
40
41Here is a simple example of instantiating a connection, adding a new document
42into the bucket and then retrieving its contents:
43
44```javascript
45var couchbase = require('couchbase');
46var cluster = new couchbase.Cluster('couchbase://127.0.0.1', {
47  username: 'username',
48  password: 'password',
49});
50var bucket = cluster.bucket('default');
51var coll = bucket.defaultCollection();
52
53coll.upsert('testdoc', {name:'Frank'}, (err, res) => {
54  if (err) throw err;
55
56  coll.get('testdoc', (err, res) => {
57    if (err) throw err;
58
59    console.log(res.value);
60    // {name: Frank}
61  });
62});
63```
64
65
66## Documentation
67
68An extensive documentation is available on the Couchbase website.  Visit our
69[Node.js Community](http://couchbase.com/communities/nodejs) on
70the [Couchbase](http://couchbase.com) website for the documentation as well as
71numerous examples and samples.
72
73
74## Source Control
75
76The source code is available at
77[https://github.com/couchbase/couchnode](https://github.com/couchbase/couchnode).
78Once you have cloned the repository, you may contribute changes through our
79gerrit server.  For more details see
80[CONTRIBUTING.md](https://github.com/couchbase/couchnode/blob/master/CONTRIBUTING.md).
81
82To execute our test suite, run `make test` from the root directory.
83
84To execute our code coverage, run `make cover` from the root directory.
85
86In addition to the full test suite and full code coverage, you may additionally
87execute a subset of the tests which excludes slow-running tests for quick
88verifications.  These can be run through `make fasttest` and `make fastcover`
89respectively.
90
91## License
92Copyright 2013 Couchbase Inc.
93
94Licensed under the Apache License, Version 2.0.
95
96See
97[LICENSE](https://github.com/couchbase/couchnode/blob/master/LICENSE)
98for further details.
99