feat(cli)!: make pg-delta the default diff engine everywhere

[avallete]

Summary

Second half of the pg-delta work, tracked as CLI-1588. It follows #6487 (the bundled pg-delta engine became the only pg-delta implementation, CLI-2211), which is now merged; this PR is only the default flip on top of it.

An absent [experimental.pgdelta] section — or a section that omits enabled — now resolves to pg-delta for db diff, db pull, and db remote commit, in the TypeScript CLI, @supabase/config (and the published JSON schema), and the residual Go binary (the config template supabase init scaffolds, plus the delegated db remote changes / db diff --use-pg-schema paths that still read the setting).

The Go zero-value tri-state called out in CLI-1588 needed no *bool: the ejected config template now defaults enabled = true, and since mergeDefaultValues feeds that template to viper as the default config, viper's key-level merge resolves both the absent-section and omitted-key cases to true while an explicit enabled = false still wins. PgDeltaInitEnabled / InitParams.UsePgDelta go away with it.

Rollback stays one line: [experimental.pgdelta] enabled = false in config.toml, or per-invocation --use-migra (db diff) / --diff-engine migra (db pull). Migra is unchanged. The explicit config rollback is authoritative: the historical SUPABASE_EXPERIMENTAL_PG_DELTA opt-in env var is no longer consulted (with pg-delta on by default it added nothing, and a stale opt-in would have silently defeated enabled = false); --use-pg-delta remains the per-run opt-in that overrides the rollback.

Knock-on behavior changes to note in release notes:

• the db schema declarative commands' gate (--experimental || pgdelta enabled) is now open by default
• a versionless db reset --experimental only takes the [db.migrations].schema_paths schema-files path when pg-delta is explicitly disabled; otherwise it replays migrations
• SUPABASE_EXPERIMENTAL_PG_DELTA is ignored (see Rollback above)

SIDE_EFFECTS.md files and the db diff/db pull/declarative docs were updated to match. Tests pin the new default (absent config → pg-delta), the explicit-false → migra rollback (including with a stale env opt-in present), and the per-invocation flag overrides; migra-subject tests opt out explicitly.

Linked issue

Linear: CLI-1588

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

BREAKING CHANGES:

pg-delta is now the default schema diff engine. After this PR you must explicitly provide --use-migra (db diff) / --diff-engine migra (db pull), or set [experimental.pgdelta] enabled = false in config.toml, to keep using migra.

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).

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQAoY9JF4uiZRvKVkSd9Wy

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2f97b70424

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@870dde114c8b9250939d57255bff0b3c9c719ae5

Preview package for commit 870dde1.

[avallete]

CI status note — Run end-to-end tests (shard 2/3) failure is not this PR's.

The failing test is packages/stack tests/createStack.e2e.test.ts: its beforeAll times out after 45s inside createStack({...}) (before stack.start()), followed by the afterAll 30s timeout. It failed identically on this PR's last two heads — and also on the unrelated #6371 (workers push, run 33230852020, where all three e2e shards failed with the exact same createStack.e2e.test.ts:24 / :44 hook timeouts).

Why it's not this PR's:

