Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Perl Client for Couchbase (http://www.couchbase.org)

branch: master

PLCBC-12: Add 'compat' tests, and fix compat-mode cas

Also, forward-port some fixes from 'stable' mode
latest commit b4ee141374
M. Nunberg authored December 19, 2012
Octocat-spinner-32 author_utils Split 'VALGRIND' variable April 17, 2013
Octocat-spinner-32 constants Refactor async API April 23, 2013
Octocat-spinner-32 eg Modify and make couch_demo script a bit nicer April 11, 2013
Octocat-spinner-32 inc Wrap some %Config constants so they work on OS X April 11, 2013
Octocat-spinner-32 lib PLCBC-12: Add 'compat' tests, and fix compat-mode cas April 25, 2013
Octocat-spinner-32 src PLCBC-7: Allow option to skip test execution April 25, 2013
Octocat-spinner-32 t PLCBC-12: Add 'compat' tests, and fix compat-mode cas April 25, 2013
Octocat-spinner-32 xs PLCBC-8, PCLCB-9: cluster_nodes and lcb_version April 25, 2013
Octocat-spinner-32 .gitignore Reworked source code to work with libcouchbase2 April 03, 2013
Octocat-spinner-32 .gitmodules Changed .gitmodules bad repo url February 09, 2012
Octocat-spinner-32 HACKING.pod Update installation documentation April 13, 2013
Octocat-spinner-32 MANIFEST.SKIP First non-dev release February 27, 2012
Octocat-spinner-32 MANIFEST.in PLCBC-12: Add 'compat' tests, and fix compat-mode cas April 25, 2013
Octocat-spinner-32 Makefile.PL Refactor some internal APIs April 24, 2013
Octocat-spinner-32 PLCB_ConfUtil.pm Fixed build scripts, changed absolute to relative time offsets February 19, 2012
Octocat-spinner-32 PLCB_Config.pm Upgrade to newer version of libcouchbase April 24, 2013
Octocat-spinner-32 README.dist First non-dev release February 27, 2012
Octocat-spinner-32 README.pod Provide information on support/technical support April 24, 2013
Octocat-spinner-32 TODO Added preliminary view code April 09, 2012
Octocat-spinner-32 build_libraries.pl PLCBC-7: Allow option to skip test execution April 25, 2013
Octocat-spinner-32 couchbase-client.kpf Prepare stuff for iteration April 09, 2012
Octocat-spinner-32 ignore.txt Test files (based on Test::Class). README glorified. January 28, 2012
README.pod

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.

Something went wrong with that request. Please try again.