A migration's filename is its metadata. DBLift reads the type, the version, the description and the tags straight out of the name, so a file that does not match the convention is not a migration — it is excluded, with a warning naming it.
Four shapes
| Pattern | Type | Runs |
|---|---|---|
V{version}__{description}.{ext} | Versioned | Once, in version order, and is recorded in the history table. Example: V2.4__add_orders_index.sql |
U{version}__{description}.{ext} | Undo | Reverses the versioned migration with the same version. Never runs on its own. Example: U2.4__add_orders_index.sql |
R__{description}.{ext} | Repeatable | No version. Re-runs whenever its checksum changes, after the versioned migrations. Example: R__refresh_reporting_views.sql |
{event}__{description}.{ext} | Callback | Runs at a named point in the lifecycle rather than as a migration of its own. Example: beforeMigrate__set_lock_timeout.sql |
The double underscore is mandatory in every shape. It is what separates the prefix from the description, and a file that omits it is not classified at all.
Versions
- Numeric versions may be separated by dots or underscores.
V1_2_3__andV1.2.3__are the same version — underscores are normalised to dots before comparison. - Letter-based versions are allowed and kept verbatim:
Va__,VB2__. They sort as strings, so mixing them with numeric versions in one directory is a way to surprise yourself. - An undo script matches its migration by version, not by filename.
U2.1__anything.sqlreversesV2.1__anything_else.sql.
Repeatables carry no version
They run whenever their checksum changes, after the versioned migrations.
Tags
A bracketed, comma-separated group anywhere in the name is read as tags and stripped before classification.
V3.1__add_orders_index[prod,slow].sql → version 3.1, tags: prod, slow
afterMigrate__notify[prod].sql → callback on afterMigrate, tag: prodTags are stripped by the same code that classifies the file, so the two can no longer disagree.
Use --tags, --exclude-tags, --versions and --exclude-versions to scope migrate, undo, validate and diff to subsets of your script tree. In a multi-directory tree, tags are how you apply one module and skip another — see Multi-module projects.
Callback events
A callback is named {event}__{description}.{ext}, in camelCase, matched case-insensitively. It is not recorded in the schema history table. Put session setup and teardown here, not schema changes.
-- migrations/beforeMigrate__set_pragma.sql
PRAGMA foreign_keys = ON;-- migrations/afterEachMigrate__analyze.sql
ANALYZE;dblift migrate --dry-run --show-sqlbeforeMigrate runs once before any pending script. afterEachMigrate runs after every versioned file that actually executed. afterMigrateError runs if the command fails.
Nineteen events are recognised:
beforeMigrate · afterMigrate · afterMigrateError · beforeEach · afterEach · beforeEachMigrate · afterEachMigrate · beforeValidate · afterValidate · beforeClean · afterClean · afterCleanError · beforeUndo · afterUndo · afterUndoError · beforeVersioned · afterVersioned · beforeRepeatable · afterRepeatable
The separator is what makes it a callback
Five events are prefixes of longer ones, so without
__the boundary is ambiguous.afterMigrate.sqlandafterMigrate_notify.sqlare not callbacks. Both are reported by name rather than ignored, because a file like that sits in the migrations directory looking like it works.
Python event listeners (client.events.on(...)) are a separate mechanism. See Events & callbacks.
What gets excluded
Anything that matches none of the four shapes is classified as unknown and left out of the run. The count and the filenames are logged, so a mistyped name shows up as a warning rather than as a migration that quietly never ran.
Found 2 script(s) not following Dblift naming convention.
These will be excluded from migration: ['v1_add_users.sql', 'rollback.sql']