16bfc6f19SBrett Lawson# Couchbase Node.js Client
2a8b965b6STrond Norbye
3d7189b90SBrett LawsonThe Node.js SDK library allows you to connect to a Couchbase cluster from 
4d7189b90SBrett LawsonNode.js. It is a native Node.js module and uses the very fast libcouchbase 
5d7189b90SBrett Lawsonlibrary to handle communicating to the cluster over the Couchbase binary
6d7189b90SBrett Lawsonprotocol.
7e95076f4STrond Norbye
8495d902bSChris Anderson
96bfc6f19SBrett Lawson## Useful Links
10495d902bSChris Anderson
11d7189b90SBrett LawsonSource - [http://github.com/couchbase/couchnode](http://github.com/couchbase/couchnode)
1260ea65d1SMark Nunberg
13d7189b90SBrett LawsonBug Tracker - [http://www.couchbase.com/issues/browse/JSCBC](http://www.couchbase.com/issues/browse/JSCBC)
14495d902bSChris Anderson
156b885a9aSRichard SmedleyCouchbase Developer Portal - [https://docs.couchbase.com/](https://docs.couchbase.com/nodejs-sdk/2.6/start-using-sdk.html)
16495d902bSChris Anderson
176b885a9aSRichard SmedleyRelease 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)
18495d902bSChris Anderson
196bfc6f19SBrett Lawson## Installing
20495d902bSChris Anderson
216bfc6f19SBrett LawsonTo install the lastest release using npm, run:
22d7189b90SBrett Lawson```bash
236bfc6f19SBrett Lawsonnpm install couchbase
246bfc6f19SBrett Lawson```
25495d902bSChris Anderson
26d7189b90SBrett LawsonTo install the development version directly from github, run:
27d7189b90SBrett Lawson```bash
28d7189b90SBrett Lawsonnpm install "git+https://github.com/couchbase/couchnode.git#master"
296bfc6f19SBrett Lawson```
30320d972bSPatrick Heneise
31320d972bSPatrick Heneise
326bfc6f19SBrett Lawson## Introduction
33495d902bSChris Anderson
34d7189b90SBrett LawsonConnecting to a Couchbase bucket is as simple as creating a new `Cluster` 
35fab72700SBrett Lawsoninstance to represent the `Cluster` you are using, and then using the
36fab72700SBrett Lawson`bucket` and `collection` commands against this to open a connection to
37fab72700SBrett Lawsonopen your specific bucket and collection.  You are able to execute most
38fab72700SBrett Lawsonoperations immediately, and they will be queued until the connection is
39fab72700SBrett Lawsonsuccessfully established.
40320d972bSPatrick Heneise
41d7189b90SBrett LawsonHere is a simple example of instantiating a connection, adding a new document
426bfc6f19SBrett Lawsoninto the bucket and then retrieving its contents:
43baaf682fSTrond Norbye
446bfc6f19SBrett Lawson```javascript
45d7189b90SBrett Lawsonvar couchbase = require('couchbase');
46fab72700SBrett Lawsonvar cluster = new couchbase.Cluster('couchbase://127.0.0.1', {
47fab72700SBrett Lawson  username: 'username',
48fab72700SBrett Lawson  password: 'password',
49d7189b90SBrett Lawson});
50fab72700SBrett Lawsonvar bucket = cluster.bucket('default');
51fab72700SBrett Lawsonvar coll = bucket.defaultCollection();
5260ea65d1SMark Nunberg
53fab72700SBrett Lawsoncoll.upsert('testdoc', {name:'Frank'}, (err, res) => {
5417c8ee75SBrett Lawson  if (err) throw err;
5517c8ee75SBrett Lawson
56fab72700SBrett Lawson  coll.get('testdoc', (err, res) => {
5717c8ee75SBrett Lawson    if (err) throw err;
5817c8ee75SBrett Lawson
59fab72700SBrett Lawson    console.log(res.value);
6017c8ee75SBrett Lawson    // {name: Frank}
6117c8ee75SBrett Lawson  });
62fab72700SBrett Lawson});
636e8e1a58SBrett Lawson```
646e8e1a58SBrett Lawson
656e8e1a58SBrett Lawson
666bfc6f19SBrett Lawson## Documentation
6760ea65d1SMark Nunberg
686bfc6f19SBrett LawsonAn extensive documentation is available on the Couchbase website.  Visit our
696bfc6f19SBrett Lawson[Node.js Community](http://couchbase.com/communities/nodejs) on
706bfc6f19SBrett Lawsonthe [Couchbase](http://couchbase.com) website for the documentation as well as
716bfc6f19SBrett Lawsonnumerous examples and samples.
7260ea65d1SMark Nunberg
7360ea65d1SMark Nunberg
746bfc6f19SBrett Lawson## Source Control
7560ea65d1SMark Nunberg
766bfc6f19SBrett LawsonThe source code is available at
776bfc6f19SBrett Lawson[https://github.com/couchbase/couchnode](https://github.com/couchbase/couchnode).
786bfc6f19SBrett LawsonOnce you have cloned the repository, you may contribute changes through our
796bfc6f19SBrett Lawsongerrit server.  For more details see
806bfc6f19SBrett Lawson[CONTRIBUTING.md](https://github.com/couchbase/couchnode/blob/master/CONTRIBUTING.md).
8160ea65d1SMark Nunberg
82d7189b90SBrett LawsonTo execute our test suite, run `make test` from the root directory.
83d7189b90SBrett Lawson
84d7189b90SBrett LawsonTo execute our code coverage, run `make cover` from the root directory.
8560ea65d1SMark Nunberg
86d7189b90SBrett LawsonIn addition to the full test suite and full code coverage, you may additionally
87d7189b90SBrett Lawsonexecute a subset of the tests which excludes slow-running tests for quick
88d7189b90SBrett Lawsonverifications.  These can be run through `make fasttest` and `make fastcover`
89d7189b90SBrett Lawsonrespectively.
90fac5ad62SBrett Lawson
916bfc6f19SBrett Lawson## License
926bfc6f19SBrett LawsonCopyright 2013 Couchbase Inc.
93fac5ad62SBrett Lawson
946bfc6f19SBrett LawsonLicensed under the Apache License, Version 2.0.
9560ea65d1SMark Nunberg
966bfc6f19SBrett LawsonSee
976bfc6f19SBrett Lawson[LICENSE](https://github.com/couchbase/couchnode/blob/master/LICENSE)
986bfc6f19SBrett Lawsonfor further details.
99