Class: Connection

Connection

An object representing a connection to a Couchbase cluster. Normally, your application should only need to create one of these per process and use it contiously. Operations are executed asynchronously and pipelined when possible.

new Connection(options, callback)

Parameters:
Name Type Argument Description
options object <optional>
A dictionary of options to use. Additionally, other options may be passed in this object which correspond to the various settings (see their documentation). For example, it may be helpful to set timeout properties *before* connection.
Properties
Name Type Argument Description
host string | array a string or an array of strings indicating the hosts to connect to. If the value is an array, all the hosts in the array will be tried until one of them succeeds. Default is 'localhost'
bucket string <optional>
The bucket to connect to. If not specified, the default is 'default'.
password string <optional>
Password for the bucket, if the bucket is password-protected
callback Function A callback that will be invoked when the instance is actually connected to the server. Note that this isn't actually required - however if the connection fails, an exception will be thrown if the callback is not provided. Note that it is safe to perform operations on the Couchbase object before the connect callback is invoked. In this case, the operations are queued until the connection is ready (or an unrecoverable error has taken place).
Source:

Members

clientVersion :Array

Get information about the Couchnode version (i.e. this library).
Type:
  • Array
Source:

connectionTimeout :number

Sets or gets the connection timeout in msecs. This is the timeout value used when connecting to the configuration port during the initial connection (in this case, use this as a key in the 'options' parameter in the constructor) and/or when Connection attempts to reconnect in-situ (if the current connection has failed).
Type:
  • number
Default Value:
  • 5000
Source:

lcbVersion :Array

Get information about the libcouchbase version being used.
Type:
  • Array
Source:

operationTimeout :number

Sets or gets the operation timeout in msecs. The operation timeout is the time that Connection will wait for a response from the server. If the response is not received within this time frame, the operation is bailed out with an error.
Type:
  • number
Default Value:
  • 2500
Source:

serverNodes :Array.<String>

Get an array of active nodes in the cluster.
Type:
  • Array.<String>
Source:

Methods

add(key, value, options, callback)

Like Connection#set but will fail if the key already exists.
Parameters:
Name Type Argument Description
key string
value string | object | Buffer
options object <optional>
Properties
Name Type Description
expiry integer
flags integer
format string | integer
callback KeyCallback
Source:
See:

addMulti(kv, options, callback)

Multi version of add.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

append(key, fragment, options, callback)

Like Connection#set, but instead of setting a new value, it appends data to the existing value. Note that this function only makes sense when the stored item is a string; 'appending' to JSON may result in parse errors when the value is later retrieved.
Parameters:
Name Type Argument Description
key string
fragment string | object The data to append
options object <optional>
Properties
Name Type Description
expiry integer
flags integer
cas CAS
format string | integer
callback KeyCallback
Source:
See:

appendMulti(kv, options, callback)

Multi version of append.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

decr(key, options)

Decrements the key's numeric value. Follows same semantics as Connection#incr with the exception that the offset parameter is the amount by which to decrement the existing value.
Parameters:
Name Type Argument Description
key string
options object <optional>
Properties
Name Type Description
offset integer
initial integer
expiry integer
callback. KeyCallback
Source:
See:

decrMulti(kv, options, callback)

Decrement multiple keys. Multi variant of Connection#decr.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

get(key, options, callback)

Get a key from the cluster.
Parameters:
Name Type Argument Description
key string the key to retrieve
options object <optional>
additional options for this operation
Properties
Name Type Description
expiry integer A new expiration time for the item. This makes the Get operation into a Get-And-Touch operation.
raw boolean Instructs the library not to attempt conversion based on the flags, and return the value as-is in byte form. The resultant output will be stored as a Buffer object.
callback KeyCallback the callback to be invoked when complete. The second argument of the callback shall contain the following fields:
Source:
See:

getDesignDoc(name, callback)

Gets a design document from the server.
Parameters:
Name Type Description
name string The name of the design document to retrieve
callback DDocCallback
Source:

getMulti(kv, options, callback)

Get multiple keys at once.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

incr(key, value, options, callback)

Increments the key's numeric value. This is an atomic operation. Note that JavaScript does not support 64 bit integers (while libcouchbase and the server does). You may end up receiving an invalid value if the existing number is greater than 64 bits. Note that as this operation is atomic, no 'cas' parameter is provided. If the key already exists but its value is not numeric, an error will be provided to the callback
Parameters:
Name Type Argument Description
key string the key to increment
value
options object <optional>
Options are:
Properties
Name Type Description
offset integer The amount by which to increment.
initial integer The initial value to use if the key does not exist. If this is not supplied and the key does not exist, the operation will fail
expiry integer the expiration time for the key
callback KeyCallback Invoked with the following fields in the response:
Properties
Name Type Description
value integer the current value of the item
cas CAS
format string | integer
Default Value:
  • 1
Source:
See:

incrMulti(kv, options, callback)

Increment multiple keys. Multi variant of Connection#incr.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

lock(key, options, callback)

Lock the object on the server and retrieve it. When an object is locked, its CAS changes and subsequent operations on the object (without providing the current CAS) will fail until the lock is no longer held. This function behaves identically to get in that it will return the value. It differs in that the key is also locked. This ensures that attempts by other client instances to access this item while the lock is held will fail. Once locked, an item can be unlocked either by explicitly calling Connection#unlock or by performing a storage operation (e.g. set, replace, append) with the current CAS value. Note that any retrieval operations will fail while an item is locked.
Parameters:
Name Type Argument Description
key string the item to lock
options object <optional>
options to use.
Properties
Name Type Description
expiry integer The duration of time the lock should be held for. If this value is not provided, it will use the default server-side lock duration which is 15 seconds. Note that the maximum duration for a lock is 30 seconds, and if a higher value is specified, it will be rounded to this number.
callback KeyCallback The result in this callback contains the same fields as a Connection#get operation.
Source:

