feat(cli)!: make pg-delta the default diff engine for all projects

[avallete]

TL;DR

pg-delta becomes the schema diff engine for every project, not only ones created by a recent supabase init. A config.toml with no [experimental.pgdelta] section, or a section that omits enabled, now resolves to pg-delta for db diff, db pull, and db remote commit. Migra stays available through a one-line rollback.

flowchart LR
  subgraph Before
    A1["no [experimental.pgdelta]"] --> M1[migra]
    B1["enabled = true"] --> P1[pg-delta]
    C1["SUPABASE_EXPERIMENTAL_PG_DELTA=1"] --> P1
  end
  subgraph After
    A2["no [experimental.pgdelta]"] --> P2[pg-delta]
    B2["enabled = false"] --> M2[migra]
    C2["--use-migra / --diff-engine migra"] --> M2
  end

Loading

Why

CLI-1587 opted new projects into pg-delta, but existing projects still diffed with migra unless they edited config.toml. This finishes the migration so every project uses the same engine.

What changed

• [experimental.pgdelta].enabled defaults to true when absent, in the CLI's config reader and in @supabase/config (including the published JSON schema). An explicit enabled = false still selects migra.
• The historical SUPABASE_EXPERIMENTAL_PG_DELTA opt-in env var is no longer read. With pg-delta on by default it added nothing, and a stale value would have silently overridden enabled = false. --use-pg-delta remains the per-run override.
• db schema declarative generate / sync no longer need --experimental. They are closed only when enabled = false is set and --experimental is omitted.
• A versionless db reset --experimental (and a fresh-volume start --experimental) applies [db.migrations].schema_paths files only when pg-delta is explicitly disabled. Otherwise it replays migrations and, when schema_paths is set, prints a warning naming the enabled = false rollback (before the remote reset's confirmation prompt).
• db pull --declarative writes [db.migrations].schema_paths into config.toml only when pg-delta is explicitly disabled.
• db diff -f that finds declarative schema files it did not read prints a note pointing to supabase db schema declarative sync (and to --use-migra when migra would read those files), including when the diff is empty. Local diffs without -f only report the JSON advisory.
• The schema_paths warning on db diff / db pull explains that declarative sync reads declarative_schema_path, not schema_paths, and names the enabled = false rollback. The declarative-command gate suggests --experimental rather than undoing enabled = false.
• On the stack backend, --use-migra=false / --use-pgadmin=false are accepted, since they keep pg-delta.
• db diff --use-migra=false keeps the pg-delta default instead of selecting migra.
• Help text, command docs, and SIDE_EFFECTS.md contracts describe pg-delta as the default.

Linked issue

Closes CLI-1588

BREAKING CHANGES:

pg-delta is now the default schema diff engine for all projects. Generated migration SQL from db diff, db pull, and db remote commit changes for projects that had not opted in. Under pg-delta, [db.migrations].schema_paths and declarative files in supabase/schemas are no longer inputs to db diff or migration-style db pull, so the "edit supabase/schemas, then db diff -f" workflow no longer picks up those edits; use supabase db schema declarative sync to generate migrations from declarative schema files.

To keep migra, set this in supabase/config.toml:

[experimental.pgdelta]
enabled = false

or pass --use-migra (db diff) / --diff-engine migra (db pull) per run. SUPABASE_EXPERIMENTAL_PG_DELTA is ignored.

🤖 Generated with Claude Code

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Confirmed two non-blocking nits: outdated deprecation guidance and missing remote-commit coverage for the new default and explicit rollback. The coverage finding is narrower than originally claimed because opt-in integration tests already exist. Codex reported no findings. Static review found no additional issues; tests were not run.

Findings

Severity	Location	Category	Sources	Claim
⚪ NIT	apps/cli/src/commands/db/remote/commit/SIDE_EFFECTS.md:69	test-coverage	claude	Remote-commit integration tests do not directly cover pg-delta selection with omitted configuration or migra selection with enabled = false.
⚪ NIT	apps/cli/src/command-internal/db-pull-run.ts:92	docs	claude	The --use-pg-delta deprecation message still asks users to configure enabled = true even though pg-delta now defaults to enabled.

Findings outside the diff

• ⚪ NIT apps/cli/src/command-internal/db-pull-run.ts:92 — The --use-pg-delta deprecation message still asks users to configure enabled = true even though pg-delta now defaults to enabled.

Stats

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

---

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

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

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews were available. Claude's sole finding is refuted because the deprecation text is an existing, documented output contract; its redundant configuration advice remains valid. Codex reported no findings. No additional correctness issues were identified during static inspection. Tests were not run.

Findings

No issues found.

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

• apps/cli/src/command-internal/db-pull-run.ts:92 (docs-consistency): The db pull --use-pg-delta deprecation message unnecessarily recommends setting enabled = true and contradicts the updated documentation now that pg-delta is enabled by default.
  Refuted: The trusted baseline establishes that this wording was intentionally preserved as an output contract, and the existing comment already documents that constraint. Explicit enabled = true remains valid; becoming redundant does not make it contradict the documented default. The PR did not introduce a purported convention to justify retaining the message.

Stats

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

---

Models: claude-opus-5-5 + gpt-6.1-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]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews completed. Verified Claude's two stale-wording nits against the code; Codex reported no findings. Neither finding identifies a runtime correctness bug.

