Task
Version · 6.0
Create

Connect Liquibase with Couchbase

Last updated: September 29, 2026

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

(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.

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

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

export LIQUIBASE_COMMAND_URL=couchbase://<host>:<port>
export LIQUIBASE_COMMAND_USERNAME=<your-username>
export LIQUIBASE_COMMAND_PASSWORD=<your-password>
export LIQUIBASE_COMMAND_CHANGELOG_FILE=<changelog-path>
export LIQUIBASE_COMMAND_DRIVER=liquibase.ext.couchbase.database.CouchbaseStubDriver

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

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

export LIQUIBASE_COMMAND_URL=couchbase://<host>:<port>
export LIQUIBASE_COMMAND_USERNAME=<your-username>
export LIQUIBASE_COMMAND_PASSWORD=<your-password>
export LIQUIBASE_COMMAND_CHANGELOG_FILE=<changelog-path>
export LIQUIBASE_COMMAND_DRIVER=liquibase.ext.couchbase.database.CouchbaseStubDriver

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;

databaseChangeLog:
    - changeSet:
        id: 1
        author: your-name
        comment: Test connection to Couchbase
        changes:
          - tagDatabase:
              tag: version_1.0

    - changeSet:
        id: 2
        author: your-name
        comment: Example changeset for Couchbase
        changes:
          - tagDatabase:
              tag: version_1.1

{
    "databaseChangeLog": [
      {
        "changeSet": {
          "id": "1",
          "author": "your-name",
          "comment": "Test connection to Couchbase",
          "changes": [
            {
              "tagDatabase": {
                "tag": "version_1.0"
              }
            }
          ]
        }
      },
      {
        "changeSet": {
          "id": "2",
          "author": "your-name",
          "comment": "Example changeset for Couchbase",
          "changes": [
            {
              "tagDatabase": {
                "tag": "version_1.1"
              }
            }
          ]
        }
      }
    ]

 <?xml version="1.0" encoding="UTF-8"?>
  <databaseChangeLog
      xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

      <changeSet id="1" author="your-name">
          <comment>Test connection to Couchbase</comment>
          <tagDatabase tag="version_1.0"/>
      </changeSet>

      <changeSet id="2" author="your-name">
          <comment>Example changeset for Couchbase</comment>
          <tagDatabase tag="version_1.1"/>
      </changeSet>

  </databaseChangeLog>

 --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;

databaseChangeLog:
    - changeSet:
        id: 1
        author: your-name
        comment: Test connection to Couchbase
        changes:
          - tagDatabase:
              tag: version_1.0

    - changeSet:
        id: 2
        author: your-name
        comment: Example changeset for Couchbase
        changes:
          - tagDatabase:
              tag: version_1.1

{
    "databaseChangeLog": [
      {
        "changeSet": {
          "id": "1",
          "author": "your-name",
          "comment": "Test connection to Couchbase",
          "changes": [
            {
              "tagDatabase": {
                "tag": "version_1.0"
              }
            }
          ]
        }
      },
      {
        "changeSet": {
          "id": "2",
          "author": "your-name",
          "comment": "Example changeset for Couchbase",
          "changes": [
            {
              "tagDatabase": {
                "tag": "version_1.1"
              }
            }
          ]
        }
      }
    ]

 <?xml version="1.0" encoding="UTF-8"?>
  <databaseChangeLog
      xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
      http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

      <changeSet id="1" author="your-name">
          <comment>Test connection to Couchbase</comment>
          <tagDatabase tag="version_1.0"/>
      </changeSet>

      <changeSet id="2" author="your-name">
          <comment>Example changeset for Couchbase</comment>
          <tagDatabase tag="version_1.1"/>
      </changeSet>

  </databaseChangeLog>

(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

PreviousWhat support does Liquibase have for Couchbase?NextWhat Databricks features does Liquibase support?

Connect Liquibase with Couchbase

Before you begin

Procedure

(Maven users only) Configure Maven

Configure connection

Properties file

CLI

Environment variables

Test your connection

SQL

YAML

JSON

XML

(Optional) Configure Couchbase-Specific Properties

Example liquibase-couchbase.properties file

Next steps