- Task
- Version · 6.0.2
- Create
Decorate a folder of SQL scripts
Last updated: November 17, 2026
Convert every SQL script in one or more folders into Liquibase changelogs in a single run of decorate-sql. Liquibase writes a changelog beside each script and a root changelog that includes them all, so you deploy the whole set with one update.
Before you begin
Liquibase Secure must be installed, with your license key applied. See Apply your license key.
To deploy the changelogs, Liquibase needs a connection to your database. Set
url,username, andpasswordinliquibase.properties, asLIQUIBASE_COMMAND_*environment variables, or with--url,--username, and--password. See Connect Liquibase to your database.The scripts must be written for one database dialect, Oracle or SQL Server.
--db-type,--url,--executor, and--authorapply to every script in the run, so run the command once for each set of scripts that needs a different dialect or executor, with its own root changelog.Only files that end in
.sqlare decorated.If a script has a Down script that reverses it, decorate that pair on its own. See Decorate paired Up and Down migration scripts.
Procedure
Name the scripts in the order they must deploy
Before you run decorate-sql, name the files in each folder so they sort in the order they must deploy. For example, 010_orders.sql and 020_customers.sql.
The root changelog that decorate-sql writes includes the scripts in this order:
Each
--sql-fileentry, in the order you list them.Each
--sql-folder, in the order you list them.Within a folder, each file sorted by file name.
A script that you name more than once, for example in --sql-file and through a folder, is decorated once.
For example, this command decorates two folders. You run it in the next step.
If day2 holds 010_orders.sql and 020_customers.sql, and day3 holds 010_view.sql, the root changelog includes them in this order:
sql/release2/day2/010_orders.sqlsql/release2/day2/020_customers.sqlsql/release2/day3/010_view.sql
Run decorate-sql on the folders
Pass one or more folders, separated by commas, with --sql-folder, or a comma-separated list of files with --sql-file. Folders you do not name are not read, and subfolders are skipped unless you pass --recursive=true.
Name the root changelog with --changelog-file. It must end in .xml, .yaml, or .json, because a formatted SQL changelog cannot include other changelogs.
The run writes nothing until every script decorates successfully. If one script fails, the error names it and no changelogs are written, not even for the scripts that succeeded. Fix the script the error names, then run the command again. For other errors, see If the run fails below.
Review the generated changelogs
Liquibase writes one changelog beside each script, with the same extension as the root changelog, so sql/release2/day2/010_orders.sql becomes sql/release2/day2/010_orders.xml. The root changelog includes each one:
Each changeset's comment names its script by the path you typed, or by its path relative to its --search-path location, as in line 1 of sql/release2/day2/010_orders.sql. A committed changelog therefore holds no s3:// address and no path from your machine. Errors and warnings on the terminal give that name followed by the full location in parentheses, when the two differ.
Check how the statements were grouped and named before you deploy. See How decorate-sql builds changesets.
decorate-sql does not check that your SQL is valid. It copies each statement into a changeset as written, so a syntax error decorates without a warning and fails when you run update. Deploy to a test database first to catch errors in the SQL itself.
Deploy the root changelog
Deploy the root changelog with update. If the scripts are in Amazon S3 under a --search-path location, pass the same --search-path.
liquibase update --changelog-file=release2.xmlIf the run fails
If a script cannot be decorated, the error names the script and nothing is written. Fix that script and run the command again.
Liquibase checks every output path before it writes anything, whatever --overwrite-output-file is set to, so one write cannot replace another script's changelog or one of your scripts. It checks each file again just before writing it. Each error names the scripts involved and the file they share.
Error | Cause | What to do |
|---|---|---|
| A script is not saved as UTF-8. | Save the script as UTF-8, or set |
| A script is empty or holds only comments, so it produces no changesets. | Add the SQL the script should hold, or remove it from the folder. |
| A | Move the marker below the statement it undoes, or remove it. |
| The root changelog already exists. | Pass |
| A script's changelog already exists. | Pass |
| The inputs hold no | Check the path. Add |
|
| Decorate the pair on its own. See Decorate paired Up and Down migration scripts. |
| The root changelog ends in | Use |
| A write failed partway through. Liquibase deleted the changelogs the run created and restored any it replaced. | Fix the cause, then run the command again. |
| Two outputs have the same path. For example, | Rename |
| A local | Check the spelling. A relative path is resolved against the current directory and each |
| The root changelog could not include the changelogs written to S3. | Put the scripts under a |
| A run that wrote changelogs to S3 failed. Liquibase cannot delete files from S3, so the error names the changelogs it left behind. | Delete them before you run the command again, or pass |
| Liquibase could not restore a changelog it replaced. The error names the files. | Recover those files from source control before you run the command again. |
| Two different paths lead to one file, through a symbolic link, a hard link, or names that differ only in letter case on macOS and Windows. For example, | Point the link elsewhere or remove it, or rename |
| An output path is a symbolic or hard link to one of the | Remove the link or point it somewhere that is not a script, or move the script out of the batch. |
|
| Remove the script from all but one |
Liquibase detects hard links on Linux and macOS but not on Windows, where a hard link is compared by its path. When a failed run removes a changelog it wrote through a symbolic link, it deletes the file the link points to and keeps your link.