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 Node.js Community - [http://couchbase.com/communities/nodejs](http://couchbase.com/communities/nodejs)
16
17
18## Installing
19
20To install the lastest release using npm, run:
21```bash
22npm install couchbase
23```
24
25To install the development version directly from github, run:
26```bash
27npm install "git+https://github.com/couchbase/couchnode.git#master"
28```
29
30
31## Introduction
32
33Connecting to a Couchbase bucket is as simple as creating a new `Cluster` 
34instance to represent the `Cluster` you are using, and then executing
35`openBucket` against this to open a connection to you specific bucket.  You
36are able to execute most operations immediately, and they will be queued
37until the connection is successfully established.
38
39Here is a simple example of instantiating a connection, adding a new document
40into the bucket and then retrieving its contents:
41
42```javascript
43var couchbase = require('couchbase');
44var cluster = new couchbase.Cluster('couchbase://127.0.0.1');
45var bucket = cluster.openBucket('default');
46
47bucket.upsert('testdoc', {name:'Frank'}, function(err, result) {
48  if (err) throw err;
49
50  bucket.get('testdoc', function(err, result) {
51    if (err) throw err;
52
53    console.log(result.value);
54    // {name: Frank}
55  });
56});
57```
58
59
60## Mock Testing
61
62As part of the core library, we additionally include a powerful Mock version
63of the library which supports a significant set of the features that are
64available when connected to a real Couchbase Server.
65
66As part of this library, we include a mock version of the client that supports
67nearly the exact same feature set as the library itself, but which does not
68require that a server be configured.  Note that these Mock connections currently
69are per-instance, if another connection is instantiated, none of the data will
70be shared.
71
72Using the Mock is as simple as this:
73```javascript
74var couchbase = require('couchbase').Mock;
75var db = new couchbase.Cluster();
76var bucket = cluster.openBucket();
77
78bucket.upsert('testdoc', {name:'Frank'}, function(err, result) {
79  if (err) throw err;
80
81  bucket.get('testdoc', function(err, result) {
82    if (err) throw err;
83
84    console.log(result.value);
85    // {name: Frank}
86  });
87```
88
89
90## Documentation
91
92An extensive documentation is available on the Couchbase website.  Visit our
93[Node.js Community](http://couchbase.com/communities/nodejs) on
94the [Couchbase](http://couchbase.com) website for the documentation as well as
95numerous examples and samples.
96
97
98## Source Control
99
100The source code is available at
101[https://github.com/couchbase/couchnode](https://github.com/couchbase/couchnode).
102Once you have cloned the repository, you may contribute changes through our
103gerrit server.  For more details see
104[CONTRIBUTING.md](https://github.com/couchbase/couchnode/blob/master/CONTRIBUTING.md).
105
106To execute our test suite, run `make test` from the root directory.
107
108To execute our code coverage, run `make cover` from the root directory.
109
110In addition to the full test suite and full code coverage, you may additionally
111execute a subset of the tests which excludes slow-running tests for quick
112verifications.  These can be run through `make fasttest` and `make fastcover`
113respectively.
114
115## License
116Copyright 2013 Couchbase Inc.
117
118Licensed under the Apache License, Version 2.0.
119
120See
121[LICENSE](https://github.com/couchbase/couchnode/blob/master/LICENSE)
122for further details.
123