Create a database change

A database change in Liquibase is a changeset inside a changelog: a small, uniquely identified unit that deploys once and is tracked forever. This page is the whole model and the task in one place — what changelogs and changesets are, and how to author a change well.

What is a changelog?

An individual unit of change in your changelog is called a Changeset. When modifying your database, simply add a new changeset and specify its operation as a Change Type. For example, you may add a changeset to create a new table, and another changeset to drop a primary key.

You can also include other changelogs in a main changelog, minimizing conflicts between different teams or workflows. You can also specify preconditions, contexts, labels, and other attributes in your changelog to precisely control which changesets run—and in which environments.

When you run the update command, Liquibase deploys the changes you specify in your changelog to your database. You can specify which changelog you want to use with the --changelog-file argument in your command line (CLI), your liquibase.properties file, as an environment variable, or using the JAVA_OPTS Environment Variable.

To learn more about using changelogs and changesets, see Introduction to Liquibase. If you understand the basics of Liquibase and want to learn how to structure your changelogs, see Design Your Liquibase Project.

File formats

Your changelogs can be written in the SQL, XML, YAML, JSON formats. For Liquibase Secure users, Formatted Mongo format is also supported. Liquibase determines the changelog format by the file extension and the changelog header. If you are using the include or includeAll tags in your root changelog to reference other changelogs, your root changelog must be an XML, YAML, JSON, or Formatted Mongo file. Click the drop-downs to see examples.

Liquibase uses two models for changelogs:

• The SQL model (.sql files): Write SQL statements directly in changesets in your changelog, formatted with SQL comments.

• The platform-agnostic model (.xml, .yaml, and .json files): Use Liquibase Change types corresponding to SQL changes in each changeset. Liquibase then generates database-specific SQL for you. You can also insert raw SQL statements in your changesets using the SQL Change type or reference a SQL file with the SQLFile Change type.

Note: You can simultaneously use one or more different changelog formats with Liquibase.

Here are some qualities to consider when choosing a changelog format for Liquibase:

• Familiarity:

  If you already know the syntax for one of the formats, you can easily use it with Liquibase.

• Tools:

  If your existing tools and processes are built around a particular format, such as SQL, you can easily integrate changelogs of that format.

• Appearance:

  XML syntax is specific but verbose. If you want a less verbose format, try SQL, YAML, or JSON.

• Specificity:

  Formatted SQL changelogs let you control exactly what SQL to run. In contrast, XML, YAML, and JSON also support raw SQL statements, but are primarily meant to describe what kind of change you want to make: Liquibase handles the underlying database logic for you. XML, YAML, and JSON changelogs can be helpful if you're working with multiple databases and don't want to write database-specific SQL, or if you want Liquibase to generate automatic rollback statements for some changes.

The following examples demonstrate the structure of a changelog using generic terms. See the "Example Changelogs" pages linked in the drop-down tabs for examples that use real change types and preconditions.

Runtime logic

When you run a database update, the Liquibase migrator detects the changelog file type from the file extension and parses the changelog header. Liquibase checks any global preconditions specified. If any global preconditions fail, Liquibase exits with an error message explaining what failed. Preconditions can typically be used for both documenting and enforcing expectations or assumptions. For example, you can specify the DBMS to be run against the changelog or the user you should log in to run changes.

If all preconditions are met, Liquibase will begin running the changeset and include tags in the order they appear in the changelog file. You can control which changesets run in a particular migration using contexts, labels, and other attributes on the changeset level. Liquibase uses the DATABASECHANGELOG table to keep track of which changes it has already deployed. In Liquibase 4.27.0 and later, Liquibase also records additional migration information in the DATABASECHANGELOGHISTORY table.

Each changeset contains the id and author tags. The id tag, author tag, search path location, and name of the changelog file create a unique identifier for the changeset.

Note: The XML schema for the changelog tag is available at: http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd. The version of the XSD can be set to either latest to match your current version of Liquibase, or latest can be replaced with a specific version, like http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.25.xsd. Legacy XSDs are listed on the XML Format page.

Attributes

You can apply these attributes to your whole changelog:

Nested elements

You can use these tags in the body of your changelog or sometimes within another nested element:

Note: The tables above only list attributes and elements at the top level of a changelog. You can apply contexts, labels, and other Changelog Attributes on individual changesets.

What is a changeset?

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.

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.

Create the change

Keep one logical change per changeset — it makes failures precise, rollbacks surgical, and the tracking record readable. Pick your format deliberately (Use SQL or modeled changelogs), start from a working example in the changelog examples, and define the rollback while the change is fresh (Create custom rollback statements). Then validate before you commit.