feat(cli): make the bundled pg-delta engine the only pg-delta implementation

[avallete]

Summary

First half of the pg-delta cleanup, tracked as CLI-2211. The second half (flipping the default engine to pg-delta, CLI-1588) is stacked on top of this PR in #6391.

The SUPABASE_USE_PG_DELTA_NEXT escape hatch shipped in v2.115.0 as a temporary opt-out back to the legacy edge-runtime pg-delta engine; its release notes announced removal after ~a month. Setting it now has no effect: the in-process @supabase/pg-delta engine is the only pg-delta implementation.

Deleted with the legacy engine:

• the flag module and the engine selector layer; LegacyPgDeltaEngine loses its implementation discriminator and every handler branch keyed on it
• the edge-runtime pg-delta Deno script templates, the supabase/.temp/pgdelta-version npm pin, and the PGDELTA_NPM_REGISTRY / PGDELTA_{SOURCE,TARGET}_SSLROOTCERT plumbing (all legacy-engine-only; the edge-runtime service itself stays — migra still runs through it)
• the migrations-catalog cache warmups after db push / db reset / start / db start / bootstrap (TypeScript and Go), and the whole catalog snapshot machinery (legacy-pgdelta.cache.ts); the shared migration lister moves to command-internal/legacy-migration-list.ts
• the legacy declarative catalog seam (LegacyDeclarativeSeam.exportCatalog), the declarative-apply engine (legacy-pgdelta.apply.ts), and db pull's legacy empty-diff debug bundle
• the "--strict-coverage has no effect with the legacy pg-delta engine" warning — the flag is now always effective
• leftover writer/debug/edge-runtime surface that only the deleted engine used (manifest-less wipe-and-rewrite, orphan debug-bundle fields, extraFiles / extraEnv)

db pull --experimental and db remote commit now run in-process as well (commit is a thin db pull wrapper with a fixed remote_commit name and the cobra deprecation line). The deprecated --experimental export writes the same declarative tree as --declarative.

Go is slimmed to match: db pull, db dump, db remote commit, and the Go pg-delta / dump engines are gone. supabase-go db diff only serves the TypeScript --use-pg-schema proxy. db remote changes still uses Go migra.

