Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Perl Client for Couchbase (
C++ Perl C XS

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
Config @ 378544b
VBucket @ 0e80a4d



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


Couch::Couchbase is a Perl client for Couchbase (

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.

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).

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.

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.


I will be focusing on installing and configuring libcouchbase itself, the C client library. It is assumed you have a functional installation of the couchbase server somewhere. If not, go to

To use this module, you should have installed libvbucket (see the links on the side here

As of 01/28/2011, you will need to download libcouchbase itself from github (the current release versions contain bugs which may break this module).

Building libcouchbase

libcouchbase itself depends on libvbucket, so make sure to install that (and its development libraries) first.

Currently, I know of these dependencies:

libevent >= 1.4

For embedded default event loop functionality


For the Perl and C tests


Additionally, libcouchbase depends on header files available from the engine-pu branch of the memcached project. Note that actually building memcached itself is not required.

Your best bet would be to do something like this:

    ~$ mkdir couch
    ~$ git clone -b engine-pu couch/memcached
    ~$ git clone couch/libcouchbase
    #Get vbucket stuff:
    # I pick RPM, since that's what my target production platform is:
    ~$ wget
    ~$ rpm -ivh libvbucket1-
    ~$ wget
    ~$ cd couch; tar xf ../libvbucket-
    ~$ ln -s libvbucket- libvbucket
    # Note for CentOS/RHEL 5 users, you will need to perform the autorun
    # to generate the 'configure' script on a newer platform, then copy it over
    # to your target platform
    ~$ cd couch/libcouchbase
    ~$ ./config/
    #make sure we know about the new memcached (and vbucket) headers:
    ~$ CPPFLAGS='-I../memcached/include -I../libvbucket/include' ./configure
    # (EL5: If configure complains about not finding libvbucket, try:)
        ~$ ln -s /usr/lib64/ /usr/lib64/
    ~$ make
    #optional, run some tests:
    ~$ make check

Building Couchbase::Client

There are two ways to build Couchbase::Client and associated modules.

Static libcouchbase and libvbucket

This is the mode of distribution and is the default option.

You should edit the LIBVBUCKET_TARRBALL and LIBCOUCHBASE_TARBALL keys in to correspond to the basename (the release string, without the .tar.gz suffix), thus:

    == ==
    my $params = {
    LIBCOUCHBASE_RELEASE => '1.0.0_45_g58818c5'

    $ mkdir src
    cp libvbucket- src/
    cp libcouchbase-1.0.0_45_g58818c5.tar.gz src/
    cp -a memcached/include src

Note that the tarball MUST have as its top-level directory the name of the tarball itself, without the .tar.gz suffix.

If you are not using a 'release-style' tarball but rather checking out from git, then you will likely need to run ./configure and then make dist, which should give you a tarball.


    $ perl Makefile.PL
    $ make test install #and whatever other targets you want
Dynamic Linking

This is the non-default option, and should be used if you want to use your system's libcouchbase, which may or may not break the perl client.

Granted libcouchbase is rather new, so most systems will not have available packaging for libcouchbase or its tributaries.

Know where your include and linker paths are, and do the following:

    perl Makefile.PL --dynamic \
    --include=-I/sources/libcouchbase/include \


There are some top-level scripts. Some have meaning to only the author, some might be useful.

If you would like to generate the perl MANIFEST, run the script.

Also, check out the runnable modules in the t/ directory


The tests in this module require java to run. Some tests furthermore will only work on a real cluster, due to some of the limitations in the Java client.

To run the tests on a real cluster, you can make use of the PLCB_TEST_REAL_SERVER environment variable.

When set, it should/can contain something like this:


The keys available are

username, password

Authentication information


Which bucket to use (default is default)


Which server to connect to (default is localhost:8091)


Required for some tests. This is the authless port for memcached client access.

Something went wrong with that request. Please try again.