FAQ
Short questions that come up where a migration tree’s naming meets
import’s input. Each answer shows a command that checks it on your own
tree.
My migrations imported out of order. What happened?
import reads its sources in the order you pass them and never re-sorts
them. A bare glob over files numbered without padding can pass V10
before V2. Print the order the shell passes:
echo V*.sql
If the order is not the order the files applied in, pass them sorted or
through --from-file (see Import a migration tree in order),
and run the import with --dry-run first:
retrofit import --schema mig --dry-run $(ls V*.sql | sort -V)
The shell splits $(…) on whitespace, so for names with a space in
them pass the list as a stream instead (see
Can I pass a sorted list without writing a file?).
An out-of-order tree fails at the first statement whose target a later
file creates (validation-error), or imports cleanly and shows up later
as an unexpected snapshot.
How do I import a tree with dotted versions such as V2.1?
Read the order your sort produces before you import:
ls V*.sql | sort -V
If a dotted version such as V2.1__hotfix.sql is anywhere other than
where it applied, list the order yourself, one file per line, and pass
the list with --from-file
(see List the order in a file):
retrofit import --schema mig --dry-run --from-file migrations/order.txt
--dry-run prints every op the import would append without writing the
oplog, and leaves a schema not registered yet unregistered
(see Dry run).
Does zero-padding the version numbers fix the order?
For whole-number versions, a zero-padded prefix (V01, V02, V10)
lets a bare glob pass the files in order. Padding says nothing about
where a dotted version such as V02.1 falls, so print the order and
read it:
echo V*.sql
If any file is out of place, use --from-file.
Can I pass a sorted list without writing a file?
Yes. --from-file takes a stream, so the output of a sort can go
straight to it. Print the list first to check it:
ls V*.sql | sort -V
retrofit import --schema mig --from-file <(ls V*.sql | sort -V)
Paths in a stream resolve against the working directory, where paths in
a list file resolve against the file’s directory.
--from-file /dev/stdin reads the list from a pipe; --from-file -
names a file called -.
Can I sort with a glob qualifier instead of a sort command?
A shell with a numeric glob qualifier can order the names itself; in
zsh it is (n). Print the order it gives, then import it:
print -l V*.sql(n)
retrofit import --schema mig --dry-run V*.sql(n)
Why does a parse error name - instead of my file?
The sources reached import through stdin, as one stream, so the error
can only name -. Pass the files as arguments instead, and the error
names the file that failed to parse:
retrofit import --schema mig --dry-run $(ls V*.sql | sort -V)