Also bumps @supabase/pg-delta to 1.0.0-alpha.49 (same @supabase/pg-topo 1.0.0-alpha.6 peer; the release is younger than the workspace's minimum release age, so it is on the exclusion list).

Engine selection is unchanged in this PR: migra stays the default for db diff / migration-style db pull, and pg-delta is still opted into through [experimental.pgdelta] enabled = true, SUPABASE_EXPERIMENTAL_PG_DELTA, --use-pg-delta, or --diff-engine pg-delta. An absent [experimental.pgdelta] section still resolves enabled = false, so declarative export still writes [db.migrations].schema_paths in that default case. SIDE_EFFECTS.md files, the db pull docs, and the Go CONTRIBUTING pg-delta section were updated to match.

Linked issue

Linear: CLI-2211

• The linked issue is open and carries the open-for-contribution label (or I'm a Supabase maintainer).

Checklist

• The PR title follows Conventional Commits (e.g. fix(cli): …).
• Tests added or updated for the change.
• From the repository root, pnpm check:all passes; relevant package tests pass for every touched workspace, and pnpm types:check passes for each touched TypeScript workspace (or workspace declaring it).

[github-actions]

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@3e19649d1a459429b1897cef077afb0e58cdedc8

Preview package for commit 3e19649.

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Claude reported five findings and Codex reported none. All five are confirmed: one test-coverage regression, one contradictory engine-default description, stale references to removed pg-delta code, silent removal of a documented environment-variable opt-out, and two unrelated test changes bundled into the cleanup. No correctness or security defect was identified.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/legacy/shared/legacy-migration-list.ts:28	test-coverage	claude	The moved legacyListLocalMigrations implementation lost its dedicated unit coverage when legacy-pgdelta.cache.unit.test.ts was deleted, with no replacement test file added.
🟡 MINOR	apps/cli/docs/go-cli-divergences.md:30	documentation	claude	The --strict-coverage documentation incorrectly describes pg-delta as the default and selecting migra as “rolling back,” although migra remains the default for db diff and migration-style db pull.
⚪ NIT	apps/cli/src/legacy/commands/db/shared/legacy-pgdelta-engine.layer.ts:18	user-experience	claude	SUPABASE_USE_PG_DELTA_NEXT=false is no longer read and silently ceases to select the legacy engine, without a deprecation notice.
⚪ NIT	apps/cli/src/legacy/commands/experimental/workers/push/push.integration.test.ts:1287	scope	claude	The PR includes two root-environment test fixes unrelated to the pg-delta removal, increasing the scope of an already large cleanup.
⚪ NIT	apps/cli/src/legacy/commands/db/shared/legacy-pgdelta.seam.integration.test.ts:85	documentation	claude	Several surviving comments still refer to pg-delta modules and helpers deleted by this PR, including a seam-test comment describing edge-runtime scripts the seam no longer invokes.

Findings outside the diff

• ⚪ NIT apps/cli/src/legacy/commands/db/shared/legacy-pgdelta.seam.integration.test.ts:85 — Several surviving comments still refer to pg-delta modules and helpers deleted by this PR, including a seam-test comment describing edge-runtime scripts the seam no longer invokes.

Stats

Claude findings: 5 · Codex findings: 0 · Confirmed: 5 · Refuted: 0 · Uncertain: 0

---

Models: claude-opus-5 + gpt-5.6-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[avallete]

/ai-review

[github-actions]

🤖 AI Review

Only Claude's independent review was available; the Codex review did not complete. All six Claude findings are confirmed: one minor latent destructive/dead-code concern and five nits involving dead code, unnecessary wiring, stale comments, and migration UX. No critical or major defects were identified.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/db/shared/legacy-pgdelta.write.ts:321	dead-code	claude	The removed legacy engine leaves a manifest-less declarative-output fallback that recursively deletes the declarative directory, despite all surviving production exports carrying a manifest.
⚪ NIT	apps/cli/src/commands/db/shared/legacy-debug-bundle.ts:6	dead-code	claude	Four debug-bundle fields and their artifact-writing branches remain after their sole db pull producer was deleted.
⚪ NIT	apps/cli/src/commands/db/shared/legacy-pgdelta-engine.layer.ts:18	ux	claude	SUPABASE_USE_PG_DELTA_NEXT=false is now silently ignored, so users retaining the former opt-out receive the in-process engine without notice.
⚪ NIT	apps/cli/src/command-internal/legacy-edge-runtime-script.service.ts:33	dead-code	claude	LegacyEdgeRuntimeRunOpts.extraFiles and extraEnv have no remaining producers after removal of the edge-runtime pg-delta registry injection.
⚪ NIT	apps/cli/src/commands/db/shared/legacy-pgdelta-engine.layer.ts:60	maintainability	claude	The shared pg-delta command runtime still installs the edge-runtime and TLS-probe layers for declarative generate and sync even though those commands use only the in-process engine.
⚪ NIT	apps/cli/src/commands/db/diff/diff.integration.test.ts:279	documentation	claude	Several comments still refer to functions or workflows deleted by this PR.

Findings outside the diff

• 🟡 MINOR apps/cli/src/commands/db/shared/legacy-pgdelta.write.ts:321 — The removed legacy engine leaves a manifest-less declarative-output fallback that recursively deletes the declarative directory, despite all surviving production exports carrying a manifest.
• ⚪ NIT apps/cli/src/command-internal/legacy-edge-runtime-script.service.ts:33 — LegacyEdgeRuntimeRunOpts.extraFiles and extraEnv have no remaining producers after removal of the edge-runtime pg-delta registry injection.
• ⚪ NIT apps/cli/src/commands/db/shared/legacy-pgdelta-engine.layer.ts:60 — The shared pg-delta command runtime still installs the edge-runtime and TLS-probe layers for declarative generate and sync even though those commands use only the in-process engine.
• ⚪ NIT apps/cli/src/commands/db/diff/diff.integration.test.ts:279 — Several comments still refer to functions or workflows deleted by this PR.

Stats

Claude findings: 6 · Codex findings: 0 · Confirmed: 6 · Refuted: 0 · Uncertain: 0

---

Models: claude-opus-5 + gpt-5.6-sol · Trigger: manual · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[avallete]

/ai-review

[avallete]

CI note on 3e19649: Run end-to-end tests (shard 3/3) failed in shadow-cache.e2e.test.ts before the test's subject ran. The supabase start that provisions the test's stack could not start the inbucket container because host port 54324 was already taken on the runner (failed to bind host port for 0.0.0.0:54324 ... address already in use), so the test saw exit code 1 instead of 0. Nothing in this PR touches stack startup or inbucket port assignment; the same shard passed on the previous heads of this branch, and the other 13 e2e files in the shard (30 tests) passed. The failed jobs are already re-running (attempt 2). If the port collision recurs on the re-run, I'll look at whether the preceding e2e file in the shard is leaving its stack up rather than treat it as a flake.

---

Generated by Claude Code