diff-column-order
The diff-column-order
global parameter is a Boolean that determines whether the diff command and diff-changelog command compare the column order of a table between two databases. The default value is false
.
Relational databases
Relational databases organize data as relations (tables) that contain rows and columns. This data is ordered in the computer’s physical memory, but you’re meant to access it by name (column name
, column id
…), not ordinal position (column 1
, column 2
…).
It’s possible to add or select columns by ordinal position if you use the statement SELECT * FROM my_table
and run getValue(1)
on the result set rather than getValue(name)
. However, this is generally considered bad practice.
This means the diff-column-order
parameter usually isn’t relevant when you compare two databases.
Uses
The diff
command compares two databases and reports any differences to STDOUT
. The diff-changelog
command compares two databases and generates a changelog containing changesets that you can deploy to resolve any differences.
If you’re comparing two databases with diff
or diff-changelog
, it’s best practice to leave diff-column-order
at the default value of false
. If you set it to true
and run diff-changelog
, Liquibase cannot create changesets to resolve differences in column order.
However, if you use external comparison or reporting tools which cannot easily handle differences in column order data, you can set diff-column-order
to true
. This way, Liquibase handles order differences before passing any data to these external tools.
Setting the diff-column-order
parameter
You can set diff-column-order
in four ways:
- In the Liquibase properties file
- As a global parameter in the CLI
- As a JVM system property
- As an environment variable (Liquibase Pro)
Liquibase properties file parameter
In Liquibase 4.1+, add the following to Liquibase properties file:
liquibase.diffColumnOrder
: <true|false>
CLI global parameter
Tip: All commands and parameters use the --kebab-case
format in the CLI environment. This is the format Liquibase recommends for best results. If your preference is camelCase, it will still work in the CLI.
In your command line, use a global parameter with a single Liquibase command:
liquibase --diff-column-order
=<true|false>
diff
--changelog-file=dbchangelog.xml
Java system property
In your command line, use the JAVA_OPTS Environment Variable to set a JVM system property:
Mac/Linux syntax:
JAVA_OPTS=-Dliquibase.diffColumnOrder
=<true|false>
Windows syntax:
set JAVA_OPTS=-Dliquibase.diffColumnOrder
=<true|false>
Note: To use a Liquibase command alongside JAVA_OPTS
, add && liquibase <command>
to the end of your input.
Environment variable (Liquibase Pro)
In Liquibase Pro, set an environment variable:
Mac/Linux syntax:
LIQUIBASE_DIFF_COLUMN_ORDER
=<true|false>
Windows syntax:
set LIQUIBASE_DIFF_COLUMN_ORDER
=<true|false>
Note: These environment variable commands only apply to the current shell. If you need to pass an environment variable to a child process without affecting the parent process, you can use the export
command on Mac/Linux or the setx
command on Windows.
Output
If you set diff-column-order
to true
and run the diff
command on two databases containing tables with opposite column orders, the output includes:
Changed Column(s):
PUBLIC.TEST_TABLE.TEST_NAME
order changed from '2' to '1'
PUBLIC.TEST_TABLE.TEST_ID
order changed from '1' to '2'