lockMulti(kv, options, callback)

Multi version of lock.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

prepend(key, fragment, options, callback)

Like Connection#append, but prepends data to the existing value.
Parameters:
Name Type Argument Description
key string
fragment string | Buffer The data to prepend
options object <optional>
Properties
Name Type Description
expiry integer
flags integer
cas CAS
format string | integer
callback KeyCallback
Source:
See:

prependMulti(kv, options, callback)

Multi version of prepend.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

remove(key, options, callback)

Delete a key on the server.
Parameters:
Name Type Argument Description
key string the key to remove
options object <optional>
the options to use.
Properties
Name Type Description
cas CAS The CAS value to check. If the item on the server contains a different CAS value, the operation will fail.
callback KeyCallback
Source:
See:

removeDesignDoc(name, callback)

Deletes a design document from the server.
Parameters:
Name Type Description
name string The name of the design document to delete
callback DDocCallback
Source:

removeMulti(kv, options, callback)

Remove multiple keys at once.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:

replace(key, value, options, callback)

Like Connection#set, but will only succeed if the key exists (i.e. the inverse of add()).
Parameters:
Name Type Argument Description
key string
value string | object | Buffer
options object <optional>
Properties
Name Type Description
expiry integer
flags integer
cas CAS
format string | integer
callback KeyCallback
Source:
See:

replaceMulti(kv, options, callback)

Multi version of replace.
Parameters:
Name Type Argument Description
kv object
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

set(key, value, options, callback)

Store a key on the server, setting its value.
Parameters:
Name Type Argument Description
key string the key to store
value string | object | Buffer the value the key shall contain Note that if the options already contain a 'value' field (e.g. from a callback invoked after a get or getEx operation), this parameter is ignored.
options object <optional>
Options are:
Properties
Name Type Description
cas CAS value to use. If the CAS on the server does not match this value, it is assumed the object has been modified previously, and should be re-fetched (via ConnectionConnection#get and re-transformed). Note that this check only happens if this option is set.
expiry integer set initial expiration for the item
flags integer 32 bit value to use for the item. Note that this value is not currently used by couchnode, but is used by other clients and may be used by Couchnode in the future. The only use case for setting this value should be intra-client compatibility. Conventionally this value is used for indicating the storage format of the value.
format integer | string Format specifier to use for storing this value. The format may be one of the following..
callback KeyCallback
Source:
See:

setDesignDoc(name, data, callback)

Sets a design document to the server. The document data passed to this function is expected to be a key,value pair of view names and objects containing the map and reduce functions for the view. See the views chapter of the Couchbase Documentation for more information.
Parameters:
Name Type Description
name string The name of the design document to set
data object An object representing the views to be included in this design document
callback DDocCallback
Source:

setMulti(kv, options, callback)

Set multiple items.
Parameters:
Name Type Argument Description
kv object a dictionary of { key: options } where options is in the format of set with the following differences:
Properties
Name Type Description
value object | string | Buffer the value to use for this key. This must be present.
options object <optional>
Options to use affecting all key-value pairs. This can be used to specify common options for all keys rather than applying them individually to each key's options. Note that if a key option conflicts with a global option, then the key option w *ins. Additionally, one extra global-only option may be specified:
Properties
Name Type Description
spooled boolean If this option is present and is set to false, then the callback parameter will be treated as a KeyCallback which will be invoked once for each key.
callback MultiCallback | KeyCallback
Source:

shutdown()

Shuts down this connection.
Source:

stats(key, callback)

Retrieves various server statistics.
Parameters:
Name Type Argument Description
key string <optional>
An optional stats key to specify which groups of statistics are returned. If not specified, returns the "default" statistics. Consult the server documentation for more information on which statistic groups are available.
callback StatsCallback a callback to be invoked.
Source:

strError(code) → {string}

Parameters:
Name Type Description
code integer a code of an error thrown by the library
Source:
Returns:
The string description
Type
string

touch(key, options)

Update the item's expiration time in the cluster.
Parameters:
Name Type Argument Description
key string the key to retrieve
options object <optional>
additional options for this operation
Properties
Name Type Description
expiry integer The expiration time to use. If no value is provided, then the current expiration time is cleared and the key is set to never expire. Otherwise, the key is updated to expire in the value provided, in seconds.
cas CAS
callback. KeyCallback
Source:
See:
  • Connection#touchMulti

unlock(key, options)

Unlock a previously locked item on the server.
Parameters:
Name Type Description
key string the key to unlock
options object the options to use.
Properties
Name Type Description
cas CAS mandatory parameter, which should contain the CAS provided by a previous lock operation
Source:
See:

unlockMulti(kv, options, callback)

Unlock multiple keys at once. Multi variant of unlock
Parameters:
Name Type Argument Description
kv object Typically this will be the result of a previous call to Connection#lockMulti - as the CAS is already in the result.
options object <optional>
callback MultiCallback | KeyCallback
Source:
See:

view(ddoc, name, query) → {ViewQuery}

Returns a ViewQuery object representing the requested view. See the views chapter of the Couchbase Documentation for more information.
Parameters:
Name Type Description
ddoc string The name of the design document to query
name string The name of the view to query
query object Query options
Source:
Returns:
A ViewQuery representing the requested view
Type
ViewQuery