Full Installation

Installation instructions for the Couchbase Java Client.

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

The Couchbase Java SDK 3.x is a complete rewrite of the 2.x API, providing a simpler surface area and adding support for Couchbase Server features like Collections and Scopes (available in Couchbase Server 7.0+). The (reactive) API also migrated from RxJava to Reactor, along with other improvements to performance, logging, debugging and timeout troubleshooting. If you’re upgrading your application from Java SDK 2.x, please read our Migrating 2.x code to SDK 3.0 Guide.

Prerequisites

The Java SDK is tested against LTS versions of Oracle JDK and OpenJDK — see our compatibility docs. The underlying OS normally makes no difference, but library incompatibilities in Alpine Linux makes a workaround necessary for this OS.

Installing the SDK

At least Java 8 is required for current releases; see the Compatibility section for details. We recommend running the latest Java LTS version (i.e. at the time of writing JDK 21) with the highest patch version available.

Couchbase publishes all stable artifacts to Maven Central. The latest version (as of January 2024) is 3.5.3.

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

Maven
Gradle

For Maven, you can insert the following into the dependencies section of your project’s pom.xml file:

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

Refer to the Maven Documentation for more information regarding the structure of the pom.xml file.

For Gradle, you can use:

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

Alternatively, we provide a zip file with all the dependencies bundled if you wish to manually include the jar files in your classpath. Refer to the Release Notes for further details. You can also find links to the hosted javadocs there.

Using a Snapshot Version

Couchbase publishes pre-release snapshot artifacts to the Sonatype OSS Snapshot Repository. If you wish to use a snapshot version, you’ll need to tell your build tool about this repository.

Maven
Gradle (Groovy)

pom.xml

<repositories>
  <repository>
    <id>sonatype-snapshots</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    <releases><enabled>false</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
</repositories>

build.gradle

repositories {
    mavenCentral()
    maven {
        url "https://oss.sonatype.org/content/repositories/snapshots"
        mavenContent { snapshotsOnly() }
    }
}