Quarkus Couchbase

Integrates Couchbase into Quarkus.

This extension is currently in beta status. It supports:

• Dependency injecting a Couchbase Cluster and Bucket.
• Connecting to a cluster using TLS in native mode (either with the packaged Capella certificate, or a path to a custom one specified with quarkus.couchbase.security.trustCertificate)
• Configuring the Cluster through application.properties. Currently, a minimal set of configuration options is provided.
• A dev service that starts a Couchbase server in a Docker container. With this you can develop your Quarkus app without having to install Couchbase on your machine.
• GraalVM/Mandrel/native-image.
• KV, Query, Transactions, Analytics, Search and Management operations.
• Micrometer metrics using quarkus-micrometer
• SmallRye Health checks (Readiness) using quarkus-smallrye-health

Please try it out and provide feedback, ideas and bug reports on Github.

Native Image

All main Cluster operations have been tested with our internal testing tools, however the extension remains in beta and some features may be missing or not be fully supported.

Usage

Since version 1.5.0, the extension requires Quarkus 3.40 or later.

Add it to your project:

<dependency>
  <groupId>io.quarkiverse.couchbase</groupId>
  <artifactId>quarkus-couchbase</artifactId>
  <version>1.5.0</version>
</dependency>

Provide the Couchbase configuration in application.properties:

quarkus.couchbase.connection-string=localhost
quarkus.couchbase.username=username
quarkus.couchbase.password=password

Since version 1.4.0, you can also configure and inject a Bucket:

The Bucket must exist on the Cluster.

quarkus.couchbase.bucket-name=default

Since version 1.5.0, you can also set any ClusterEnvironment option with a CDI bean that implements com.couchbase.quarkus.extension.ClusterEnvironmentCustomizer. See Customizing the Cluster environment.

To disable TestContainers, add:

quarkus.devservices.enabled=false

Now you can @Inject a Couchbase Cluster or Bucket into your project:

@Path("/couchbase")
public class TestCouchbaseResource {
    @Inject
    Cluster cluster;
    
    @Inject
    Bucket bucket;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("/test")
    public String run() {
        var collection = bucket.defaultCollection();

        // Upsert a new document
        collection.upsert("test", JsonObject.create().put("foo", "bar"));

        // Fetch and print a document
        var doc = bucket.defaultCollection().get("test");
        System.out.println("Got doc " + doc.contentAsObject().toString());

        // Perform a N1QL query
        var queryResult = cluster.query("select * from `travel-sample` where url like 'http://marriot%' and country = 'United States';");

        queryResult.rowsAsObject().forEach(row -> {
            System.out.println(row.toString());
        });

        return "success!";
    }
}

And test http://localhost:8080/couchbase/test.

Additional Configuration

Please refer to the docs for additional configuration options.

Limitations

The quarkus.couchbase.* properties cover a small set of Cluster options. Use a ClusterEnvironmentCustomizer to set the other options.
Additional Cluster connections can be created and configured using Cluster.connect(...), however not all code paths have been tested and are therefore not officially supported.

License

The Netty substitutions in runtime/src/main/java/com/couchbase/quarkus/extension/runtime/graal/ (NettyCompressionSubstitutions and NettySslSubstitutions) are adapted from the official netty extension. Couchbase does not intend copyright infringement or claim ownership over these files or their content.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Graham Pople 💻 🚧

Emilien Bevierre 💻 🚧

Michael Reiche 💻

This project follows the all-contributors specification. Contributions of any kind welcome!