You are viewing the documentation for a prerelease version.

View Latest

Install and Start Using the Java SDK with Couchbase Server

The Couchbase Java SDK allows Java applications to access a Couchbase cluster. It offers traditional synchronous APIs as well as reactive and asynchronous APIs to maximize flexibility and performance.

These pages cover the Beta release of the Couchbase Java SDK. The API interface is stable, but could change for bug fixes during the Beta process. New features are likely to be added.

Documentation is incomplete, subject to change, and could contain broken links.

The Couchbase Java SDK 3.0 is a complete rewrite of the API, reducing the number of overloads to present a simplified surface area, and adding support for future Couchbase Server features like Collections and Scopes (available in Couchbase Server 6.5 as a developer preview). The 3.0 SDK also moves from RxJava to Java Reactor, along with other improvements to performance, logging, and timeout troubleshooting.

Installing the SDK

The SDK requires Java 8 or later to be installed, earlier versions will not work. Java 11 is recommended, which has various enhancements like lambda local variable type inference, profiling tools, and updated security features. Most of the flavors available will do, although we might only provide support for OpenJDK and Oracle JDK going forward. It has not been tested (and is not supported on) Java 12.

You can use your favorite dependency management tool to install the SDK. The following snippet shows how to do it with maven.

      <name>Couchbase Preview Repository</name>


Hello Couchbase

Once you have the Java client installed, open your IDE, and try out the following:

Cluster cluster = Cluster.connect("localhost", "username", "password");

Couchbase uses Role Based Access Control (RBAC) to control access to resources. Here we will use the Full Admin role created during installation of the Couchbase Data Platform. For production client code, you will want to use more appropriate, restrictive settings — but here we want to get you up and running quickly. If you’re developing client code on the same VM or machine as the Couchbase Server, your URI can be localhost.

Connection to the cluster is initialized by

// get a bucket reference
Bucket bucket = cluster.bucket("bucket-name");

If you installed the travel sample data bucket, substitute travel-sample for bucket-name.

// get a collection reference
Collection collection = bucket.defaultCollection();

The 3.0 SDK is ready for the introduction of Collections in an upcoming release of the Couchbase Data Platform. The latest release, Couchbase Server 6.5, brings a limited Developer Preview of Collections, allowing Documents to be grouped by purpose or theme, according to specified Scope. Here we will use the DefaultCollection, which covers the whole Bucket.

// Upsert Document
MutationResult upsertResult = collection.upsert(
    JsonObject.create().put("name", "mike")

// Get Document
GetResult getResult = collection.get("my-document");

KV Operations are described in detail on the KV Operations page. Now that you know the basics, you may wish to go straight to that page.

Additional Resources

The API reference is generated for each release and can be found here.

Couchbase welcomes community contributions to the Java SDK. The Java SDK source code is available on GitHub.