Schema History Table
DBLift keeps its own state in the database it manages: one table for applied-migration history, one for captured schema snapshots. Both are renameable, both created on first use.
Where it lives
The default name is dblift_schema_history, created in the configured schema on first run. Override it per command with --table:
dblift info --table app_schema_history
Every command that touches history accepts the flag — migrate, info, validate, undo, clean, baseline, repair and import-flyway. Point them all at the same table, or you will be reading two different histories.
Root-level keys
These sit at the top level of dblift.yaml, not inside a section, and can each be set from the environment (DBLIFT_HISTORY_TABLE, DBLIFT_SNAPSHOT_TABLE, DBLIFT_MAX_SNAPSHOTS).
| Key | Default | What it holds |
|---|---|---|
history_table | dblift_schema_history | One row per applied migration: version, description, type, checksum, who applied it, when, how long it took, and whether it succeeded. |
snapshot_table | dblift_schema_snapshots | Captured schema snapshots, each with its checksum and the model it recorded. |
max_snapshots | — | How many snapshots to retain. When a capture pushes the count past this, the oldest is deleted. |
Renaming is a migration in itself
Changing history_table against a database that already has history does not move the rows. DBLift will find no history under the new name and treat every applied migration as pending. Rename the table in the database in the same change.
What each row records
| Column | Meaning |
|---|---|
installed_rank | Apply order. Not the version — it is the sequence in which rows were written, which is how out-of-order applies are detected. |
version | The version parsed from the filename. Empty for repeatable migrations. |
description | The text after the double underscore, with underscores turned back into spaces. |
type | Versioned, repeatable or undo. |
script | The filename as applied. |
checksum | Hash of the file's contents at apply time. This is what makes editing an applied migration detectable. |
installed_by | Defaults to the database username. Override with --installed-by to record a pipeline or release id instead. |
installed_on | Timestamp of the apply. |
execution_time | Duration in milliseconds. |
success | Whether the migration completed. A failed row is what repair cleans up. |
Commands that write to it
| Command | Effect on history |
|---|---|
migrate | Appends one row per applied migration. |
baseline | Writes a starting point so existing objects are not re-created on an adopted database. |
repair | Removes failed rows and realigns checksums after a deliberate file change. |
import-flyway | Reads an existing flyway_schema_history and carries it over. |
Do not edit it by hand
Editing rows directly desynchronises checksums from your files, and the next validate will disagree with reality in a way that is hard to unpick. Use repair instead.