/ 
Couchbase-Client-2.0.0_1
River stage one • 1 direct dependent • 1 total dependent
/ Couchbase::Client::README

NAME

Couchbase::Client::README - README for Couchbase::Client

Introduction

Couch::Couchbase is a Perl client for Couchbase (http://www.couchbase.org).

The couchbase client is a smart, vbucket-aware client. What this means is that Couchbase::Client can tap into your Couchbase cluster, with the client needing to be able to access (initially) only a single entry point.

This is only a simple overview of the capabilities of this module. For full module documentation, see http://search.cpan.org/dist/Couchbase-Client/lib/Couchbase/Client.pm

The module provides:

Synchronous Interface: Couchbase::Client

This is the simplest and most tested interface. The methods are self-explanatory. Additionally, the return type is complex and detailed, allowing error reporting for any unexpected conditions (something severely lacking in any Memcache client implementation).

I Will be using Devel::REPL to emulate an interactive shell (the actual script to launch the shell is in eg/re.pl), where necessary

Creating a new object

use Couchbase::Client;
my $cbo = Couchbase::Client->new({ server => "localhost" });

Set a Value

my $ret = $cbo->set(a_key => "a_value");

Almost every single Couchbase operation returns the common Couchbase::Client::Return object:

$ret # =>
bless( [
    undef,
    0,
    undef,
    "12952738923228168704"
  ], 'Couchbase::Client::Return' )

You may inspect and access the object using its methods:

$ret->is_ok
#=> 1

$ret->cas
# => 12952738923228168704

Get a Value

Now, get the key back again:

$ret = $cbo->get("a_key");
$ret->value
#=> "a_value"

Object References

Transparently store references:

$cbo->set("an object", ["Hello", "World"]);
$ret = $cbo->get("an object");

And get them back again..

$cbo->get("an object")->value
#=> [ "Hello", "World" ]

Arithmetic

If the counter does not yet exist, we will need to create it

$cbo->arithmetic(
    "my counter",
    +1, # desired change,
    0, # initial value
)->value
#=> 1
# results are returned for arithmetic operations

now, increment it by 1

$cbo->incr("my counter")->value
#=> 2

increment by 10

$cbo->incr("my counter", 10)->value
#=> 12

decrement by 1

$cbo->decr("my counter")->value
#=> 11

Optimistic Locking

Use CAS to sure your data is consistent:

$ret = $cbo->get("a_key");

$ret->value #=> "a_value";
$ret->cas #=> 7712708499878511104

$cbo->cas("a_key", "a different value", $ret->cas);
#=> OK

$ret = $cbo->cas("a_key", "yet another value", $ret->cas);
$ret->errstr #=> "Key exists (with a different CAS value)"

Try updating the key again, but using the CAS from the first operation:

Pessimistic Locking

If you have keys that will likely be objects of contention, you can use pessimistic locking (i.e. mutual-exclusion) by using the lock and unlock methods

$lockret = $cbo->lock("foo", 10);
if ($lockret->errnum == COUCHBASE_ETMPFAIL) {
    # something else is locking it.. maybe retry?
}
# lock() returns the value as well, just like get()

my $value = frob($lockret->value);
# Set the value. We must use the CAS from the lock operation.

my $rv = $cbo->set("foo", $value, { cas => $lockret->cas });
$cbo->unlock("foo", $rv->cas);

Legacy Interface: Couchbase::Client::Compat

Drop-in replacement for Cache::Memcached and Cache::Memcached::Fast.

I can't say it's 100% compatible yet, but the basic methods have been implemented. Internally it just wraps around the new interface

Asynchronous Framework for Perl: Couchbase::Client::Async

Provides the necessary functions and utilities needed to make a POE, IO::Async, etc. client for Couchbase.

Couch View Interface: Couchbase::Couch

Provides the methods to interface with Couch endpoints, create, modify, and use design documents and views.

Mock Server Interface: Couchbase::MockServer

Interface to the Java CouchbaseMock.jar. This is a work in progress.

Extra Components

Couchbase::Config - REST API module

This module will probably be a dependency for full testing, but will not necessarily be part of this distribution. It's currently available as a separate repository on github.

Couchbase::VBucket - VBucket server mapping module

Just a little utility module. May be useful for testing.

Installation

Couchbase::Client depends on libcouchbase. You may either use the bundled libcouchbase (which is the default installation mode), or using a user/system installed libcouchbase.

In any event, the process consists of doing something like:

perl Makefile.PL
make
make test
make install

Of course, the test target is optional.

Using Embedded Libraries

This option is normally only available if using a pre-made CPAN distribution. The Git repository does not contain the actual libcouchbase source code, so there are some extra steps needed. These are documented in the HACKING.POD file in the root of this distribution.

Using an Existing libcouchbase

If libcouchbase is already installed, the script should detect this. If it doesn't, you may need to pass some extra arguments to Makefile.PL. For example if your libcouchbase is installed as /sources/lcb/inst, you'd do

perl Makefile.PL --dynamic --incpath -I/sources/lcb/inst/include --libpath -L/sources/lcb/inst/lib

where the --incpath and --libpath parameters specify extra compiler/linker flags to use.

Support

You may file a bug at the Couchbase JIRA, at http://www.couchbase.com/issues, specifying the Couchbase Perl Client Library project. You may also find support in the #libcouchbase channel on irc.freenode.net.