Findings

Severity	Location	Category	Sources	Claim
⚪ NIT	apps/cli/src/commands/db/schema/declarative/declarative.errors.ts:11	documentation	claude	The DeclarativeNotEnabledError comment still describes pg-delta as requiring an explicit opt-in, although it is now enabled by default.
⚪ NIT	apps/cli/src/command-internal/db-pull-run.ts:91	user-facing-messaging	claude	The --use-pg-delta deprecation warning still recommends explicitly enabling pg-delta in config.toml, which is redundant with the new default.

Findings outside the diff

• ⚪ NIT apps/cli/src/commands/db/schema/declarative/declarative.errors.ts:11 — The DeclarativeNotEnabledError comment still describes pg-delta as requiring an explicit opt-in, although it is now enabled by default.
• ⚪ NIT apps/cli/src/command-internal/db-pull-run.ts:91 — The --use-pg-delta deprecation warning still recommends explicitly enabling pg-delta in config.toml, which is redundant with the new default.

Stats

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

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Confirmed Claude's sole finding: the new pg-delta default silently changes the rebuild source for versionless experimental resets and fresh-volume starts. Codex reported no findings. Verification was static; tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/command-internal/db-config.toml-read.ts:1408	error-handling	claude	Projects with configured schema_paths but no pg-delta setting now silently replay migrations instead of schema files during versionless db reset --experimental and fresh-volume start --experimental. Remote reset drops user schemas before rebuilding, so schema-file-only objects are no longer recreated without any warning about the changed source.

Stats

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

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Confirmed Claude’s documentation nit: one comment still implies declarative commands require opt-in, although pg-delta now defaults to enabled. Codex reported no findings. Code inspection found no additional actionable issue; runtime tests were not run.

Findings

Severity	Location	Category	Sources	Claim
⚪ NIT	apps/cli/src/docs/docs-spec.tables.ts:90	documentation	claude	The DOCS_EXPERIMENTAL_OPTIONAL comment still describes the old opt-in model without explaining that declarative commands are now enabled by default.

Findings outside the diff

• ⚪ NIT apps/cli/src/docs/docs-spec.tables.ts:90 — The DOCS_EXPERIMENTAL_OPTIONAL comment still describes the old opt-in model without explaining that declarative commands are now enabled by default.

Stats

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

---

Models: claude-opus-5-5 + gpt-6.1-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]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews were available. Code verification confirms Claude's documentation nit: the inserted warning makes the following branch reference ambiguous and breaks the list item's formatting. No additional actionable findings were identified.

Findings

Severity	Location	Category	Sources	Claim
⚪ NIT	apps/cli/src/commands/db/reset/SIDE_EFFECTS.md:296	documentation	claude	The inserted warning describes the migrations-replay path immediately before "Taking this branch means timestamped migrations never run at all", making "this branch" ambiguous. The warning's continuation also loses the list indentation and surrounding line wrapping.

Stats

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

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews completed. The sole reported finding is confirmed as a minor correctness issue: --use-migra=false switches normal native-backend diffs from the new pg-delta default to migra. Verification was by code inspection; runtime tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/db/diff/diff.handler.ts:464	correctness	claude	In normal mode on the native Docker backend, db diff --use-migra=false selects migra instead of retaining the default pg-delta engine because engine selection ignores the flag's boolean value.

