1# Couchnode - Fast and Native Node.JS Client for Couchbase
2
3
4This library allows you to connect to a Couchbase cluster from node.js.
5It is very fast and utilizes the binary protocol via a native node.js
6addon.
7
8## Basic installation and usage
9
10To install this module, we'll assume you are using
11[NPM](https://npmjs.org).  However it is not as simple as a regular
12JavaScript module, as it depends on the C-library for Couchbase
13clients, [libcouchbase](https://github.com/couchbase/libcouchbase).
14Libcouchbase also powers other dynamic language clients, such as Ruby
15and PHP, so if you've worked with those clients you should feel right
16at home.
17
18First, you must install libcouchbase (version 2.1 or greater)
19
20On a mac, you can use homebrew this should be as easy as running:
21
22    brew install libcouchbase
23
24
25### Building from Git
26Since you're reading this README, we're assuming you're going to be building
27from source. In this case, `cd` into the source root directory and run
28
29    npm install --debug
30
31If your libcouchbase prefix is not inside the linker path, you can pass the
32`--couchbase-root` option over to `npm` like so:
33
34    npm install --debug --couchbase-root=/sources/libcouchbase/inst
35
36Note that `--couchbase-root` also sets the `RPATH` flags and assumes you are
37using an `ELF`-based platform (i.e. not OS X). To build on OS X, edit the
38bindings.gyp to replace `-rpath` with the appropriate linker flags.
39
40
41## API description
42
43### Connecting.
44
45To use this module, first do:
46
47```javascript
48    var Couchbase = require('couchbase');
49    var cb = new Couchbase.Connection({bucket: "default"}, function(err) { });
50```
51
52Note that you do not need to wait for the connection callback in order to start
53performing operations.
54
55### Dealing with keys and values
56
57For API illustration, the best bet at the current time is [a small
58example http hit
59counter](https://github.com/couchbase/couchnode/tree/master/example.js). There
60is also [the test suite which shows more details.]
61(https://github.com/couchbase/couchnode/tree/master/tests)
62
63The basic method summary is:
64
65```javascript
66    cb.get(key, function (err, result) {
67      console.log("Value for key is: " + result.value);
68    });
69
70    cb.set(key, value, function (err, result) {
71      console.log("Set item for key with CAS: " + result.cas);
72    });
73
74    // Then the similar methods of add, replace, append, prepend:
75    cb.add(key, value, function (err, result) {});
76    cb.replace(key, value, function (err, result) {});
77    cb.append(key, value, function (err, result) {});
78    cb.prepend(key, value, function (err, result) {});
79
80    // Increment or decrement a numeric value:
81    cb.incr(key, { delta: 42, initial: 20 }, function(err, result) {
82      console.log("New value for counter is: " + result.value);
83    });
84    cb.decr(key, { delta: 99, default: 1024 }, function (err, result) {});
85
86    // Remove items
87    cb.remove(key, function (err, result));
88
89    // Set multiple items:
90    cb.setMulti({
91      key1: { value: value1 },
92      // You can set per-key options, like expiry as well.
93      key2: { value: value2, expiry: 1000 } },
94
95      // Use the "spooled" option to ensure the callback is invoked only once
96      // with the result for all the items.
97      { expiry: 300, spooled: true  },
98      function (err, results) {
99        console.dir(results);
100      }
101    );
102
103    // Get multiple items:
104    // Note we don't pass options and don't use spooled, so the callback is
105    // invoked for each key.
106    cb.getMulti(["key1", "key2", "key3"], null, function(err, result) {
107      console.log("Got result for key.. " + result.value);
108    });
109```
110
111## Running Tests
112
113To run the unit tests built into the Node.js driver.  Make sure you have
114mocha installed globally on your system, then execute mocha in the root
115directory of your couchnode installation.
116
117## Contributing changes
118
119See CONTRIBUTING.md
120