Liquibase ChangeSet file

ChangeSet is the basic unit of ChangeLog file. each Database change is stored in ChangeSet and marked with Change Type to specify what each ChangeSet does for example creating a new table or adding a new column.

Each ChangeSet is uniquely defined by author and id attributes.

<changeSet author="wesome (generated)" id="1692352246983-1">

The id attribute is just an identifier to distinguish between each ChangeSet, it doesn't govern the order of execution of ChangeSet. The id attribute doesn't have to be an integer only and can be of string type as well. along with these, ChangeSet supports Preconditions, Contexts, and Labels, to control exactly when they run.

It is a best practice to specify only one type of change per changeset

Each ChangeSet is responsible for a unit change in Database. Liquibase supports the rollback of individual ChangeSet as well. if multiple Changes as clubbed in a single ChangeSet then it will be hard to rollback individual changes.

For example, the Apple table creation and primary key assignment changes are mentioned in a single ChangeSet as shown below.

-- liquibase formatted sql

-- changeset wesome:1692352309571-1
CREATE TABLE apple (apple_id BIGINT NOT NULL, apple_name VARCHAR(255));
ALTER TABLE apple ADD CONSTRAINT PK_APPLE PRIMARY KEY (apple_id);

--rollback ALTER TABLE apple DROP PRIMARY KEY;
--rollback DROP TABLE apple;

Assume the Apple table is fine but due to some issues the primary key constraint needs to be dropped, Liquibase supports ChangeSet to ChangeSet rollback, so the rollback command to revert the previous ChangeSet is.

liquibase rollback-count --count=1

but since both, the table creation and primary key assignment query are mentioned under a single ChangeSet, the rollback will drop the primary key constrain as well as drop the table as well. the correct ChangeLog file should be.

-- liquibase formatted sql

-- changeset wesome:1692352309571-1
CREATE TABLE apple (apple_id BIGINT NOT NULL, apple_name VARCHAR(255)); 
--rollback DROP TABLE apple; 

-- changeset wesome:1692352309572-1 
ALTER TABLE apple ADD CONSTRAINT PK_APPLE PRIMARY KEY (apple_id);
--rollback ALTER TABLE apple DROP PRIMARY KEY;

now run the same rollback command

liquibase rollback-count --count=1

this time Liquibase will drop the primary key constrain but the table will remain intact.

ChangeSet format depends upon the file type of ChangeLog, Liquibase supports SQL, XML, YAML, or JSON, below are sample ChangeLog in each format.

SQL ChangeSet

-- changeset wesome:1692352309571-1
CREATE TABLE apple (apple_id BIGINT NOT NULL, apple_name VARCHAR(255) NULL, CONSTRAINT PK_APPLE PRIMARY KEY (apple_id));

XML ChangeSet

<changeSet author="wesome (generated)" id="1692361922797-1">
        <createTable tableName="apple">
            <column name="apple_id" type="BIGINT">
                <constraints nullable="false" primaryKey="true"/>
            </column>
            <column name="apple_name" type="VARCHAR(255)"/>
        </createTable>
</changeSet>

YAML ChangeSet

  - changeSet:
      id: 1692352255676-1
      author: wesome (generated)
      changes:
        - createTable:
            columns:
              - column:
                  constraints:
                    nullable: false
                    primaryKey: true
                  name: apple_id
                  type: BIGINT
              - column:
                  name: apple_name
                  type: VARCHAR(255)
            tableName: apple

JSON ChangeSet

 "changeSet": {
        "id": "1692352264594-1",
        "author": "wesome (generated)",
        "changes": [
          {
            "createTable": {
              "columns": [
                {
                  "column": {
                    "constraints": {
                      "nullable": false,
                      "primaryKey": true
                    },
                    "name": "apple_id",
                    "type": "BIGINT"
                  }
                },
                {
                  "column": {
                    "name": "apple_name",
                    "type": "VARCHAR(255)"
                  }
                }
              ],
              "tableName": "apple"
            }
          }
        ]
      }