Connect Liquibase with Couchbase

Couchbase is a distributed NoSQL document database that combines the capabilities of a key-value store and a document database. For more information, see https://docs.couchbase.com/.

Starting with Liquibase Secure 5.1, Couchbase support is included in-the-box. You do not need to install an extension separately.

Before you begin

  • Install Liquibase

  • Ensure you have Java installed. Liquibase requires Java to run. If you used the Liquibase Installer, Java is included automatically. Otherwise, you must install Java manually.

  • Gather these values for your Couchbase cluster:

    - The Couchbase cluster connection string or URL

    - Valid username and password with appropriate permissions

    - Network connectivity to the cluster

Procedure

1

(Maven users only) Configure Maven

If you're running Liquibase using the Maven plugin using mvn liquibase:update installing the extension with Maven ensures the right files are available and everything works together automatically. You can manage these extensions by adding them as dependencies in your project’s pom.xml file. When configured this way, Maven automatically downloads the specified JAR files from Maven Central during the build process.

2

Configure connection

1. Ensure your Couchbase cluster is running and accessible from your network.

2. Specify the database URL in the liquibase.properties file (defaults file), along with other properties you want to set a default value for. Liquibase does not parse the URL. You can specify the URL using Couchbase's standard connection format:

url: couchbase://<host>:<port>

You can also specify connection parameters using command-line arguments or environment variables.

To use the following code samples, replace the variable text with the following:

<host>: The hostname or IP address of your Couchbase cluster (for example, 127.0.0.1)

<port>: The connection port (for example, 8091)

<your-username>: Your Couchbase cluster username

<your-password>: Your Couchbase cluster password

<path-to-changelog>: The relative path to your changelog file (for example, changelog.xml)

Note: The driver class must be set to liquibase.ext.couchbase.database.CouchbaseStubDriver for Couchbase connections. Unlike traditional SQL databases, Couchbase does not use a JDBC connection format.

url: couchbase://<host>:<port>
username: <your-username>
password: <your-password>
changeLogFile: <changelog-path>
driver: liquibase.ext.couchbase.database.CouchbaseStubDriver

3

Test your connection

1. Create a text file called changelog(.sql,.yaml,.json, or.xml) in your project directory and add a changeset.

If you already created a changelog using theinit projectcommand, you can use that instead of creating a new file. When adding onto an existing changelog, be sure to only add the changeset and to not duplicate the changelog header.

2. Navigate to your project folder in the CLI and run the Liquibase connect command to see whether the connection is successful.

liquibase connect

--liquibase formatted sql
--changeset your-name:1
--comment: Test connection to Couchbase
--rollback: SELECT 1;
--changeset your-name:2
--comment: Example changeset for Couchbase
--rollback: SELECT 1;

4

(Optional) Configure Couchbase-Specific Properties

You can customize Couchbase-specific behavior by creating a liquibase-couchbase.properties file in your project directory. This file is not required—Liquibase uses default values if the file is not present.

Create a file named liquibase-couchbase.properties and specify any properties you want to override:

Property

Default value

Description

serviceBucketName

liquibaseServiceBucket

The bucket where Liquibase stores changelog metadata and lock information

lockservice.lockTtl

PT3M

Lock time-to-live duration in ISO-8601 format (default: 3 minutes)

transaction.timeout

PT15S

Transaction timeout in ISO-8601 format (default: 15 seconds)

transaction.reactive.enabled

false

Enable reactive programming model for transactions

Note: Time values use ISO-8601 duration format. For example:

  • PT3M = 3 minutes

  • PT15S = 15 seconds

  • PT1H = 1 hour

Example liquibase-couchbase.properties file
 serviceBucketName=liquibaseServiceBucket
  lockservice.lockTtl=PT3M
  transaction.timeout=PT15S
  transaction.reactive.enabled=false