A newer version of this documentation is available.

Install and Start Using the Java SDK with Couchbase Server

Hello Couchbase

On this page we show you how to quickly get up and running — installing the Couchbase Java SDK, and trying out the Hello World code example against Couchbase Capella, or against a local Couchbase cluster.

We will go through the code sample step by step, but for those in a hurry to see it, here it is:

Couchbase Capella Sample
Local Couchbase Server

If you are connecting to Couchbase Capella, be sure to get the correct endpoint as well as user, password — and see the Cloud section, below.

import com.couchbase.client.java.*;
import com.couchbase.client.java.kv.*;
import com.couchbase.client.java.json.*;
import com.couchbase.client.java.query.*;
import java.time.Duration;


public class CloudConnect {
  // Update these variables to point to your Couchbase Capella instance and credentials.
  static String connectionString = "couchbases://cb.njg8j7mwqnvwjqah.cloud.couchbase.com";
  static String username = "username";
  static String password = "Password!123";
  static String bucketName = "travel-sample";
  

  public static void main(String... args) {
    Cluster cluster = Cluster.connect(connectionString, username, password);
    
    // get a bucket reference
    Bucket bucket = cluster.bucket(bucketName);
    bucket.waitUntilReady(Duration.ofSeconds(10));

    // get a user defined collection reference
    Scope scope = bucket.scope("tenant_agent_00");
    Collection collection = scope.collection("users");

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

    // Get Document
    GetResult getResult = collection.get("my-document");
    String name = getResult.contentAsObject().getString("name");
    System.out.println(name); // name == "mike"

    // Call the query() method on the cluster object and store the result.
    QueryResult result = cluster.query("select \"Hello World\" as greeting");
    
    // Return the result rows with the rowsAsObject() method and print to the terminal.
    System.out.println(result.rowsAsObject());
  }
}

The Couchbase Capella free trial version comes with the Travel Sample Bucket, and its Query indexes, loaded and ready.

import com.couchbase.client.java.*;
import com.couchbase.client.java.kv.*;
import com.couchbase.client.java.json.*;
import com.couchbase.client.java.query.*;
import java.time.Duration;

public class StartUsing {
  // Update these variables to point to your Couchbase Server instance and credentials.
  static String connectionString = "couchbase://localhost";
  static String username = "Administrator";
  static String password = "password";
  static String bucketName = "travel-sample";
  

  public static void main(String... args) {
    Cluster cluster = Cluster.connect(connectionString, username, password);
    
    // get a bucket reference
    Bucket bucket = cluster.bucket(bucketName);
    bucket.waitUntilReady(Duration.parse("PT10S")) ;

    // get a user defined collection reference
    Scope scope = bucket.scope("tenant_agent_00");
    Collection collection = scope.collection("users");

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

    // Get Document
    GetResult getResult = collection.get("my-document");
    String name = getResult.contentAsObject().getString("name");
    System.out.println(name); // name == "mike"

    // Call the query() method on the cluster object and store the result.
    QueryResult result = cluster.query("select \"Hello World\" as greeting");
    
    // Return the result rows with the rowsAsObject() method and print to the terminal.
    System.out.println(result.rowsAsObject());
  }
}

As well as the Java SDK (see below), and a running instance of Couchbase Server, you will need to load up the Travel Sample Bucket using either the Web interface or the command line.

Quick Installation

We recommend running the latest Java LTS version (i.e. at the time of writing JDK 17) with the highest patch version available. Couchbase publishes all stable artifacts to Maven Central.

The latest version (as of September 2022) is 3.3.4.

You can use your favorite dependency management tool to install the SDK.

Maven
Gradle

<dependencies>
    <dependency>
        <groupId>com.couchbase.client</groupId>
        <artifactId>java-client</artifactId>
        <version>3.3.4</version>
    </dependency>
</dependencies>

implementation 'com.couchbase.client:java-client:3.3.4'

See the installation page for more detailed instructions.

Step by Step

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

Couchbase Capella Connection
Local Server Connection

// Update these variables to point to your Couchbase Capella instance and credentials.
static String connectionString = "couchbases://cb.njg8j7mwqnvwjqah.cloud.couchbase.com";
static String username = "username";
static String password = "Password!123";
static String bucketName = "travel-sample";

  Cluster cluster = Cluster.connect(connectionString, username, password);

From 3.3, the Java SDK includes Capella’s standard certificates by default, so you do not need to additional configuration. You do need to enable TLS, which can be done by simply using couchbases: in the Connection String as in this example. See Managing Connections for full configuration details.

// Update these variables to point to your Couchbase Server instance and credentials.
static String connectionString = "couchbase://localhost";
static String username = "Administrator";
static String password = "password";
static String bucketName = "travel-sample";

  Cluster cluster = Cluster.connect(connectionString, username, password);

Couchbase uses Role Based Access Control (RBAC) to control access to resources. Here we suggest using the Full Admin role created during setup of Couchbase Capella, or a local Couchbase Server cluster.

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 connection string can be just localhost.

The Cluster provides access to cluster-level operations like N1Ql queries, analytics or full-text search. You will also find different management APIs on it.

To access the KV (Key/Value) API or to query views, you need to open a Bucket:

// get a bucket reference
Bucket bucket = cluster.bucket(bucketName);
bucket.waitUntilReady(Duration.parse("PT10S")) ;

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

The 3.3 SDK supports full integration with the Collections feature introduced in Couchbase Server 7.0. This brings complete support of Collections, allowing Documents to be grouped by purpose or theme, according to a specified Scope. Here we will use the users collection within the tenant_agent_00 scope from travel-sample bucket as an example.

// get a user defined collection reference
Scope scope = bucket.scope("tenant_agent_00");
Collection collection = scope.collection("users");

KV Operations are described in detail on the KV Operations page, but to get you started the following code creates a new document and then fetches it again, printing the result.

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

// Get Document
GetResult getResult = collection.get("my-document");
String name = getResult.contentAsObject().getString("name");
System.out.println(name); // name == "mike"

You can also perform a N1QL query at the cluster level:

// Call the query() method on the cluster object and store the result.
QueryResult result = cluster.query("select \"Hello World\" as greeting");

// Return the result rows with the rowsAsObject() method and print to the terminal.
System.out.println(result.rowsAsObject());

You can learn more about N1QL queries on the Query page. Other services (like analytics, search or views) work very similar to the two shown above. Please refer to their respective documentation sections to learn more.

Cloud Connections

For developing on Capella, if you are not working from the same Availability Zone, refer to the following:

Notes on Constrained Network Environments
Network Requirements
If you have a consumer-grade router which has problems with DNS-SRV records review our Troubleshooting Guide.

Additional Resources

The API reference is generated for each release and the latest can be found here. Older API references are linked from their respective sections in the Release Notes.

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

If you are planning to use Spring Data Couchbase, see the notes on version compatibility.