preConditions onFail=MARK_RAN versus runAlways for Liquibase retry safety: which prevents duplicate writes?

The Direct Answer

Neither preConditions nor runAlways inherently prevent duplicate writes; they only control whether Liquibase attempts to execute the changeSet. To prevent duplicate writes during a retry, you must design the changeSet to be inherently idempotent. Between the two options, preConditions with onFail=MARK_RAN is safer for preventing duplicates than runAlways, but it introduces the risk of leaving the database in an inconsistent, partially applied state.

Comparison of Behaviors

The following table outlines how these mechanisms handle retries for non-idempotent SQL (e.g., a standard INSERT):

Mechanism	Retry Behavior	Duplicate Risk	Consistency Risk
runAlways="true"	Executes every time the changelog runs.	High (Guaranteed duplicates)	Low (Always attempts execution)
onFail="MARK_RAN"	Skips execution if precondition fails; marks as ran.	Low (Skips if condition met)	High (Hides partial failures)

The Risk of MARK_RAN

Using onFail="MARK_RAN" is acceptable only when the precondition can definitively prove that the entire intended effect of the changeSet has been achieved. If a transient failure occurs during the SQL execution (after the precondition passed), Liquibase may mark the set as ran upon retry, effectively hiding a partial failure and leaving your data in an inconsistent state.

Recommended Implementation Strategy

To achieve retry safety without sacrificing correctness, combine a state-check precondition with idempotent SQL logic. This ensures that if the precondition fails, the set is skipped, and if the SQL executes, it does not create duplicates.

1. Design for Idempotency: Use SQL syntax that handles existing data, such as INSERT ... ON CONFLICT DO NOTHING (PostgreSQL) or INSERT IGNORE (MySQL), or wrap logic in a WHERE NOT EXISTS clause.
2. Layer with preConditions: Use a precondition to check for the existence of the data. Set onFail="MARK_RAN" only if the precondition is a comprehensive check of the final desired state.
3. Avoid runAlways for Writes: Reserve runAlways for read-only diagnostic scripts or strictly idempotent cleanup tasks.

Verification Command

To verify your idempotency logic, manually insert a record that the changeSet is intended to create, then run the Liquibase update. If the DATABASECHANGELOG marks the set as executed but no duplicate record appears in your data table, the implementation is safe.

Diagnostic Detail Needed: Does your target database support transactional DDL? If it does not (e.g., MySQL), the risk of partial application with MARK_RAN is significantly higher because the DATABASECHANGELOG update and the data change cannot be atomic.