Where migration files are found and how they are read. Which of the discovered files a given run applies is decided by the command's flags, not here.
Directories
A directory entry is either a plain path or a path with its own recursive setting. Mixing both forms in one list is fine.
migrations:
directories:
- "./migrations"
- path: "./vendor/sql"
recursive: false
script_encoding: "utf-8"
detect_encoding: falseSetting directories makes the older single directory key inert — it is not appended to the list. With neither set, DBLift reads ./migrations. For a tree with one folder per module, see Multi-module projects.
Keys
| Key | Default | What it does |
|---|---|---|
directories | [] | Where migration files are found. Each entry is a path, or a path with its own recursive setting. When set, directory is ignored. |
directory | migrations | Single-directory form, kept for older projects. Use directories instead. |
recursive | true | Whether subdirectories are scanned. Applies to any entry that does not set its own. |
table | schema_version | Name recorded for the migration set. The applied-history table is the root history_table key, not this one. |
script_encoding | utf-8 | Encoding used to read migration files. |
detect_encoding | false | Detect each file's encoding before reading it, rather than assuming the setting above. |
Placeholders
SQL files may contain ${NAME} or ${NAME:default}. Values are merged from the root placeholders: map, then --placeholders on the command.
placeholders:
TABLE_NAME: users
LABEL_VALUE: hellodblift migrate --placeholders TABLE_NAME=users LABEL_VALUE=hello --dry-run --show-sql
dblift migrate --placeholders "TABLE_NAME=users,LABEL_VALUE=hello"Unresolved tokens stay in the SQL and a warning is logged. Python migrations are not substituted — they read context.placeholders. See dblift migrate.