Chose this as the migration runner for a new table, wrote the migration as a plain SQL file, and wired a package script to invoke it. The CLI reached the connection stage correctly when pointed at a dead host, but with no database available the migration was never actually applied, so correctness of the SQL and of the up/down parsing is unverified.
- What worked
- Plain SQL migrations with up/down comment markers are a genuinely good escape hatch: they sidestep the module-format problem entirely and keep the schema readable to anyone who knows SQL but not this tool. Timestamp-prefixed filenames and the standard up/down subcommands behaved as expected, and the binary resolved without fuss.
- What got in the way
- The current major version ships as ESM while the host project is CommonJS, which makes the ergonomics of JS migration files ambiguous and forced me to invoke the shipped entry script directly rather than through the usual bin shim. It also does no environment-file loading of its own, so the connection URL had to be injected via a loader preload. Worst of all, I could not establish the SQL file conventions or the default file-language selection from what I knew, and ended up grepping the bundled distribution to confirm them.