goose v3.30.1: Postgres Locker Fix and Richer ENVSUB Expansions


goose, the SQL first migration tool from Pressly, shipped two releases in four days: v3.30.0 and v3.30.1. Only four commits landed in the window, but two of them matter to anyone running migrations against shared Postgres clusters from long lived processes: a lock wait fix and a much richer set of shell expansions for +goose ENVSUB ON. The patch release also clears a build failure that hit users who ran go get -u.

The most operator relevant change is the locker fix from November 11. The bug: a long lived locker could stop waiting for a held lock and fail immediately. Concretely, if you embed goose in a daemon or a worker pool that holds the migration lock across requests, the locker could bail out of the wait on a race instead of blocking until the lock was released.

Programs that migrate once at startup were not affected, which is why most users never saw it. Embedding goose as a library inside a long running service is the pattern that exposed this, and that pattern is more common than the docs suggest: sidecar migrators, job runners that recheck schema state, and anything that calls the lock API more than once per process.

The change touched the core of the table based locking implementation: lock/internal/table/locker.go, lock/internal/table/config.go, lock/postgres.go, and the new options file lock/session_locker_options.go. A regression test went into internal/testing/integration/locking/postgres_locking_test.go, so the edge case is now covered by an integration test rather than hope. If you run shared Postgres with goose based locking, upgrading to v3.30.1 is the fix you want.

The same day, commit 580061a built on the interpolate package from Michael Fridman, now at v0.2.0. Before this change, +goose ENVSUB ON handled simple variable substitution and not much else. After it, the SQL parser understands a broader set of POSIX style expansions:

  • ${VAR:?message}: fail with a message if the variable is unset
  • ${VAR:+word}: substitute word only when the variable is set
  • other shell style operators in the same family

That matters because migration SQL is often templated by hand, and ${VAR:?message} is the pattern that turns a silent empty string substitution into a hard failure with a readable error. If a required schema name is missing, you want the migration to abort, not to create a table named "". The change landed in internal/sqlparser/parser.go with tests in parser_test.go, so the parser now recognizes the full syntax rather than tokenizing variables naively.

One tradeoff to flag: expansions now behave like shell, which means ${VAR:-default} and friends change behavior for anyone who embedded literal ${...} strings in their SQL expecting no substitution. Check your migration files before upgrading if you use dollar brace sequences in identifiers.

The final commit in the window is the v3.30.1 release itself. Patch bump, README image tag update, and one important fix: a build failure when github.com/mfridman/interpolate is upgraded to v0.2.0, for example via go get -u. Since the 580061a feature commit depends on interpolate v0.2.0, anyone adding goose as a library and running go get -u would hit mismatched package APIs until the goose side caught up. v3.30.1 pins everything consistently in go.mod and go.sum.

For container users, the README now points at ghcr.io/pressly/goose:v3.30.1:

COPY --from=ghcr.io/pressly/goose:v3.30.1 /usr/local/bin/goose /usr/local/bin/goose

The CHANGELOG records the full detail, including the note in the v3.30.0 entry about context aware functions and a returned error when the migrations directory is empty or missing.

  • Session lock stability: the fix added a dedicated integration test suite under internal/testing/integration/locking/. If more edge cases surface, expect them to land there first.
  • ENVSUB behavior: the new expansions change failure modes for unset variables, from silent empty substitution to hard errors. Audit migration files that embed ${...} literally.
  • Library consumers: if you vendor goose and upgrade interpolate independently, do both sides in the same move; the v3.30.1 changelog entry documents exactly that break.

The repository is pressly/goose on GitHub.