couchbase-driver

An improved version of the official Couchbase driver.

Installation

npm install couchbase-driver

Overview

A simple alternative driver for Couchbase that wraps the Bucket from existing driver with the following modifications:

• get works on a single key or an array of keys, calling Bucket.getMulti if appropriate. Automatically handles key not found errors and doesn't return an error in that scenario. In case of multiple keys, optionally returns an array of missing keys.
• remove also handles key not found errors more gracefully.
• getAndLock also handles key not found errors more gracefully.
• adds atomic function that tries to do perform getAndLock + transform + specified database operation utilizing CAS in one step until success or maximum retries have occurred. By default we use getAndLock to lock the document while we transform and perform document operation and unlock. Optionally we can use normal get function.
• adds Promise support so that functions call be called with either Node-style callbacks or with Promises.
• adds option to automatically retry operations on Couchbase temporary errors. Uses async.retry and is configurable with the tempRetryTimes, tempRetryInterval and retryTemporaryErrors options (defaults to false).
• adds getServerVersion function that attempts to get the server version from the cluster.

Usage

Creating:

const couchbase = require('couchbase');
const Driver = require('couchbase-driver');
const cluster = new couchbase.Cluster('couchbase://127.0.0.1');
const bucket = cluster.openBucket('default');
const driver = Driver.create(bucket);

Simple retrieval:

driver.get('my_doc_key', (err, res) => {
  if (err) return console.log(err)
  console.dir(res.value)
});

If key does not exist err and res will be undefined.

Getting multiple documents:

driver.get(['my_doc_key_1', 'my_doc_key_2', 'my_missing_doc_key_3'], (err, results, missing) => {
  if (err) return console.log(err);
  if (mising.length > 0) console.dir(missing); // ['my_missing_doc_key_3']
  console.dir(res.value);
});

"Atomic" transformations can be achieved using the atomic function which attempts to do get + transform + specified database operation where CAS in get and the final operation have to match. This uses async.retry until successful or maximum retries have occurred, which can be specified in the Driver construction or as function option parameter.

function transform(doc) {
  doc.foo = 'bar';
  return {
    value: doc,
    action: Driver.OPERATIONS.UPSERT
  };
}
 
driver.atomic('my_doc_key', transform, (err, res) => {
  if(err) return console.dir(err);
  console.dir(res);
});

With promises:

const result = await driver.get('mykey');
console.dir(result.value); // document

Note that with Promise style call and multiple keys we do not get misses.

const results = await driver.get(['mykey1', 'mykey2']);
console.dir(_.map(results, 'value')); // array of documents

API Reference

Driver

A simple alternative driver for Couchbase that wraps the Bucket from existing driver and improves get and remove methods and adds atomic method.

Kind: global class

• Driver
  • new Driver(bucket, options)
  • instance
    • .OPERATIONS
    • .get(keys, options, fn)
    • .getAndLock(key, options, fn)
    • .remove(key, options, fn)
    • .insert(key, value, options, fn)
    • .upsert(key, value, options, fn)
    • .atomic(key, transform, options, fn)
    • .getServerVersion(fn)
  • static
    • .OPERATIONS
    • .OPERATIONS : enum
    • .isKeyNotFound(err)
    • .isTemporaryError(err)
    • .create(bucket, options) ⇒ Driver

new Driver(bucket, options)

Constructs the new instance. This should not be called directly, but rather use Driver.create().

Param	Type	Description
bucket	Object	the Couchbase Bucket
options	Object	Options
options.retryTemporaryErrors	Boolean	Whether to automatically backoff/retry on temporary couchbase errors. Default: false.
options.tempRetryTimes	Number	The number of attempts to make when backing off temporary errors. See async.retry. Default: 5.
options.tempRetryInterval	Number	The time to wait between retries, in milliseconds, when backing off temporary errors . See async.retry. Default: 50.
options.atomicLock	Boolean	Whether to use getAndLock in atomic() or just the standard get. Default: true.
options.atomicRetryTimes	Number	The number of attempts to make within atomic(). See async.retry. Default: 5.
options.atomicRetryInterval	Number	The time to wait between retries, in milliseconds, within atomic(). See async.retry. Default: 0.
options.atomicLock	Boolean	Whether to use getAndLock in atomic() or just the standard get. Default: true.
options.missing	Boolean	Whether to return missing. If false Does not return. Useful for certain contexts. Defalt: true.

driver.OPERATIONS

Get operation enums

Kind: instance property of Driver
Example

const Driver = require('couchbase-driver');
const driver = Driver.create(bucket);
console.log(driver.OPERATIONS.UPSERT);

driver.get(keys, options, fn)

A simplified get. Properly handles key not found errors. In case of multi call, returns array of found and an array of misses.

Kind: instance method of Driver

Param	Type	Description
keys	String | Array	a single key or multiple keys
options	Object	Options for bucket get function
options.missing	Boolean	Whether to return missing. If false Does not return. Useful for certain contexts. This option takes presidence over the one set in constructor. Default: true.
fn	function	callback

Example

