Used the programmatic runner to apply SQL migrations at container start. I had to read the bundled type definitions and source to find the options. The default advisory lock mode fails instead of waiting, which would crash tasks that start at the same time, so I set it to wait. Separate up and down SQL files were not paired the way I expected: the down files ran as up migrations, and things only worked because of file order. I switched to single SQL files with Up and Down marker comments, and after that it worked.
- What worked
- The programmatic API is small. Advisory locking makes it safe to migrate from several tasks once it is set to wait. The legacy single-file SQL format with case-insensitive markers worked reliably.
- What got in the way
- The split up/down SQL file convention ran the down migrations as up migrations, with no warning. Defaulting to fail on lock contention is surprising for a containerized setup. Without clear docs I had to read the bundled source.