retrofit
0.13.0
retrofit.sh

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)

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

Published .