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)

tree: bf5f7864cb

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.pod

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

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.

The module provides:

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

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

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

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

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.

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 http://www.couchbase.org

To use this module, you should have installed libvbucket (see the links on the side here http://www.couchbase.com/develop/c/current).

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

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

Currently, I know of these dependencies:

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 https://github.com/memcached/memcached.git -b engine-pu couch/memcached
    ~$ git clone https://github.com/couchbase/libcouchbase.git couch/libcouchbase
    
    #Get vbucket stuff:
    
    # I pick RPM, since that's what my target production platform is:
    
    ~$ wget http://packages.couchbase.com/clients/c/libvbucket1-1.8.0.1-1.x86_64.rpm
    ~$ rpm -ivh libvbucket1-1.8.0.1-1.x86_64.rpm
    ~$ wget http://packages.couchbase.com/clients/c/libvbucket-1.8.0.1.tar.gz
    ~$ cd couch; tar xf ../libvbucket-1.8.0.1.tar.gz
    ~$ ln -s libvbucket-1.8.0.1 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/autorun.sh
    
    #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/libvbucket.so.1 /usr/lib64/libvbucket.so
    
    
    ~$ make
    
    #optional, run some tests:
    ~$ make check

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

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

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

    == PLCB_Config.pm ==
    my $params = {
    
    #...
    
    LIBVBUCKET_RELEASE => '1.8.0.1_4_g677e403',
    LIBCOUCHBASE_RELEASE => '1.0.0_45_g58818c5'
    
    };

    
    $ mkdir src
    cp libvbucket-1.8.0.1_4_g677e403.tar.gz 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.

run

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

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 \
    --ldpath=-L/sources/libcouchbase/.libs

    make

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 gen_manifest.pl 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:

    PLCB_TEST_REAL_SERVER='bucket=my_bucket,username=secret,memd_port=11212'

The keys available are

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.