1# Couchbase Node.js Client
2
3This library allows you to connect to a Couchbase cluster from Node.js.
4It is a native Node.js module and uses the very fast libcouchbase library to
5handle communicating to the cluster over the Couchbase binary protocol.
6
7[![Build Status](http://cb.br19.com:86/buildStatus/icon?job=couchnode)](http://cb.br19.com:86/job/couchnode/)
8
9
10## Useful Links
11
12Source - http://github.com/couchbase/couchnode
13
14Bug Tracker - http://www.couchbase.com/issues/browse/JSCBC
15
16Couchbase Node.js Community - http://couchbase.com/communities/nodejs
17
18
19## Installing
20
21To install the lastest release using npm, run:
22```
23npm install couchbase
24```
25
26To install the in development version directly from github, run:
27```
28npm install git+https://github.com/couchbase/couchnode.git
29```
30
31
32## Introduction
33
34Connecting to a Couchbase bucket is as simple as creating a new Connection
35instance.  Once you are connect, you may execute any of Couchbases' numerous
36operations against this connection.
37
38Here is a simple example of instantiating a connection, setting a new document
39into the bucket and then retrieving its contents:
40
41```javascript
42    var couchbase = require('couchbase');
43    var db = new couchbase.Connection({bucket: "default"}, function(err) {
44      if (err) throw err;
45
46      db.set('testdoc', {name:'Frank'}, function(err, result) {
47        if (err) throw err;
48
49        db.get('testdoc', function(err, result) {
50          if (err) throw err;
51
52          console.log(result.value);
53          // {name: Frank}
54        });
55      });
56    });
57```
58
59
60## Mock Testing
61
62As part of this library, we include a mock version of the client that supports
63nearly the exact same feature set as the library itself, but which does not
64require that a server be configured.  Note that these Mock connections currently
65are per-instance, if another connection is instantiated, none of the data will
66be shared.
67
68Using the Mock is as simple as this:
69```javascript
70    var couchbase = require('couchbase').Mock;
71    var db = new couchbase.Connection();
72```
73
74
75## Documentation
76
77An extensive documentation is available on the Couchbase website.  Visit our
78[Node.js Community](http://couchbase.com/communities/nodejs) on
79the [Couchbase](http://couchbase.com) website for the documentation as well as
80numerous examples and samples.
81
82
83## Source Control
84
85The source code is available at
86[https://github.com/couchbase/couchnode](https://github.com/couchbase/couchnode).
87Once you have cloned the repository, you may contribute changes through our
88gerrit server.  For more details see
89[CONTRIBUTING.md](https://github.com/couchbase/couchnode/blob/master/CONTRIBUTING.md).
90
91To execute our test suite, run `make test` from your checked out root directory.
92
93
94## License
95Copyright 2013 Couchbase Inc.
96
97Licensed under the Apache License, Version 2.0.
98
99See
100[LICENSE](https://github.com/couchbase/couchnode/blob/master/LICENSE)
101for further details.
102