Quarkus Couchbase

Integrates Couchbase into Quarkus.

This extension currently supports:

Dependency injecting a Couchbase Cluster and Bucket.
Configuring the Cluster through application.properties. Currently, a minimal set of configuration options is provided.
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
Dev Services (starts a Couchbase TestContainer, re-usable across tests)

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

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 (usually located in your src/main/resources directory). See the Configuration section for more options and details.

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

# Optional, the name of an existing bucket to inject as a `Bucket` bean. If using DevServices, this bucket is also provisioned in the container.
quarkus.couchbase.bucket-name=travel-sample

You can now @Inject a Couchbase Cluster and 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 it at http://localhost:8080/couchbase/test.

Customizing the Cluster environment

To set a ClusterEnvironment option that has no quarkus.couchbase.* property, declare a CDI bean that implements com.couchbase.quarkus.extension.ClusterEnvironmentCustomizer. This interface is available since version 1.5.0. The extension calls it after it applies the properties, so a customizer can also override them.

This example makes the Reactive API publish results on an application scheduler.

@Singleton
public class PublishOnCustomizer implements ClusterEnvironmentCustomizer {
    private final Scheduler scheduler = Schedulers.newBoundedElastic(4, 1000, "my-app");

    @Override
    public void customize(ClusterEnvironment.Builder builder) {
        builder.publishOnScheduler(() -> scheduler);
    }

    @PreDestroy
    void dispose() {
        scheduler.dispose();
    }
}

Create the scheduler in an instance field or in a method, not in a static field. A native build initializes classes at build time, so a scheduler in a static field starts its threads during the build, and the build fails.

If there are several customizers, they run in ascending @jakarta.annotation.Priority order, so a customizer with a higher priority runs later and its values win. A customizer without @Priority has priority 0.

Use @Singleton or @ApplicationScoped if the customizer owns resources, such as a scheduler, because a @Dependent customizer is never destroyed.

Dev Services

DevServices (Couchbase TestContainers) activate when quarkus.devservices.enabled is true and no quarkus.couchbase.connection-string is set.

Setting quarkus.couchbase.connection-string (for example to point at a real cluster or Capella) disables DevServices.

If the container fails to start, DevServices tries again, up to 3 attempts in total.

Micrometer Metrics

The extension already includes the Couchbase metrics-micrometer module. You can enable Micrometer metrics by adding the following dependencies to your application:

# Add the Quarkus micrometer dependency
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer</artifactId>
</dependency>

# Here we use Quarkus' Prometheus extension to display metrics in the DevUI
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
</dependency>

Set quarkus.couchbase.metrics.enabled=true in application.properties. The emission rate is also configurable with quarkus.couchbase.metrics.emit-interval. It is recommended to enable histograms which aren’t enabled by default. Configuring the MeterRegistry is explained on the Quarkus Docs and Couchbase docs.

Unsupported Features

Using the separate tracing-opentelemetry package for the Couchbase Java SDK.