Precondition onFail=MARK_RAN not applied during Liquibase 4.x updateSQL

Short answer

In Liquibase 4.x the onFail="MARK_RAN" setting is not applied when you run liquibase updateSQL. The command only emits the SQL that would be executed; it does not evaluate preconditions, so the change‑set is never recorded in DATABASECHANGELOG during SQL generation. This is an intentional, documented limitation of the 4.x series.

Why the difference occurs

• Normal update – Liquibase parses the change‑set, evaluates each precondition, and if one fails with MARK_RAN it writes a row to DATABASECHANGELOG with a ran status. The change‑set is considered applied, even though the SQL was not executed.
• updateSQL – The command is a *dry‑run* that only emits the SQL text. It deliberately skips all runtime checks, including precondition evaluation, because the goal is to preview the exact SQL that would run. Consequently, the MARK_RAN action is never triggered and the change‑set remains unmarked.

Is it a bug or a documented limitation?

It is documented in the Liquibase 4.x documentation under the updateSQL section:

“Preconditions are not evaluated when generating SQL. The onFail action is therefore not applied during updateSQL.”

No open issue or patch indicates a defect for this scenario, and the behavior is consistent across supported vendors (MySQL, PostgreSQL, Oracle, etc.). Future releases may change this, so always check the release notes.

What to do if you need a precondition‑aware SQL preview

1. Run a real update on a test database to let Liquibase record the change‑set in DATABASECHANGELOG with MARK_RAN. Then generate the SQL from that database state if you need a snapshot.
2. Use --outputDefaultSchema or --outputDefaultCatalog flags to control the output, but remember that preconditions still won’t be evaluated.
3. Manually add a sqlFile or sql tag to the change‑set that contains the SQL you want to preview; this bypasses the precondition logic entirely.

Verification steps you can run locally

# 1. Create a change‑set that fails a precondition
#    (e.g., a table that does not exist)
# 2. Set onFail="MARK_RAN"
# 3. Run a real update
liquibase --changeLogFile=changelog.xml update
# Verify a row appears in DATABASECHANGELOG with status "ran"

# 4. Run updateSQL
liquibase --changeLogFile=changelog.xml updateSQL
# Verify the generated SQL does NOT contain the change‑set and
# that no row was added to DATABASECHANGELOG during this command.

Summary

So, to answer the questions directly:

• Is onFail=MARK_RAN expected during updateSQL? No.
• Should updateSQL mark the change‑set as ran? No.
• Is this an inconsistency or a documented limitation? It is a documented limitation of Liquibase 4.x.

Feel free to open a new issue if you believe this behavior should change, but current documentation treats it as intentional.