- Concept
- Version · 6.0
- Create
Use SQL or modeled changelogs
Last updated: September 29, 2026
SQL gives you exact, reviewable statements. Modeled changelogs give you portability and automatic rollback. Both are supported, and you can mix them.
Liquibase accepts changelogs in SQL, XML, YAML, and JSON. All four formats are fully supported. They trade different things, and the right choice depends on who reviews your changes and how many database platforms you target.
What each format gives you
Format | Strengths | Trade-offs |
|---|---|---|
SQL | The exact statements that will run, in your database's own dialect. Easiest for DBAs to review, and existing SQL scripts can be adopted with a header comment. | Rollback must be written by hand for each changeset. The changelog is tied to one database platform. |
Modeled (XML, YAML, JSON) | Describes the change abstractly, so one changelog can target multiple database platforms. Liquibase generates automatic rollback for many change types. | Reviewers see the model, not the literal SQL. Use |
Complete files in every format are in the examples. See the SQL changelog example, the XML changelog example, the YAML changelog example, and the JSON changelog example.
Formatted SQL changelogs
A SQL changelog is a plain .sql file with Liquibase metadata in comments. The file starts with a --liquibase formatted sql header, and each changeset is introduced by a --changeset author:id comment. This is what lets an existing SQL script become a tracked changelog without rewriting it.
Rollback is the biggest difference
Modeled changelogs get automatic rollback for many change types. Liquibase knows how to reverse a change it modeled, such as dropping a table it created. See What automatic rollbacks does Liquibase support?. A SQL changeset carries no model, so you write its rollback statements yourself. The rollback strategy guides cover both paths. See Implement a rollback strategy with SQL changelogs and Implement a rollback strategy with modeled changelogs (XML, YAML, JSON).
Mixing formats
You can mix formats in one project. A root changelog includes SQL and modeled changelogs side by side, so teams choose per change or per component rather than once for the whole project. See Connect your changelogs using include or includeAll.