Stats

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

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews were available. Claude reported one finding; Codex reported none. Code verification confirms a major transition-warning gap: existing declarative projects can silently stop generating migrations from supabase/schemas after pg-delta becomes the default. Tests were not executed.

Findings

Severity	Location	Category	Sources	Claim
🟠 MAJOR	apps/cli/src/commands/db/diff/diff.handler.ts:459	user-experience	claude	Existing projects using supabase/schemas without schema_paths silently lose their declarative db diff workflow when pg-delta becomes the default. Migra used these files as the local diff target; pg-delta ignores them. If only those files change, db diff, including db diff -f, can report "No schema changes found" without explaining that the files were ignored.

Stats

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

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Verified all three input findings and merged the overlapping rollback-guidance findings into one. Confirmed two minor issues: misleading migra fallback guidance and stack rejection of --use-migra=false despite its new pg-delta semantics. The mutex portion of Claude's second finding is refuted as established presence-based behavior. No critical or major findings.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/db/diff/diff.handler.ts:108	user-guidance	claude+codex	The new declarative-files note recommends setting enabled = false to diff the displayed files with migra, but that advice fails for custom declarative directories without matching schema_paths and for stack backends.
🟡 MINOR	apps/cli/src/commands/db/diff/diff.handler.ts:467	correctness	claude	Although --use-migra=false now preserves the pg-delta default, the stack preflight still rejects it solely because the flag was supplied.

Stats

Claude findings: 2 · Codex findings: 1 · Confirmed: 2 · Refuted: 0 · Uncertain: 0

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews were available; Codex reported no findings. Claude’s sole finding is confirmed as a documentation nit: local pg-delta diffs skip the ignored-files note for valid export manifests unless writing a migration.

Findings

Severity	Location	Category	Sources	Claim
⚪ NIT	apps/cli/docs/supabase/db/diff.md:17	documentation	claude	The docs promise an ignored-declarative-files note for local pg-delta diffs, but local diffs that do not write a migration suppress that note when the declarative directory has a valid .pgdelta-export.json manifest.

Stats

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

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Verified both Claude findings against the checked-out code. Confirmed one cosmetic hint inaccuracy and refuted the stack-test coverage concern. Codex reported no findings. No blocking issues were verified; tests were not run.

Findings

Severity	Location	Category	Sources	Claim
⚪ NIT	apps/cli/src/commands/db/diff/diff.handler.ts:737	error-handling	claude	The declarative sync hint unnecessarily includes --experimental when pg-delta is disabled but SUPABASE_EXPERIMENTAL already opens the gate through the shell or project .env.

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

• apps/cli/src/commands/db/diff/diff.integration.test.ts:1923 (test-coverage): The --use-migra=false stack-backend test relies on fixture defect text and absence of typed errors, making it brittle and failing to directly demonstrate that StackNativeEngineError was avoided.
  Refuted: The assertions demonstrate the intended boundary: execution reaches shadow creation, encounters the stack-service sentinel defined in tests/helpers/unused-stack.ts:6-16, and contains no typed error. StackNativeEngineError is a typed failure yielded by stack-local-database.ts:160-175, so the no-typed-error assertion directly excludes it. Rewording the fixture would require updating its expectation, but the current test does verify flag acceptance.

Stats

Claude findings: 2 · Codex findings: 0 · Confirmed: 1 · Refuted: 1 · Uncertain: 0

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews were available. Confirmed Codex's single finding: the pg-delta transition warning misses projects with migrations disabled. Claude reported no findings. Verification was by code inspection; tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/db/reset/reset.handler.ts:232	error-handling	codex	The ignored-schema warning is suppressed when [db.migrations] enabled = false, although these projects also lose schema-file replay under the new pg-delta default. A versionless experimental reset can therefore drop existing schemas and replay neither schema files nor migrations without explaining the changed behavior.

Stats

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

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews completed. Confirmed one minor test-coverage gap: the remote reset warning currently precedes confirmation, but the test does not protect that ordering. No production bug was established.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/db/reset/reset.integration.test.ts:2909	test-coverage	codex	The test named “warns before the prompt” only checks ordering before reset progress. Moving the warning after confirmation could still pass, leaving the intended pre-confirmation behavior unprotected.

