Skip to main content

Retrofitting

Using Liquibase Linter in a brand new project is pretty straightforward, but more often than not you'll be retrofitting it to an existing project with a history of changes. It's likely that many of those changes would not pass the set of rules you are applying, but since changes are supposed to be immutable, fixing them retrospectively is not really an option.

Liquibase Linter provides some extra configuration options to help with this.

enable-after-changelog at project level​

This config option allows you to specify a point in time (a change log file) after which you want lint rules to be run. This would typically be the last change log before you add Liquibase Linter and turn on the rules.

Take this example configuration and change log:

{
  "enable-after-changelog": "src/main/resources/example-1.xml",
  "rules": {}
}
<!-- root change log file -->
<databaseChangeLog
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
  xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.3.xsd"
>
  <include relativeToChangelogFile="true" file="example-1.xml" />
  <include relativeToChangelogFile="true" file="example-2.xml" />
  <include relativeToChangelogFile="true" file="example-3.xml" />
</databaseChangeLog>

Since we've called out example-1.xml as our enable-after-changelog change log, the linter will start checking from example-2.xml.

enable-after-changeset at project level​

When the boundary between "legacy" and "linted" changes does not line up with a change log file, you can point at a single changeset instead. It is referenced by its full Liquibase identity — the change-log-file, id and author triple that uniquely identifies a changeset (the same three attributes as the changeSetExecuted precondition). All three are mandatory; change-log-file is matched against the changeset's logical file path.

{
  "enable-after-changeset": {
    "change-log-file": "src/main/resources/example-2.xml",
    "id": "0002-add-customer-table",
    "author": "jsmith"
  },
  "rules": {}
}

The referenced changeset and every changeset before it are ignored; linting starts at the next changeset.

At rule level​

Over time you'll probably want to add new rules to your project — but again there may be historical changes that would fail if you just drop them in. The same two options are available per rule, with the same names:

{
  "rules": {
    "has-context": {
      "enable-after-changelog": "last-changeset-before-contexts-became-mandatory.xml"
    },
    "has-comment": {
      "enable-after-changeset": {
        "change-log-file": "src/main/resources/example-2.xml",
        "id": "0002-add-customer-table",
        "author": "jsmith"
      }
    }
  }
}

Every option also accepts a camelCase spelling (enableAfterChangelog, enableAfterChangeset, changeLogFile, …) — see Configuration.

Only one boundary at a time​

enable-after-changelog and enable-after-changeset both express the same thing — the single point in history before which nothing is linted — so they are mutually exclusive. Setting both (at project level or within the same rule) fails configuration loading with an explicit error.