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