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.
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.
Installing
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).
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
- java
-
For the Perl and C tests
- libsasl2
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 checkBuilding 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_TARRBALLandLIBCOUCHBASE_TARBALLkeys inPLCB_Config.pmto 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 srcNote 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 - 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 \ --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
Testing
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