• This diff touches apps/cli, apps/cli-go, and packages/config. packages/stack depends only on @effect/* and @supabase/process-compose — not @supabase/config — and neither stack nor process-compose is touched here.
• The last green e2e run was Aug 28 17:28 UTC (run 4834); every test.yml run since then shows failures across unrelated branches, and nothing touching packages/stack merged to develop in that window (only CI-workflow commits).

No fix PR exists yet that I can port. A fresh run (33239773281) is already in progress on the current head 64831cd and serves as the re-run; I'll keep watching it. All other failures from the previous run are resolved: the 14 Go test failures were fixed in 4234d36, and the "Run unit and integration tests" red on the old head was unit=success, integration=cancelled — cancellation from the superseding push, not a test failure.

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 64831cdca5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[avallete]

CI status note (2/2) — Run end-to-end tests (shard 3/3) failure is also not this PR's.

The failing test is apps/cli src/next/commands/start/start.e2e.test.ts:67 ("keeps an HTTP service dormant until its first proxied request"): supabase start exits 1 with stdout ending at postgres: Initializing.... The unrelated #6371 failed with the identical test and assertion (start.e2e.test.ts:67, expected 1 to be +0) in run 33230852020. src/next/ has no pg-delta code paths, so this diff cannot reach it.

Together with the shard 2/3 createStack hook timeout (see previous note), both point at the same underlying repo-wide breakage: local Docker stack provisioning failing in CI since Aug 28 ~18:00 UTC, on every branch. No fix exists yet to port. Everything within this PR's control is green-bound; these two e2e checks will stay red until the base breakage is fixed.

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f7d2498e48

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e80e88a719

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[avallete]

/ai-review

[github-actions]

🤖 AI Review

Eight deduplicated findings were adjudicated: five confirmed and three refuted. The confirmed issues are two SIDE_EFFECTS documentation gaps, two stale comment/test-layer remnants, and one violation of the trusted TypeScript-authority documentation convention. The db remote commit engine switch itself is intentional and documented, so its finding is narrowed from a major behavioral defect to a minor documentation gap.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli-go/cmd/db.go:168	documentation	claude	The default flip routes delegated db remote commit through the Go edge-runtime pg-delta path, but the command's SIDE_EFFECTS.md does not document the container, pg-delta version/registry inputs, or conditional debug artifacts.
🟡 MINOR	apps/cli/src/legacy/commands/db/pull/pull.handler.ts:520	documentation	claude	db pull --declarative only rewrites [db.migrations].schema_paths when pg-delta is disabled, but SIDE_EFFECTS.md omits this conditional config.toml write; the new true default makes the no-write branch apply to configurations without a pgdelta section.
⚪ NIT	apps/cli/src/legacy/commands/db/schema/declarative/sync/sync.integration.test.ts:118	test-quality	claude	The inert LegacyEdgeRuntimeScript test layer and its comment are stale because the mocked engine and native reset path no longer require that service.
⚪ NIT	apps/cli/src/legacy/commands/db/shared/legacy-shadow-source.ts:6	documentation-conventions	codex	The edited header continues to frame the TypeScript implementation through old Go function names and source locations, contrary to the trusted package convention.
⚪ NIT	apps/cli/src/legacy/shared/db-bootstrap/shadow-database.ts:4	documentation	claude	Comments still reference the deleted legacyPrepareRawShadow symbol and deleted usePgDelta/ctx input fields.

Findings outside the diff

• 🟡 MINOR apps/cli-go/cmd/db.go:168 — The default flip routes delegated db remote commit through the Go edge-runtime pg-delta path, but the command's SIDE_EFFECTS.md does not document the container, pg-delta version/registry inputs, or conditional debug artifacts.
• 🟡 MINOR apps/cli/src/legacy/commands/db/pull/pull.handler.ts:520 — db pull --declarative only rewrites [db.migrations].schema_paths when pg-delta is disabled, but SIDE_EFFECTS.md omits this conditional config.toml write; the new true default makes the no-write branch apply to configurations without a pgdelta section.
• ⚪ NIT apps/cli/src/legacy/shared/db-bootstrap/shadow-database.ts:4 — Comments still reference the deleted legacyPrepareRawShadow symbol and deleted usePgDelta/ctx input fields.

Refuted findings (kept for transparency, not posted as review comments)

• packages/config/src/experimental.ts:78 (config-schema): The optional [experimental.pgdelta] section allegedly lacks a section-level decoding default, causing absent sections to decode differently from the CLI default.
  Refuted: The checked-out code already contains exactly the proposed section-level default at line 100, matching the sibling webhooks pattern. An absent section therefore decodes through {} and receives enabled: true.
• apps/cli/src/legacy/commands/db/reset/SIDE_EFFECTS.md:137 (documentation): The false value of SUPABASE_EXPERIMENTAL_PGDELTA_ENABLED is allegedly undocumented even though it selects the schema-files reset branch.
  Refuted: Although the environment-variable table describes the truthy direction, the document's opening behavior description explicitly documents that false selects the schema-files branch and that true is the default.
• apps/cli/src/legacy/commands/experimental/workers/push/push.integration.test.ts:722 (scope): The root-specific workers-push success branch and skipped unreadable-file test allegedly relax unrelated assertions without justification.
  Refuted: Both changes accurately account for root bypassing POSIX permission bits. Under root the workers directory and file are genuinely readable, so expecting failure would test behavior that did not occur; the changes correct environment-dependent tests rather than relax production behavior.

Stats

Claude findings: 7 · Codex findings: 1 · Confirmed: 5 · Refuted: 3 · 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]

CI note on 46af87e: Run end-to-end tests (shard 1/3) failed in serve-main-offline.e2e.test.ts ("Function at http://127.0.0.1:32769/functions/v1/custom-alias did not become ready"). Kong's logs show the edge-runtime upstream refusing connections for the whole readiness window, so the functions runtime container never came up on the runner. This PR only flips the pg-delta default for db diff / db pull / db remote commit and touches no functions-serve code; the other 14 e2e files in the shard (32 tests) passed. I'll re-run the failed jobs once the run completes; if the runtime still fails to start on the re-run it needs a look at the functions-serve e2e itself rather than this change.

---

Generated by Claude Code

[Coly010]

I merged develop into this branch to resolve the merge conflicts caused by #6525 ("remove the legacy shell concept and naming prefix"), which renamed ~1400 files/identifiers across the repo (stripping the Legacy/legacy prefix) after this PR's branch point.

All conflicts were mechanical rename collisions between this PR's own changes (still using the old legacy-prefixed names) and #6525's renames on develop. I resolved each by keeping this PR's logic/behavior in full and updating identifiers/file paths to the post-#6525 naming convention — no functional changes to this PR's own work.

A few of the larger conflicted test files (diff.integration.test.ts, pull.integration.test.ts, pull.handler.ts, generate.integration.test.ts, sync.integration.test.ts) required manual reconstruction since the rename touched almost every line; I verified the result by diffing against a reconstructed "renamed base" to confirm nothing beyond the naming and this PR's own intended behavior changed. One additional stale reference (legacyDbReset → dbReset in reset.integration.test.ts) that auto-merged without a conflict marker was caught by pnpm check:all and fixed in a follow-up commit, along with an oxfmt pass on the hand-resolved files.

Verified after the merge:

• pnpm check:all passes (types, lint, format, knip, effect-lint) — the only pre-existing failure is an unrelated cli-go gosec finding in files last touched long before either branch.
• Full apps/cli unit + integration suite: 464 test files / 9173 tests passing.

Please double check the resolution, especially around db diff/db pull's pg-delta-default engine-selection logic, since that's the most semantically dense area of the merge.

[avallete]

Double-checked the #6525 merge resolution; it holds up.

Diff equivalence. I compared this PR's diff against its base before the merge (3095e91..46af87e) with the post-merge diff against develop (afc7d47..85c75d4), normalizing the Legacy/legacy prefix out of identifiers and file names on both sides. After normalization the only differences are two test-helper names the normalizer didn't cover (LEGACY_FAKE_SHADOW_CONTAINER_ID → FAKE_SHADOW_CONTAINER_ID, mockLegacyShadowContainerCliSpawner → mockShadowContainerCliSpawner) and oxfmt collapsing a few .pipe(Effect.exit) / .pipe(Effect.flip) calls onto one line now that dbPull is shorter than legacyDbPull. No added, dropped, or altered logic, including in the hand-reconstructed diff / pull / generate / sync test files.

Engine selection specifically. All of the flip's pieces are present and unchanged in meaning on the merged head:

• command-internal/diff-engine.ts: shouldUsePgDelta is configEnabled || usePgDeltaFlag (no env input), and the --use-migra comment describes it as off unless passed.
• command-internal/db-config.toml-read.ts: enabled defaults to true when absent, envLookup is gone from the resolved values.
• db diff / db pull handlers: no parseBoolEnv(...SUPABASE_EXPERIMENTAL_PG_DELTA) input; diff.command.ts deprecation text and pull.handler.ts DEPRECATION_LINE updated.
• packages/config experimental.pgdelta.enabled default/decoding default true; Go IsPgDeltaEnabled is PgDelta == nil || PgDelta.Enabled and the template ejects enabled = true.

Checks on the merged head (f016a81). oxfmt, oxlint, and types:check for apps/cli and packages/config pass; Go build/vet plus the utils, cmd, db/diff, and migration/apply package tests pass. Full apps/cli unit + integration: 462/464 files, 9156 tests passing; the two failures are the root-only environment cases (workers push unlistable root, applySchemaFiles unreadable file) that fail identically on develop when the suite runs as root, which CI does not.

One follow-up I pushed as f016a81: docs/go-cli-divergences.md still described migra as the db diff / migration-style db pull default (wording that landed with #6487's review fixes and that this PR had not updated); it now says pg-delta is the default and lists the migra opt-outs.

---

Generated by Claude Code