Skip to content


Subversion checkout URL

You can clone with
Download ZIP
The official Java client for Couchbase Server

JCBC-784: Adapt javadocs to reflect counter API changes.

Change-Id: If0fcf05decf13f31ad7eae0a61289fcee0b07f50
Reviewed-by: Simon Baslé <>
Tested-by: Michael Nitschinger <>
latest commit d810620807
@daschl daschl authored daschl committed

Official Couchbase Java SDK

Welcome to the official Couchbase Java client library. If you want to use Couchbase from the Java programming language, this is your one-stop-shop.

Getting Started

Getting the Dependencies

The package is available from Maven Central:


You can also go here and download the jars directly.

Staying Updated, Asking Questions

Come by the forums! And be sure to check out our blog.


Both synchronous and asynchronous (reactive, through RxJava) are supported. The following code connects to localhost, opens the default bucket, stores a document, loads it again and prints its content.

Here is the sync variation:

// Create a cluster reference
CouchbaseCluster cluster = CouchbaseCluster.create("");

// Connect to the bucket and open it
Bucket bucket = cluster.openBucket("default");

// Create a JSON document and store it with the ID "helloworld"
JsonObject content = JsonObject.create().put("hello", "world");
JsonDocument inserted = bucket.insert(JsonDocument.create("helloworld", content));

// Read the document and print the "hello" field
JsonDocument found = bucket.get("helloworld");
System.out.println("Couchbase is the best database in the " + found.content().getString("hello"));

// Close all buckets and disconnect

And here (one of the possible) async ones:

JsonObject content = JsonObject.create().put("hello", "world");
    .insert(JsonDocument.create("helloworld", content))
    .flatMap(new Func1<JsonDocument, Observable<JsonDocument>>() {
        public Observable<JsonDocument> call(JsonDocument document) {
            return bucket.async().get(document);
    .map(new Func1<JsonDocument, String>() {
        public String call(JsonDocument doc) {
            return doc.content().getString("hello");
    .subscribe(new Action1<String>() {
        public void call(String s) {
            System.out.println("Couchbase is the best database in the " + s);

If you can already use Java 8, things get much nicer:

JsonObject content = JsonObject.create().put("hello", "world");
    .insert(JsonDocument.create("helloworld", content))
    .flatMap(document -> bucket.async().get(document))
    .map(doc -> doc.content().getString("hello"))
    .subscribe(s -> System.out.println("Couchbase is the best database in the " + s));

You can read more in the documentation.



We are utilizing the publish gradle plugin:

~/couchbase-java-client $ ./gradlew publishToMavenLocal

Make sure to do the same with core-io first!

Running the Tests

The test suite is separated into unit, integration and performance tests. Each of those sets can and should be run individually, depending on the type of testing needed. While unit and integration tests can be run from both the command line and the IDE, it is recommend to run the performance tests from the command line only.

Unit Tests

Unit tests do not need a Couchbase Server reachable, and they should complete within a very short time. They are located under the src/test namespace and can be run directly from the IDE or through the gradle test command line:

~/couchbase-java-client $ ./gradlew test


Integration Tests

Those tests interact with Couchbase Server instances and therefore need to be configured as such. If you do not want to change anything special, make sure you at least have one running on localhost. Then use the gradle integrationTest command:

~/couchbase-java-client $ ./gradlew integrationTest

Something went wrong with that request. Please try again.