What is a Changeset?
Last updated: July 14, 2025
A changeset is the basic unit of change in Liquibase. You store all your changesets in your Changelog. Your changesets contain Change Types that specify what each change does, like creating a new table or adding a column to an existing table.
A changeset is uniquely tagged by both the author and id attributes (author:id), as well as the changelog file path. The id tag is just an identifier—it doesn't direct the order that changes are run and doesn't have to be an integer. To deploy the changeset with the update command, you must include both author and id. You can specify Preconditions, Contexts, Labels, and other attributes in individual changesets to control exactly when they run.
It is a best practice to specify only one type of change per changeset. Doing so avoids failed auto-commit statements that can leave the database in an unexpected state. When you deploy your changes, each changeset either succeeds or fails; if it fails, you can correct it and deploy again. You can also add comments to individual changesets to explain why they're important.
By default, Liquibase runs changesets as a single transaction. You can modify this behavior with the runInTransaction attribute. Once you run a changeset, Liquibase does not re-run it unless you specify runAlways or runOnChange for that changeset.
What is a changeset?
Liquibase source control workflow
File formats
The format of your changeset depends on the file type of your changelog, which can be SQL, XML, YAML, or JSON. See the pages linked in the following drop-down tabs for examples of entire changelogs in each format.
Changeset examples
--changeset nvoxland:1
create table company (
id int primary key,
address varchar(255)
);
Runtime logic
When you run a database update, Liquibase reads the changesets in your changelog in order. For each one, it checks the DATABASECHANGELOG table to see if the combination of id/author/filepath has already been deployed.
If a changeset has already been deployed to your database, Liquibase skips it unless it has a runAlways=true tag. After running all the changes in the changesets, Liquibase inserts a new row with the id/author/filepath along with an MD5Sum (checksum) of the changeset in the DATABASECHANGELOG table. For more information, see Changeset Checksums.
Note: filepath is the path that defines the changelog-file attribute. Even if the same file is referenced with a different path, that is considered a different file unless the logicalFilePath is defined.
Liquibase attempts to execute each changeset in a transaction that is committed at the end, or rolled back if there is an error. Some databases auto-commit statements, which interferes with this transaction setup and could lead to an unexpected database state. Therefore, it is best practice to have just one change per changeset unless there is a group of non-auto-committing changes that you want to apply as a transaction such as inserting data.
runOnChange changeset attribute
<changeSet author="your.name" id="changeset01" runOnChange="true" >
<createProcedure>
. . .
</createProcedure>
</changeSet>