What support does Liquibase have for Couchbase?

Verified database versions

Minimum supported version is 7.0 As it uses the latest Couchbase SDK, this extension supports fully qualified keyspaces Bucket.Scope.Collection Which are incompatible with the < 7.0 Cluster version

Command support

Update commands

The following update commands are supported:

• update

• update-count

• update-one-changeset

• update-testing-rollback

• update-to-tag

The following commands are not supported. These are SQL-specific and not intended for NoSQL databases like Couchbase.

• update-count-sql

• update-one-changeset-sql

• update-sql

• update-to-tag-sql

Note: The -sql variant commands fail because they generate SQL output, which is not applicable to Couchbase's NoSQL architecture.

Rollback commands

Rollback functionality is supported only for selected changesets. Only specific changesets can be automatically rolled back due to the nature of Couchbase's data structures.

The following rollback commands are supported:

• rollback

• rollback-count

• rollback-one-changeset

• rollback-one-update

• rollback-to-date

The following rollback commands are not supported. These are SQL-specific and not intended for NoSQL databases like Couchbase.

• future-rollback-count-sql

• future-rollback-from-tag-sql

• future-rollback-sql

• rollback-sql

• rollback-count-sql

• rollback-one-changeset-sql

• rollback-one-update-sql

• rollback-to-date-sql

Note: The -sql variant commands fail because they generate SQL output, which is not applicable to Couchbase's NoSQL architecture.

Database inspection commands

The following database inspection commands are not currently supported for Couchbase:

• diff

• diff-changelog

• generate-changelog

• snapshot

• snapshot-reference

Couchbase uses a non-JDBC connection type that is incompatible with Liquibase's inspection framework. These commands report that they are not supported and exit with a non-zero status. A pipeline that gates on the exit code treats the run as a failure.

Change tracking commands

Most change tracking commands are supported. For example:

• connect

• history

• status

• unexpected-changesets

Not supported:

dbcl-history - DATABASECHANGELOGHISTORY functions are not yet implemented for Couchbase

Utility commands

The following utility commands are supported:

• calculate-checksum

• changelog-sync

• changelog-sync-to-tag

• clear-checksums

• list-locks

• mark-next-changeset-ran

• release-locks

• set-contexts

• set-labels

• tag

• validate

The following utility commands are not supported:

• changelog-sync-sql - Not intended for NoSQL databases; generates SQL output

• changelog-sync-to-tag-sql - Not intended for NoSQL databases; generates SQL output

• mark-next-changeset-ran-sql - Not intended for NoSQL databases; generates SQL output

• db-doc - Requires a JDBC connection, which Couchbase does not use

• drop-all - Requires a JDBC connection, which Couchbase does not use

• execute-sql - Not supported for Couchbase

• tag-exists - Reports incorrect tag state

Note: Like the database inspection commands, db-doc and drop-all report that they are not supported and exit with a non-zero status.

Supported change types

Liquibase supports the following Couchbase-specific change types:

Bucket operations

• Create bucket

• Update bucket

• Drop bucket

Scope operations

• Create scope

• Drop scope

Collection operations

• Create collection

• Drop collection

Index operations

• Create index (primary and secondary)

• Drop index

Document operations

• Insert document(s) (either plain JSON inside the XML or JSON files)

• Upsert document(s) (either plain JSON inside the XML or JSON files)

• Mutate document

• Remove document(s)

Query operations

• Execute query

• SQL file (non-reactive only)

Preconditions

Liquibase supports the following preconditions for Couchbase:

• Bucket exists

• Scope exists

• Collection exists

• Index exists (primary and secondary)

• Document exists

• SQL check

Features support

Changelog validation

Liquibase validates the structure of a Couchbase changelog before it runs any changesets. What gets checked depends on the format:

• XML: Validated against the Couchbase XSD.

• JSON: Validated against the Couchbase JSON schema.

• YAML: Not validated against a Couchbase schema. A malformed Couchbase change fails when it runs rather than when Liquibase parses the file.

The JSON schema covers every Couchbase change type. It enforces which properties each change requires, rejects a property the change does not define, and applies the same either/or rules the XSD applies to XML. For example, insertDocuments and upsertDocuments take exactly one of document, documents, or importFile, and removeDocuments takes exactly one of id, whereCondition, or sqlPlusPlusQuery.

When a JSON changelog fails validation, the command stops with The provided [changelog.json] changelog file has invalid structure, and the log lists each property that failed and why.

Note: A misspelled property name fails validation, because the schema rejects any property a change does not define. Run validate against your existing JSON changelogs to check them before your next deployment.

Targeted rollbacks

Targeted rollbacks are supported for Couchbase, but only specific changesets can be automatically rolled back. Review your changelog carefully to ensure rollback compatibility.

Liquibase checks

• Changelog checks: Fully supported

• Database checks: Not supported - Database-scoped checks fail due to connection type incompatibility

Observability

Liquibase Secure observability features have the following support levels:

• Update reports: Fully supported

• Rollback reports: Fully supported

• Drift reports: Not supported - Fails due to general diff command limitations

• Checks run reports: Fully supported

• Structured logging: Not supported

Flows

The flow command is fully supported for Couchbase workflows.

Credentials vaults

Liquibase Secure supports the following credentials vault integrations with Couchbase:

• AWS Secrets Manager: Supported, but commands execute more slowly when using S3 compared to local file access

• AWS Systems Manager: Fully supported

• HashiCorp Vault: Fully supported

Note: When using AWS S3 for credentials, you may experience longer execution times. This is a known behavior under investigation.

Tracking collection indexes

Liquibase creates a secondary index on meta().id for each tracking collection, named liquibase_DATABASECHANGELOG_idx and liquibase_CHANGELOGLOCKS_idx. It does not create a primary index. Couchbase recommends secondary indexes over primary indexes for production queries. Because meta().id is present on every document, the secondary index covers the same documents a primary index would.

Custom queries need a predicate: Couchbase uses a secondary index only when the query filters on the index key. A query against a tracking collection with no WHERE clause is served by no index. On Couchbase 7.2 and earlier that query fails, and on 7.6 and later it falls back to a sequential scan. Add a predicate such as WHERE meta().id IS NOT MISSING to any custom query, script, or dashboard that reads these collections. Liquibase's own queries already include one.

Existing deployments keep their primary index: Liquibase does not drop a primary index it finds, so a deployment upgraded from an earlier version keeps using it. To move to the secondary index, drop the primary index once. Liquibase does not recreate it.

Note: Running an earlier version of Liquibase against the same database recreates a primary index on both tracking collections. Liquibase leaves that index in place, and the Couchbase query planner prefers it. A single run of an earlier version therefore returns the deployment to using a primary index, with nothing reported to the operator. Drop the index again to undo it.

DATABASECHANGELOGHISTORY table

The DATABASECHANGELOGHISTORY (DBCLH) table feature is not currently supported for Couchbase.

Known limitations

• JDBC-based commands: Commands that require JDBC connections (diff, snapshot, generate-changelog, db-doc, drop-all) are not supported because Couchbase uses a non-JDBC connection type.

• Database inspection: Due to Couchbase's document-oriented architecture, traditional database inspection and comparison features are not available.

• Performance with cloud storage: When using AWS S3 as a credentials vault, command execution may be significantly slower than with local file access or other vault options.