driver.get('my_doc_key', (err, res) => {
  if (err) return console.log(err)
  console.dir(res.value)
}

Example

driver.get(['my_doc_key_1', 'my_doc_key_2', 'my_missing_doc_key_3'], (err, results, missing) => {
  if (err) return console.log(err);
  if (mising.length > 0) console.dir(missing); // ['my_missing_doc_key_3']
  console.dir(res.value);
});

driver.getAndLock(key, options, fn)

Our implementation of Bucket.getAndLock that properly ignores key not found errors.

Kind: instance method of Driver

Param	Type	Description
key	String	document key to get and lock
options	Object	Options to pass to Bucket.getAndLock
fn	function	callback

Example

driver.getAndLock('my_doc_key', (err, res) => {
  if (err) return console.log(err);
  console.dir(res.value)
});

driver.remove(key, options, fn)

Our implementation of Bucket.remove that properly ignores key not found errors.

Kind: instance method of Driver

Param	Type	Description
key	String	document key to remove
options	Object	Options to pass to Bucket.remove
fn	function	callback

Example

driver.remove('my_doc_key', (err, res) => {
  if (err) return console.log(err);
});

driver.insert(key, value, options, fn)

Our implementation of Bucket.insert that can recover from temporary errors.

Kind: instance method of Driver

Param	Type	Description
key	String	document key to insert
value	String	document contents to insert
options	Object	Options to pass to Bucket.insert
fn	function	callback

Example

driver.insert('my_doc_key', "doc_contents", (err, res) => {
  if (err) return console.log(err);
});

driver.upsert(key, value, options, fn)

Our implementation of Bucket.upsert that can recover from temporary errors.

Kind: instance method of Driver

Param	Type	Description
key	String	document key to upsert
value	String	document contents to upsert
options	Object	Options to pass to Bucket.upsert
fn	function	callback

Example

driver.upsert('my_doc_key', "doc_contents", (err, res) => {
  if (err) return console.log(err);
});

driver.atomic(key, transform, options, fn)

Performs an "atomic" operation where it tries to first get the document given the key, then perform the function transform on the value and then write using the CAS value in the upsert. If the final document operation fails due to a CAS error, the whole process is retried.

Kind: instance method of Driver

Param	Type	Description
key	String	document key
transform	function	synchronous function to be performend on the document value. Function accepts the document or undefined if the document was not found. The function should perform any necessary mutation and return an object with value and action. value is the new value of the document. action should be one of OPERATIONS specifying the action to take with the new value.
options	String	Options
options.atomicRetryTimes	Number	The number of attempts to make within atomic(). See async.retry. Default: 5.
options.atomicRetryInterval	Number	The time to wait between retries, in milliseconds, within atomic(). See async.retry. Default: 0.
options.atomicLock	Boolean	Whether to use getAndLock in atomic() or just the standard get. Default: true.
options.saveOptions	Object	bucket save options
fn	function	callback

Example

function transform(doc) {
  doc.foo = 'bar';
  return {
    value: doc,
    action: OPERATIONS.UPSERT
  };
}
 
driver.atomic('my_doc_key', transform, (err, res) => {
  if(err) return console.log(err);
  console.dir(res);
});

driver.getServerVersion(fn)

Attempts to get the lowest couchbase server version from the nodes in the cluster.

Warning This depends on undocumented internals of Node.js couchbase library

Kind: instance method of Driver

Param	Type	Description
fn	function	callback

Example

driver.getServerVersion((err, version) => {
  if(err) return console.log(err);
  console.log(version);
});

Driver.OPERATIONS

Get operation enums

Kind: static property of Driver
Example

const Driver = require('couchbase-driver');
console.log(Driver.OPERATIONS.UPSERT);

Driver.OPERATIONS : enum

Enum for Database operations

Kind: static enum of Driver
Read only: true
Properties

Name	Type	Default	Description
UPSERT	string	"upsert"	Upsert operation
REMOVE	string	"remove"	Remove operation
NOOP	string	"noop"	No operation or action

Driver.isKeyNotFound(err)

Determines if error is a "key not found" error

Kind: static method of Driver

Param	Type	Description
err	Error	the error to check

Example

Driver.isKeyNotFound(err);

Driver.isTemporaryError(err)

Determines if error is a "Temporary" error https://developer.couchbase.com/documentation/server/current/sdk/nodejs/handling-error-conditions.html

Kind: static method of Driver

Param	Type	Description
err	Error	the error to check

Example

Driver.isTemporaryError(err);

Driver.create(bucket, options) ⇒ Driver

Create a Driver object by wrapping the Couchbase bucket and creates a new Driver instance and adds Promise support to the instance.

Kind: static method of Driver

Param	Type	Description
bucket	Object	The Couchbase Bucket instance to wrap.
options	Object	Options
options.retryTemporaryErrors	Boolean	Whether to automatically backoff/retry on temporary couchbase errors. Default: false.
options.tempRetryTimes	Number	The number of attempts to make when backing off temporary errors. See async.retry. Default: 5.
options.tempRetryInterval	Number	The time to wait between retries, in milliseconds, when backing off temporary errors . See async.retry. Default: 50.
options.atomicRetryTimes	Number	The number of attempts to make within atomic(). See async.retry. Default: 5.
options.atomicRetryInterval	Number	The time to wait between retries, in milliseconds, within atomic(). See async.retry. Default: 0.
options.atomicLock	Boolean	Whether to use getAndLock in atomic() or just the standard get. Default: true.

Example

const couchbase = require('couchbase');
const Driver = require('couchbase-driver');
const cluster = new couchbase.Cluster('couchbase://127.0.0.1');
const bucket = cluster.openBucket('default');
const driver = Driver.create(bucket);

Debug logging

debug package is used for debug logging.

DEBUG=couchbase-driver node app.js

License

Copyright 2015 Bojan D.

Licensed under the MIT License.