nginx-couchbase-module (0.3.1)

Description

This module translates requests to Couchbase cluster, specified with directive couchbase_pass, and returns result back to the client.

By default, the module can use information, accessible in the request, to construct data packet. As a key it use part of the request URI, which remains after stripping the name of the matching location.

location /cache/ {
    couchbase_pass;
}

In example above, if address /cache/example.html will be requested from the server, then the key will be example.html.

To choose command, which will be sent to Couchbase Server, it use HTTP method. The table below shows correspondence commands to the methods.

And, eventually, to pick the value (for mutation operations) it uses body of the HTTP request.

Information, about how to override aforementioned behaviour using variables, can be found below: set $couchbase_cmd, set $couchbase_key, set $couchbase_val.

Configuration Directives

Specifies connection parameters for the cluster. Parameter address represents comma-separated pairs host:port, where :port might be omitted in which case default port (8091) will be used:

location /cache/ {
    couchbase_pass example.com:8091,example.org bucket=app;
}

Sets timeout for establishing connection to Couchbase Server.

Sets timeout for data communication with Couchbase Server.

Variables

Sets command type, executed for this location. For example, command can be taken from query string (/cache/?cmd=append):

location /cache/ {
    set $couchbase_cmd $arg_cmd;
    couchbase_pass;
}

Or command can be fixed string:

location /cache/ {
    set $couchbase_cmd 'append';
    couchbase_pass;
}

As for version 0.3.1 supported the following commands: get, set, add, replace, append, prepend, delete. About corresponding HTTP methods to commands, read section “Description”.

Sets key for the document in this location. For example, key can be taken from query string (/cache/?key=foo):

location /cache/ {
    set $couchbase_key $arg_key;
    couchbase_pass;
}

Or key can be fixed string:

location /cache/ {
    set $couchbase_key 'foo';
    couchbase_pass;
}

Picks the value for the document in this location. For example, value might be taken from query string (/cache/?value=foo%0a):

location /cache/ {
    set $couchbase_val $arg_val;
    couchbase_pass;
}

Or value can be fixed string:

location /cache/ {
    set $couchbase_val 'foo%a';
    couchbase_pass;
}

Note, that if the value specified by $couchbase_key, then it will be considered URL-encoded, and will be decoded back.

This variable stores CAS value of the document. This value changes on each mutation of the document. Therefore it can be used for optimistic locking.

location /cache/ {
    set $couchbase_key $arg_key;
    set $couchbase_val $arg_val;
    set $couchbase_cmd $arg_cmd;
    set $couchbase_cas $arg_cas;
    couchbase_pass;
    add_header X-CAS $couchbase_cas;
}

With configuration above, the server will set header X-CAS with actual CAS value. This value can be used for subsequent updates, and if someone managed to changed it before, the server will respond with code 409 Conflict, so that the client have to update local document and try again with new CAS.

System Requirements

This module has been tested with nginx v1.3.7, v1.2.6 and v1.4.0.

Download

Last version is 0.3.1: nginx-couchbase-module-0.3.1.tar.gz.

Project repository: https://github.com/couchbaselabs/couchbase-nginx-module

Usage

Create build directory, download and unpack all dependencies there:

mkdir nginx-couchbase
cd nginx-couchbase
wget http://nginx.org/download/nginx-1.3.7.tar.gz
wget http://packages.couchbase.com/clients/c/libcouchbase-2.0.3nginx3.tar.gz
wget http://packages.couchbase.com/clients/c/nginx-couchbase-module-0.3.1.tar.gz
for i in *.tar.gz; do tar xvf $i; done

The following steps describe how to install nginx with module into the directory /opt/nginx-couchbase:

export PREFIX=/opt/nginx-couchbase

cd libcouchbase-2.0.3nginx3
./configure --prefix=$PREFIX --enable-debug --disable-plugins --disable-tests --disable-couchbasemock
make && sudo make install
cd ..

cd nginx-1.3.7
export LIBCOUCHBASE_INCLUDE=$PREFIX/include
export LIBCOUCHBASE_LIB=$PREFIX/lib
./configure --prefix=$PREFIX --with-debug --add-module=../nginx-couchbase-module-0.3.1
make && sudo make install