Secure 5.1.1: Couchbase preconditions

Couchbase preconditions

Last updated: July 13, 2026

Couchbase preconditions are extension-specific tags that check for the existence of Couchbase resources before executing a changeset. Use them inside a standard Liquibase <preConditions> block. In XML changelogs, all Couchbase precondition tags require the ext: namespace prefix.

Known limitations:

All Couchbase precondition tags require the ext: namespace prefix in XML changelogs. Make sure your changelog header includes the Couchbase extension schema location.
queryCustomCheck compares the full query result against expectedResultJson as an exact string match, including field names and value order.

Available preconditions

bucketExists

Checks whether a bucket with the specified name exists in the Couchbase cluster.

Attribute	Type	Description	Required
`bucketName`	String	The name of the bucket to check.	Yes

scopeExists

Checks whether a scope exists within a bucket.

Attribute	Type	Description	Required
`bucketName`	String	The name of the bucket containing the scope.	Yes
`scopeName`	String	The name of the scope to check.	Yes

collectionExists

Checks whether a collection exists within a scope.

Attribute	Type	Description	Required
`bucketName`	String	The name of the bucket containing the scope.	Yes
`scopeName`	String	The name of the scope containing the collection.	Yes
`collectionName`	String	The name of the collection to check.	Yes

documentExists

Checks whether a document with the specified key exists in a collection.

Attribute	Type	Description	Required
`bucketName`	String	The name of the bucket containing the collection.	Yes
`scopeName`	String	The name of the scope containing the collection.	Yes
`collectionName`	String	The name of the collection to check.	Yes
`key`	String	The document key to check for.	Yes

doesIndexExist

Checks whether a named secondary query index exists on a collection.

Attribute	Type	Description	Required
`bucketName`	String	The name of the bucket containing the collection.	Yes
`scopeName`	String	The name of the scope containing the collection.	Yes
`collectionName`	String	The name of the collection to check.	Yes
`indexName`	String	The name of the secondary index to check for.	Yes

doesPrimaryIndexExist

Checks whether a primary query index exists on a collection.

Attribute	Type	Description	Required
`bucketName`	String	The name of the bucket containing the collection.	Yes
`scopeName`	String	The name of the scope containing the collection.	Yes
`collectionName`	String	The name of the collection to check.	Yes
`indexName`	String	The name of the primary index to check for.	Yes

queryCustomCheck

Runs a SQL++ query against the cluster and checks whether the result matches the expected JSON value.

Attribute	Type	Description	Required
`query`	String	The SQL++ (N1QL) query to execute.	Yes
`expectedResultJson`	String	The expected query result as a JSON string. The actual result must match exactly.	Yes

<?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"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.19.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-couchbase-ext.xsd">

    <changeSet id="1" author="liquibase">
        <preConditions onFail="HALT">
            <ext:bucketExists bucketName="myBucket"/>
        </preConditions>
        <!-- Add change types here -->
    </changeSet>

</databaseChangeLog>

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "liquibase",
        "preConditions": [
          {
            "onFail": "HALT",
            "bucketExists": {
              "bucketName": "myBucket"
            }
          }
        ]
      }
    }
  ]
}

databaseChangeLog:
  - changeSet:
      id: '1'
      author: liquibase
      preConditions:
        - onFail: HALT
          bucketExists:
            bucketName: myBucket

<?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"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.19.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-couchbase-ext.xsd">

    <changeSet id="1" author="liquibase">
        <preConditions onFail="HALT">
            <ext:bucketExists bucketName="myBucket"/>
        </preConditions>
        <!-- Add change types here -->
    </changeSet>

</databaseChangeLog>

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "liquibase",
        "preConditions": [
          {
            "onFail": "HALT",
            "bucketExists": {
              "bucketName": "myBucket"
            }
          }
        ]
      }
    }
  ]
}

databaseChangeLog:
  - changeSet:
      id: '1'
      author: liquibase
      preConditions:
        - onFail: HALT
          bucketExists:
            bucketName: myBucket

Couchbase preconditions

Available preconditions

bucketExists

scopeExists

collectionExists

documentExists

doesIndexExist

doesPrimaryIndexExist

queryCustomCheck

XML example

JSON example

YAML example

More like this