Couchbase Configuration

Full details can be found in the CouchbaseBuildTimeConfig API Reference (dev-services, health, metrics enablement) and the CouchbaseRuntimeConfig API Reference (connection, credentials, TLS, runtime tuning).

Currently, a minimal set of configuration options for the Cluster bean is provided.

Configuration options fall into two categories that differ in when they take effect:

  • Run-time options are read when the application starts. You can change them in application.properties (or via environment variables, system properties, etc.) and they take effect on the next restart. This covers connection details, credentials, TLS/security, and runtime tuning.

  • Build-time options are fixed into the artifact when the application is built. Changing them in application.properties after the build has no effect. The application must be recompiled. These options control which features are wired in (DevServices, health checks, metrics).

The following options are build-time and require a rebuild to change:

  • quarkus.couchbase.devservices.version

  • quarkus.couchbase.devservices.use-dynamic-ports

  • quarkus.couchbase.devservices.ui-port

  • quarkus.couchbase.health.enabled

  • quarkus.couchbase.metrics.enabled

Every other option is run-time and can be changed without rebuilding.

Required:

These config items do not default to placeholder values, and are required to be set in application.properties.

  • quarkus.couchbase.connection-string

    • String: Examples localhost, couchbase://127.0.0.1.

    • Note: This should be unset if using DevServices, else the TestContainer won’t start.

  • quarkus.couchbase.username

    • String: The username to authenticate with.

    • Note: Not required when DevServices starts a container, injected to Administrator.

  • quarkus.couchbase.password

    • String: The password to authenticate with.

    • Note: Not required when DevServices starts a container injected to password.

Optional

These config items have default values, but can be overridden in application.properties.

  • quarkus.couchbase.devservices.use-dynamic-ports (build-time)

    • Boolean: Whether to use dynamic ports for DevServices. When true, TestContainers will use random available ports. When false, fixed ports are used (container ports mapped to same host ports).

    • Default: false (fixed ports mode)

  • quarkus.couchbase.devservices.version (build-time)

    • String: The version of the Couchbase server to use for DevServices. See Docker Hub for available versions.

    • Default: latest

  • quarkus.couchbase.metrics.enabled (build-time)

    • Boolean: Enable or disable Micrometer metrics.

    • Default: false

  • quarkus.couchbase.metrics.emit-interval

    • Seconds: The interval at which metrics are emitted.

    • Default: 600 (10min)

  • quarkus.couchbase.bucket-name

    • String: A bucket exposed as an injectable Bucket bean. Only required if a Bucket is injected. When DevServices starts a container, this bucket is also provisioned in it so the injected Bucket is immediately usable. If unset, DevServices creates no bucket.

    • Default: None

  • quarkus.couchbase.preferredServerGroup

    • String: The preferred server group for operations which support it.

    • Default: None

  • quarkus.couchbase.health.enabled (build-time)

    • Boolean: Enable or disable SmallRye health checks (Readiness check).

    • Default: true

  • quarkus.couchbase.health.readiness.timeout

    • Seconds: The timeout for the extension’s Readiness health check.

    • Default: 3

Security

Refer to the Couchbase Java SDK Documentation for further details on security options. All the following options use the underlying Couchbase Java SDK’s default values if unset.

  • quarkus.couchbase.security.enableTls

    • Boolean: Enable or disable TLS.

  • quarkus.couchbase.security.enableHostnameVerification

    • Boolean: Enable or disable hostname verification when validating the remote certificate.

  • quarkus.couchbase.security.enableNativeTls

    • Boolean: Enable or disable netty native TLS (OpenSSL) used for better performance.

  • quarkus.couchbase.security.ciphers

    • String: A comma-separated list of cipher suites to enable.

  • quarkus.couchbase.security.trustCertificate

    • String: A path to a single PEM-encoded certificate file.