retrofit
0.14.0
retrofit.sh

Import a migration tree in order

retrofit import records a tree of migration files as one history, each file’s changes after the ones before it, when you pass the files in the order they were applied. import reads its sources in the order you pass them and never sorts them, so the order is yours to give. This page covers passing that order, checking it before anything is written, and sealing each migration.

retrofit import is the reference for every flag, the list-file rules and each refusal.

Check the order the shell passes

A bare glob over files numbered without padding passes them out of order: V1, V10, V11, V2, V20 puts the tenth migration before the second. V<N>__<desc>.sql is the shape Flyway and Liquibase trees use. Print the order a glob passes before you import:

echo V*.sql

Then preview the import. --dry-run runs the whole import and writes no ops:

retrofit import --schema mig --dry-run V*.sql

A tree passed out of order stops at the first statement whose target a later file creates, or imports and shows up later as an unexpected snapshot. Against a schema not registered yet, the preview registers nothing (Dry run).

Import files you number yourself

Give the files a zero-padded numeric prefix, and a bare glob passes them in order:

01_tables.sql  02_constraints.sql  10_indexes.sql  20_views.sql

retrofit import --schema mig *.sql

Import a tree you cannot rename

Sort the names before you pass them:

retrofit import --schema mig $(ls V*.sql | sort -V)

The shell splits $(…) on whitespace, so a name with a space in it arrives as two paths. For such names, pass the sorted list as a stream:

retrofit import --schema mig --from-file <(ls V*.sql | sort -V)

Pass the files as arguments, not one concatenated stream: an error then names the file it is in, where a stream through stdin can only be named -. The FAQ has a command to check each case.

List the order in a file

For an order no sort produces (dotted versions such as V2.1, a hand-picked subset, files from more than one directory), keep the order in a text file beside the migrations, one path per line:

# migrations/order.txt: the order the files apply in
V1__init.sql
V2__seed.sql
# V2.1 applies after V2
V2.1__hotfix_seed.sql
V3__indexes.sql

Then pass the file:

retrofit import --schema mig --from-file migrations/order.txt

Paths in the list are read relative to the list’s own directory, so the command works from any directory, and a line that starts with # is a comment. List files has every rule.

Seal each migration

A Seal marks a point in the oplog as shipped, so later work has a stable point to build on (Sealed and unsealed ops). For a history that already shipped, seal each file as its own point with --seal-per-file:

retrofit import --schema mig --from-file migrations/order.txt --seal-per-file

Each Seal’s reason is that file’s name, so retrofit identify can name the migration a database is at. A tree whose every migration has the same file name (up.sql in a directory per version) gets the shortest trailing path that tells the files apart. --seal instead seals the whole tree as one point. Seals has the reason rules and what can stop a seal.

When the tree assumes objects it does not create

import checks each statement against the state the oplog and the earlier files built, which is nothing on a first import. A tree that alters objects created outside it stops at the first such statement, one per run, so a tree with several of them takes several runs to find them all. Fix or remove each statement and run again.

For such a tree, apply it to a PostgreSQL database and import a pg_dump --schema-only of the result, or record that dump against an existing oplog with drift. What import recognizes lists the statements import reads.

  • Import existing SQL: import a schema file, preview, seal and start over.
  • retrofit import: every flag, rule and refusal.
  • FAQ: short questions about the order import reads a tree in.
  • drift: record a schema changed outside the oplog.

Before 1.0, any release may change behavior; the release notes list what changed.

Published .