Stats

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

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews completed. Confirmed one minor test-coverage gap: the handler correctly warns before confirmation, but the new test does not verify that ordering. No additional production defect was identified in the inspected changes.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/db/reset/reset.integration.test.ts:2902	test-coverage	codex	The new test does not establish that the schema_paths warning appears before the confirmation prompt.

Stats

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

---

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

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

[Coly010]

Approving so you're unblocked, a few asks inline plus one on the PR body:

The ## BREAKING CHANGES: heading doesn't get picked up by our conventional commits setup, so as it stands this squash renders an empty next release note (I rendered it locally to check). It needs a plain BREAKING CHANGE: paragraph at the very end of the body, below the 🤖 line, since everything after the keyword goes into the notes.

Otherwise looks good to me, thanks for getting this one over the line!

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Verified all three Claude findings against the checked-out code. Two minor hint correctness issues are confirmed; the test-coverage finding is refuted by existing assertions and companion coverage. Codex reported no findings. Tests were not run.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/db/diff/diff.handler.ts:726	correctness	claude	Linked db diff -f can incorrectly include or omit --experimental in its declarative sync suggestion because it uses remote-merged pg-delta settings, while sync gates on the base configuration.
🟡 MINOR	apps/cli/src/commands/db/diff/diff.handler.ts:719	correctness	claude	The hint omits the valid --use-migra alternative when pg-delta is disabled and declarative_schema_path is an absolute path pointing to the workdir's supabase/schemas directory.

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

• apps/cli/src/commands/db/diff/diff.integration.test.ts:1930 (test-coverage): The stack-backend --use-migra=false test relies on placeholder defect text and does not adequately establish flag acceptance or pg-delta selection.
  Refuted: The assertion at :1931 already excludes StackNativeEngineError because that rejection is a typed failure (stack-local-database.ts:168-175). The matched defect originates from the supplied stack-service fixture (tests/helpers/unused-stack.ts:6-17), and the banner assertion establishes progress past validation. The companion integration test explicitly verifies pg-delta selection, so the claimed coverage gap is already addressed.

Stats

Claude findings: 3 · Codex findings: 0 · Confirmed: 2 · Refuted: 1 · Uncertain: 0

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews were available. All three findings are confirmed as distinct guidance issues. The linked-diff suggestion issue is raised to minor because the suggested command can fail. No major or critical issue was established.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/src/commands/db/diff/diff.handler.ts:726	error-messages	claude	A linked diff can suggest declarative sync without the required --experimental flag when a remote override enables pg-delta but the base config disables it.
🟡 MINOR	apps/cli/src/command-internal/diff-engine.ts:5	user-guidance	codex	The shared warning implies disabling pg-delta restores schema_paths consumption for remote migration-style db pull, but the migra fallback also ignores those files.
⚪ NIT	apps/cli/src/command-internal/diff-engine.ts:5	error-messages	claude	The warning recommends setting pg-delta enabled = false even when it is already false and an explicit command flag selected pg-delta.

Stats

Claude findings: 2 · Codex findings: 1 · Confirmed: 3 · Refuted: 0 · Uncertain: 0

---

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

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

[avallete]

/ai-review

[github-actions]

Superseded by a newer AI review

🤖 AI Review

Both independent reviews were available. Claude reported no findings. The sole Codex finding is refuted: local migra pulls do read schema_paths, so the warning reflects the implementation despite the broader wording in the pull documentation.

Findings

No issues found.

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

• apps/cli/src/command-internal/diff-engine.ts:5 (user-guidance): The new warning implies that local migration-style db pull reads schema_paths with --diff-engine migra, contradicting the pull contract documented in the same diff.
  Refuted: The code verifies the warning's local migra exception. For a local migra pull, prepareShadowSource loads schema_paths into contrib_regression and returns a target override; db-pull-run.ts:635 and 670-678 use that override for the migra diff. Removing --diff-engine migra from the warning would therefore make it inaccurate. The conflicting wording in pull.md:19 does not establish the claimed warning defect.

Stats

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

---

Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: manual · 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

Both independent reviews completed and reported zero findings. Reading the checked-out code confirmed consistent pg-delta defaults, explicit migra rollback, declarative gating, and schema-path warnings; no additional actionable issues were found. Tests were not run because workspace dependencies are absent. No next-context.md was provided.

Findings

No issues found.

Stats

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

---

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

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