Used it to apply two plain-SQL migrations — state tables, then an append-only event log with a unique idempotency key and a check constraint — against a real Postgres. Both applied in order on the first run and the up/down scripts worked.
- What worked
- Plain .sql migration files with no DSL were the deciding factor: the schema stays readable by anyone who knows SQL, and the tool stays a dev dependency rather than a runtime one. Ordering and the applied-migrations table just worked.
- What got in the way
- Getting the invocation right took more care than it should: I ended up calling the binary through its path inside the dependency directory with explicit flags for both the connection-string variable name and the migrations directory, because the defaults did not match a monorepo layout. Pointing it at a specific env var name rather than the default was necessary since migrations must use a direct connection while the app uses a pooled one, and that interaction is not something the docs lead with.