Roadmap: node-pg-migrate v9 → v10

[Shinigami92]

Roadmap: node-pg-migrate v9 → v10

Hi everyone 👋

With v9.0.0-alpha.9 out the door, I want to share where node-pg-migrate is heading: how we plan to land v9 stable in the coming weeks, and what is shaping up for v10 beyond it.

The short version: v9 is a bridge release. It keeps the door open for users still on Node versions that don't have first-class package.json exports support, while we modernize the internals so v10 can move fully forward.

---

Where we are today

Latest release: v9.0.0-alpha.9

Highlights of what's already shipped across the v9 alpha line (since v8):

• jiti for TypeScript / mixed-extension migrations — replaces the previous TS loader story and unblocks a number of long-standing setup issues. See PR #1460.
• Migration loader strategies + SQL grouping — pluggable strategies for how migration files are discovered and grouped, including grouped plain-SQL migrations. Thanks @peturv for #1582!
• Index-based filename naming strategy — alternative to timestamp-based names, contributed by @adrenalin in #1443.
• Stricter input validation — addConstraint, alterPolicy, alterSequence, alterTable and the operator-family helpers now throw early instead of silently producing invalid SQL.
• Internal refactors — StringIdGenerator replaced with a generator function, indexMethod typed as string instead of Name in operator helpers.
• Tooling moved to the Ox toolchain — eslint → oxlint, prettier → oxfmt, tsup → tsdown, plus TypeScript v6. Faster local dev and CI, no runtime impact.
• Updated supported DB matrix — see CI for the current PostgreSQL and CockroachDB versions we test against.

---

v9 stable — the next ~1–2 months

The plan is to wrap up v9 with mostly cleanups rather than new features:

• Walk through the remaining TODOs and rough edges in the codebase.
• Finish a small batch of issues we already want in before stable:
  • #1615 — Allow configuring jiti (e.g. tsconfig paths).
  • #1628 — dropConstraint: add ifTableExists for idempotent retries.
  • #1627 — Documentation fix for JSON config options.
• #1497 — Switch the publishing pipeline to npm trusted publishing.
• Then one or more release candidates, followed by v9.0.0.

Why v9 is a bridge release: v9 is intentionally the last line that still aims to support Node versions and setups without solid package.json exports resolution. It is ESM-only (continuing from v8), but everything beyond that is still kept friendly to slightly older toolchains. v10 will drop that compatibility baggage — see below.

On co-maintainers: I'm currently working with @brenoepics and @osdiab to bring them on as co-maintainers — see discussion #1629 and PR #1634. The goal is to spread review, release and triage load so this project stays healthy long-term. 🙏

---

v10 — early vision

v10 is the modernization release. Nothing here is locked in yet — that's exactly what this discussion is for — but the direction I want to telegraph:

• Drop Node v20 support. Align the minimum Node version with what actively-maintained Node releases offer, so we can rely on modern platform features without polyfills or branches. This is already a concrete blocker today — several dependency updates are currently parked because they require Node v22+, e.g. pnpm v11 (#1626), devdependencies (#1622) and dotenv-expand v13 (#1620).
• Explore removing the dotenv dependency. We want to evaluate whether we can drop dotenv (and dotenv-expand) in favor of Node's built-in --env-file flag and process.loadEnvFile(). The goal is one fewer runtime dependency and a simpler env story — but we still need to check feature parity (variable expansion, precedence rules, multi-file loading) before committing.
• Stay ESM-only, but rely on require(esm). Node's new require(esm) support means CJS consumers can keep working without us shipping a CJS build. ESM stays the single source of truth.
• CLI rewrite (or at least restructure). At minimum, the bin/ folder moves into src/ so the CLI is built and type-checked alongside the rest of the library. A full rewrite to Commander is on the table (see #1137) — feedback welcome on whether that's worth the churn.

Other features that may land in or around v10 and are already on the radar — listed in our vFuture milestone:

• #1138 — strict mode that hashes migration step contents to detect unintended changes to already-applied migrations.
• #1120 — A migrate status command (applied / pending overview).
• #1122 — A --pretty option for nicer formatted SQL output.

Smaller, non-breaking improvements that can land in any version live in the vAnytime milestone — including bun setup docs, check-constraint shorthands, RLS PERMISSIVE / RESTRICTIVE, an initial-migration generator from an existing schema, and explicit migration listing instead of directory scanning (#651).

---

We want your feedback

This roadmap is a proposal, not a commitment. If you have opinions on:

• the v10 baseline (Node version, --env-file, require(esm), CLI rewrite scope),
• which vFuture items matter most for your projects,
• bugs or rough edges in v9.0.0-alpha.9 you've hit and want fixed before stable,

please reply in this discussion. The more concrete input we get now, the better v9 stable and v10 will land.

Thanks to everyone using node-pg-migrate, filing issues, and contributing PRs — and a special thanks to @brenoepics and @osdiab for stepping up. ❤️