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:
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.
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.
The following components are required for a proper
- libcouchbase >= 1.0.1 (release)
- libvbucket >= 188.8.131.52 (release)
- libevent >= 1.4
- libsasl/libsasl2 (any version).
- Java (for the tests).
All of the above components (except Java) are bundled in source form with the tarball distribution (see further).
Couchbase::Client is bundled (in its tarball distribution) with source distributions of libevent, libisasl, libvbucket, and libcouchbase. These are not present on the git version because it is assumed that the user may want to provide copies of their own.
The bundled configuration will only substitute missing dependencies from the bundle; thus, if you have
libsasl but are missing a proper version of
libevent, then only the bundled libevent (but not libsasl) will be used.
Couchbase::Client can be configured to either link against the bundled libraries, or to link against a custom or system directory.
Using Embedded Libraries:
In order to use embedded libraries, you should ensure that you have a proper distribution for each needed and unfound library.
PLCB_Config.pm should contain a bunch of hash entries in the format of
LIBFOO_RELEASE => 1.2.3-sdff
LIBFOO is the uper-case name of the library, and the value is the version of the library.
The tarball must be named
libfoo-1.2.3-sdff.tar.gz, and its top-level directory must be
You will find that the config file has sane defaults, and that the main task is downloading them.
The tarballs should then be relocated to the
Once all is ready, you can invoke the
Makefile.PL script, optionally passing some arguments.
A string for passing to the linker which should contain something like
This is only necessary if your standard dependencies are found outside the linker's default search path (e.g. macports)
This is the same as
--libpath, but are passed to the preprocessor and would look like
Thus you can invoke somehting like:
$ perl Makefile.PL --incpath=-I/opt/local/include --libpath=-L/opt/local/lib $ make $ make test # but see the testing section, later $ make install
Providing your own libraries.
This is a relatively straight-forward option, and is what I use for development.
Simply make use of the aforementioned
--incpath arguments to point to the directory which contains the necessary dependencies, and follow the relevant parts from the above section.
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
Also, check out the runnable modules in the
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.
CouchbaseMock.jar should be located within the
t/tmp directory. You can obtain one from here
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
Which bucket to use (default is
Which server to connect to (default is
Required for some tests. This is the authless port for memcached client access.
32 Bit perls will have arithmetic results stringified if their value is greater than 32 bits.
Some tests within the test suite will fail in some unices (but not linux, from what i've seen) with the following message:
t/01-main.t .. 1/? # Failed test 'have single error' # at /home/mordy/Couchbase-Client-0.16_0/blib/lib/Couchbase/Test/Settings.pm line 262. # (in Couchbase::Test::Settings->T25_multi_server_list) # got: '2' # expected: '1' t/01-main.t .. 162/? # Looks like you failed 1 test of 166. t/01-main.t .. Failed 1/166 subtests (less 1 skipped subtest: 164 okay)
This is not a fatal error, and is being worked on
Asynchronous tests (and the reference POE implementation) will not work properly on NetBSD due to a weird kernel bug
I have not even bothered to figure out how to compile this on Windows. Mingw32 will be supported eventually, but probably not MSVC.