- Reference
- Version ยท 6.0.2
- Change Automation Reference
decorate-sql
Last updated: November 17, 2026
The decorate-sql command converts a raw SQL file into a Liquibase changelog without connecting to a database. It supports only Microsoft SQL Server (MSSQL) and Oracle. If you pass any other database type, the command fails with an error.
Uses
The decorate-sql command is used when you already have raw SQL scripts and want to bring them under Liquibase management. Because the command never opens a database connection, you can review the generated changelog, and run policy checks against it, before you deploy anything with update. That way, problems such as a statement split in the wrong place or a risky DROP TABLE cost a quick edit to the changelog, not a fix to a live database.
decorate-sql keeps each statement as you wrote it and adds what Liquibase needs to track it: a changeset with an ID and an author around each statement or group of statements, and attributes such as runOnChange where they apply. For example, take this SQL Server script:
When you run decorate-sql on it with --changelog-file=changelog.sql and --db-type=mssql, you get this formatted SQL changelog:
When update deploys the changelog, Liquibase records each changeset in the DATABASECHANGELOG table, so a later update runs only the changesets that have not run yet. The GO lines are dropped, because each batch is already its own changeset. The view gets runOnChange:true, so an edited definition is deployed again.
For step-by-step instructions, see:
Run the decorate-sql command
To convert a raw SQL file to a changelog:
Step 1: Name the output changelog file
The extension you give the file sets the output format: .xml, .yaml, .json, or .sql.
Step 2: Choose the database dialect
Pass --db-type with oracle or mssql. Or pass --url with a JDBC URL, and Liquibase infers the dialect from the URL prefix. Liquibase reads only the URL string and never opens a connection, so the command still runs offline. If you pass both, they must name the same dialect. These are the only supported dialects. Any other --db-type value fails with LB-CMD-0021, and a --url for any other database fails with LB-CMD-0029.
Step 3: Run the command
Pass the raw SQL file with --sql-file, the output changelog file with --changelog-file, and the dialect. For every parameter and its allowed values, see Parameters. For example:
Parameters
The following tabs list every decorate-sql parameter, whether it is required, and its allowed values or default.
Global parameters
--license-key=<string>
Required.
Your Liquibase Secure license key.
Command parameters
--sql-file=<string>
Required unless you set --sql-folder.
Raw SQL input file to decorate into a Liquibase changelog. Pass a comma-separated list to decorate several files in one run.
--sql-folder=<string>
Required unless you set --sql-file.
One or more folders, separated by commas, whose .sql files are decorated in one run. Folders are read in the order you list them, and the files in each folder in file name order. Each script gets its own changelog beside it, and --changelog-file becomes the root changelog that includes them.
--recursive=<boolean>
Optional. Default: false
Also decorates the .sql files in the subfolders of each folder. Has no effect without a folder.
--changelog-file=<string>
Required.
Output changelog file. The format is inferred from the extension: .sql, .xml, .yaml, .yml, or .json. A .sql file name needs no database type segment. If it has one, as in changelog.oracle.sql, it must match the dialect. In batch mode, this is the root changelog, and it cannot be .sql.
--db-type=<string>
Required unless you set --url.
Database dialect used to classify SQL statements. Supported values: oracle, mssql. Not needed when you set a URL. If you set both, they must name the same dialect.
--url=<string>
Optional.
JDBC URL used to infer the database dialect from its prefix. Liquibase reads only the URL string and never opens a connection.
If you pass neither --db-type nor --url, Liquibase falls back to a URL set for all commands, such as liquibase.command.url in liquibase.properties or the LIQUIBASE_COMMAND_URL environment variable, and prints a notice naming the dialect it used. A fallback URL for a database that decorate-sql does not support is ignored rather than failing the command. When you pass --db-type, any fallback URL is ignored.
--executor=<string>
Optional.
Native executor attached to every synthesized changeset, either sqlplus or sqlcmd. Sets runWith on each changeset. Omit to run through JDBC.
--author=<string>
Optional. Default: raw-sql
Author stamped on every synthesized changeset.
--overwrite-output-file=<boolean>
Optional. Default: false
Allows an existing output changelog file to be overwritten. When false, an existing output file fails validation.
--rollback-file=<string>
Optional.
Rollback SQL file to pair with --sql-file. Switches the command into atomic-pair mode, described in Decorate paired Up and Down migration scripts. Works only with a single --sql-file, not with batch input.
--allow-in-block-txn-control=<boolean>
Optional. Default: false
Skips the check that fails the command when an Oracle PL/SQL block contains COMMIT or a bare ROLLBACK. Use it only when the block needs its own transaction control.
--allow-txn-control-loss=<boolean>
Optional. Default: false
Removes SAVEPOINT, SAVE TRANSACTION, and ROLLBACK statements outside a block, Oracle SET TRANSACTION, and a SQL Server SET TRANSACTION in a changelog that runs through a native executor, instead of failing the command. The changelog then does not reproduce the transaction behavior they define.
--allow-dialect-mismatch=<boolean>
Optional. Default: false
Decorates the file even when it contains syntax that only the other dialect accepts, and prints a warning instead of failing the command.
Global parameters
Attribute | Definition | Requirement |
|---|---|---|
| Your Liquibase Secure license key. | Required |
Command parameters
Attribute | Definition | Requirement |
|---|---|---|
| Raw SQL input file to decorate into a Liquibase changelog. Pass a comma-separated list to decorate several files in one run. | Required unless you set a folder |
| One or more folders, separated by commas, whose | Required unless you set a SQL file |
| Also decorates the | Optional |
| Output changelog file. The format is inferred from the extension: | Required |
| Database dialect used to classify SQL statements. Supported values: | Required unless you set a URL |
| JDBC URL used to infer the database dialect from its prefix. Liquibase reads only the URL string and never opens a connection. | Optional |
| Native executor attached to every synthesized changeset, either | Optional |
| Author stamped on every synthesized changeset. Default: | Optional |
| Allows an existing output changelog file to be overwritten. When | Optional |
| Rollback SQL file to pair with | Optional |
| Skips the check that fails the command when an Oracle PL/SQL block contains | Optional |
| Removes | Optional |
| Decorates the file even when it contains syntax that only the other dialect accepts, and prints a warning instead of failing the command. Default: | Optional |
Global parameters
Attribute | Definition | Requirement |
|---|---|---|
| Your Liquibase Secure license key. | Required |
Command parameters
Attribute | Definition | Requirement |
|---|---|---|
| Raw SQL input file to decorate into a Liquibase changelog. Pass a comma-separated list to decorate several files in one run. | Required unless you set a folder |
| One or more folders, separated by commas, whose | Required unless you set a SQL file |
| Also decorates the | Optional |
| Output changelog file. The format is inferred from the extension: | Required |
| Database dialect used to classify SQL statements. Supported values: | Required unless you set a URL |
| JDBC URL used to infer the database dialect from its prefix. Liquibase reads only the URL string and never opens a connection. | Optional |
| Native executor attached to every synthesized changeset, either | Optional |
| Author stamped on every synthesized changeset. Default: | Optional |
| Allows an existing output changelog file to be overwritten. When | Optional |
| Rollback SQL file to pair with | Optional |
| Skips the check that fails the command when an Oracle PL/SQL block contains | Optional |
| Removes | Optional |
| Decorates the file even when it contains syntax that only the other dialect accepts, and prints a warning instead of failing the command. Default: | Optional |
Global parameters
Attribute | Definition | Requirement |
|---|---|---|
| Your Liquibase Secure license key. | Required |
Command parameters
Attribute | Definition | Requirement |
|---|---|---|
| Raw SQL input file to decorate into a Liquibase changelog. Pass a comma-separated list to decorate several files in one run. | Required unless you set a folder |
| One or more folders, separated by commas, whose | Required unless you set a SQL file |
| Also decorates the | Optional |
| Output changelog file. The format is inferred from the extension: | Required |
| Database dialect used to classify SQL statements. Supported values: | Required unless you set a URL |
| JDBC URL used to infer the database dialect from its prefix. Liquibase reads only the URL string and never opens a connection. | Optional |
| Native executor attached to every synthesized changeset, either | Optional |
| Author stamped on every synthesized changeset. Default: | Optional |
| Allows an existing output changelog file to be overwritten. When | Optional |
| Rollback SQL file to pair with | Optional |
| Skips the check that fails the command when an Oracle PL/SQL block contains | Optional |
| Removes | Optional |
| Decorates the file even when it contains syntax that only the other dialect accepts, and prints a warning instead of failing the command. Default: | Optional |
Global parameters
Attribute | Definition | Requirement |
|---|---|---|
| Your Liquibase Secure license key. | Required |
Command parameters
Attribute | Definition | Requirement |
|---|---|---|
| Raw SQL input file to decorate into a Liquibase changelog. Pass a comma-separated list to decorate several files in one run. | Required unless you set a folder |
| One or more folders, separated by commas, whose | Required unless you set a SQL file |
| Also decorates the | Optional |
| Output changelog file. The format is inferred from the extension: | Required |
| Database dialect used to classify SQL statements. Supported values: | Required unless you set a URL |
| JDBC URL used to infer the database dialect from its prefix. Liquibase reads only the URL string and never opens a connection. | Optional |
| Native executor attached to every synthesized changeset, either | Optional |
| Author stamped on every synthesized changeset. Default: | Optional |
| Allows an existing output changelog file to be overwritten. When | Optional |
| Rollback SQL file to pair with | Optional |
| Skips the check that fails the command when an Oracle PL/SQL block contains | Optional |
| Removes | Optional |
| Decorates the file even when it contains syntax that only the other dialect accepts, and prints a warning instead of failing the command. Default: | Optional |
Output changelogs
The extension you give --changelog-file determines the output format. Use .xml, .yaml, .json, or .sql.
A formatted SQL file name does not need a database type segment, so changelog.sql works. If the name includes a segment that is a Liquibase database short name, as in changelog.oracle.sql, it must match the dialect set by --db-type or --url, or the command fails. A segment that is not a database name, as in orders.v2.sql, is treated as part of the file name. The segment never sets the dialect.
Note: This rule is looser than the one for generate-changelog and diff-changelog, which reject a segment that is not a database short name. A name like orders.v2.sql works with decorate-sql but fails with those commands.
In formatted SQL output, Liquibase also rewrites any input comment that the changelog parser would read as a directive, such as -- changeset or -- property, to -- [comment] followed by the original text. The wording is kept, the changelog parses correctly, and a warning lists every rewritten line. Detection is line-based, so a matching line inside a multi-line string literal is rewritten too. XML, YAML, and JSON output are not affected.
Note: decorate-sql does not overwrite an existing output file. Pass --overwrite-output-file=true to replace one.
How decorate-sql builds changesets
Statements are grouped as follows:
DML statements batch together until another kind of statement interrupts them.
Each DDL statement and each PL/SQL block becomes its own changeset.
On SQL Server, a
GObatch that declares a variable stays together as one changeset.A changeset that holds a single Oracle
CREATE OR REPLACEor SQL ServerCREATE OR ALTERdefinition getsrunOnChange:true.
On SQL Server, a line holding only GO ends a batch:
The keyword is not case-sensitive.
The line can end with a
--comment, as inGO -- end of batch.A line such as
GO;orGO /* end */does not end a batch, becausesqlcmdrejects both.
String literals are handled as follows:
On Oracle and SQL Server, a backslash in a string literal is an ordinary character, so a literal such as
ESCAPE '\'orN'C:\'ends at its closing quote.When you write an Oracle changelog as a
.sqlfile, a DML batch stays in one changeset only ifupdatereads it back as the same statements. A statement that the formatted SQL parser would split differently gets its own changeset.If a single statement still cannot be read back as written, Liquibase prints a warning and suggests rewriting any string literal that ends in a backslash, for example
ESCAPE '!'instead ofESCAPE '\'.
Changesets are named as follows:
A changeset that gets
runOnChange:trueis named after the object it creates, as the object type and its name, for exampleview.dbo.v1orpackage_body.hr.payroll. The ID is lowercase and includes a schema only when the SQL names one.A second definition of the same object gets
~2, a third gets~3, and so on.Every other changeset is numbered 1, 2, 3 in file order, skipping the named ones.
All changesets use the author
raw-sqlunless you set--author.If Liquibase cannot read an object's name, it numbers that changeset instead, does not set
runOnChange, and logs a warning.
Transaction control statements
Liquibase runs each changeset in its own transaction, so transaction control in the input file cannot carry over into the changelog. How Liquibase handles it depends on the statement:
COMMITandBEGIN TRANoutside a block โ Liquibase removes them, because the deployed result is the same without them.SAVEPOINT,SAVE TRANSACTION, andROLLBACKoutside a block โ The command fails, because the changelog would deploy different data than the original script. To remove them anyway, pass--allow-txn-control-loss=true. Liquibase then lists the removed statements in a warning.SET TRANSACTIONโ On SQL Server, Liquibase keeps it as its own changeset, which runs on every deploy so that the changesets after it keep the isolation level. If the changelog runs through a native executor such assqlcmd, the command fails, because each changeset runs on its own connection and the level would reach none of them. Pass--allow-txn-control-loss=trueto remove the statement instead. On Oracle, the command fails unless you pass--allow-txn-control-loss=true.COMMITor a bareROLLBACKinside an Oracle PL/SQL block โ The command fails. Oracle honors an in-blockCOMMITbefore Liquibase can stop a failed changeset, so a rerun applies the committed changes twice, and an in-blockROLLBACKleaves the deployment unable to resume. Remove these statements before you decorate the file. If the block needs its own transaction control, for example withPRAGMA AUTONOMOUS_TRANSACTION, pass--allow-in-block-txn-control=trueto skip the check for that file.
A comment before a statement does not hide its type. For example, /* undo point */ SAVEPOINT a; fails like any other SAVEPOINT, and /* done */ COMMIT; is removed like any other COMMIT. If the input file holds nothing but transaction control, such as BEGIN TRAN; followed by COMMIT;, the command fails and names the statements it would have removed.
These checks do not run when you pass --rollback-file. See Decorate paired Up and Down migration scripts.
Input file encoding
Liquibase reads a byte order mark (BOM) to decode the input file, so UTF-8, UTF-16 LE, UTF-16 BE, and UTF-32 files with a BOM all work, and the BOM does not reach the changelog. A file without a BOM is read as UTF-8, or as the encoding you set with the global --file-encoding parameter. The same rules apply to both files when you pass --rollback-file.
A BOM at the start of a line or between two statements, as when two files that each start with a BOM are joined, is also dropped, so it does not hide a --rollbackSQL marker or a GO line. A BOM inside a quoted string is kept, because there it is part of the data.
If the file does not decode cleanly, the command fails rather than writing garbled SQL. For a Windows-1252 file, pass --file-encoding=windows-1252. For a UTF-16 file without a BOM, pass --file-encoding=UTF-16LE or --file-encoding=UTF-16BE.
Limitations
Review the generated changelog before you deploy it. The command has these limitations:
Changeset numbers shift when you insert tables or DML โ Changesets that are not named after an object are numbered in file order. If you insert or move a table or DML statement mid-file and run
decorate-sqlagain, every numbered changeset after it gets a new ID, andupdatestops at the checksum check before anything runs twice. Changesets named after an object keep their IDs. Put new changes in a new SQL file, and do not runclear-checksumsto get past the checksum error.No logical file path โ The changelog does not set
logicalFilePath, so Liquibase identifies its changesets by the path you deploy it from. Keep the changelog at a stable path.Consecutive DML runs as one changeset โ If one statement in a DML batch fails, Liquibase cannot resume from that statement.
GO <count>is refused โ On SQL Server, a batch that ends withGOand a count other than 1, as inGO 5, makes the command fail, because a changeset runs only once. Repeat the statements in the file, or use a loop in the SQL.GO 1is accepted.SQL written for the other dialect is refused โ Decorating as
mssql, the command looks for a line holding only/and forCREATE OR REPLACE. Decorating asoracle, it looks for a line holding onlyGO, and forCREATE OR ALTERor aDECLARE @variable. If it finds one in--sql-fileor--rollback-file, it fails and names each construct, its line numbers, and where the dialect came from. To decorate the file anyway, pass--allow-dialect-mismatch=true, which prints a warning instead. A T-SQL/alone on a line used for division, or an Oracle identifier namedGOalone on a line, can trigger the check.