Skip to content

docs(cli): refresh db pull reference examples and overlay for pg-delta - #6557

Open
avallete wants to merge 2 commits into
developfrom
claude/pg-delta-diffing-consistency-r7kiux
Open

docs(cli): refresh db pull reference examples and overlay for pg-delta#6557
avallete wants to merge 2 commits into
developfrom
claude/pg-delta-diffing-consistency-r7kiux

Conversation

@avallete

@avallete avallete commented Sep 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

The docs-spec generator (apps/cli/scripts/generate-docs-spec.ts, published into supabase/supabase by publish-docs-spec.ts) builds the public db pull reference from apps/cli/docs/supabase/db/pull.md and apps/cli/docs/templates/examples.yaml. Both still described the pre-pg-delta flow, so the next publish would overwrite the hand-edited reference in supabase/supabase#49889 and supabase/supabase#50220 with stale text. This carries the same content into the generator inputs.

examples.yaml, supabase-db-pull:

  • Drop the retired "The auth and storage schemas are excluded. Run supabase db pull --schema auth,storage again to diff them." line. The CLI no longer prints it and no longer excludes those schemas from the baseline.
  • Replace the migra-era "Setting up initial schema" / "Creating custom roles" progress lines with the current shadow-database output ("Creating shadow database", "Seeding globals from roles.sql", "Diffing schemas"), and show the in-sync message the command prints today instead of the generic --debug hint.
  • Point the custom-schemas example at --schema public,extensions, since auth,storage is no longer the motivating case.

pull.md overlay:

  • Name split plan files with the _1 / _2 suffixes the migration writer produces (${name}${suffix}, suffix from pg-delta's renderPlanFiles) instead of the older _schema_changes / _after_enum_values unit-name scheme, and mention the -- pg-delta: transaction=false directive on non-transactional units.
  • Add a paragraph on which customizations in Supabase-managed schemas the pg-delta engine captures, matching the Supabase policy in pg-delta: user triggers on managed tables (function outside the managed schemas), RLS policies on any auth table, and the storage / realtime policy surfaces.

Deliberately not touched here: the paragraphs #6391 rewrites (engine default, initial-pull behavior, debug bundle path) and the --db-url direct-versus-pooler advice, which the docs PR and this overlay currently disagree on and which needs a CLI-team call. Text only, no behavior change.

Linked issue

Follow-up to #6391 (docs alignment); no separate issue.

  • 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. Not applicable: docs inputs only. The existing docs-spec unit tests, which validate examples.yaml ids and overlay paths, pass.
  • 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). Run locally: oxfmt --check on the two files and the src/docs/ unit tests in apps/cli. The full check:all is left to CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2

@claude
docs(cli): refresh db pull reference examples and overlay for pg-delta
d360c47 
The docs-spec generator publishes apps/cli/docs into the supabase/supabase
CLI reference, and the db pull inputs still described the pre-pg-delta
flow. The example responses printed the retired "auth and storage schemas
are excluded" line and the migra-era "Setting up initial schema" /
"Creating custom roles" progress lines; replace them with the current
shadow-database output and the in-sync message the command prints today,
and point the custom-schemas example at public,extensions since auth and
storage no longer need an explicit pull.

In the pull.md overlay, name split plan files with the _1/_2 suffixes the
CLI writer actually produces instead of the older unit-name scheme, note
the transaction=false directive on non-transactional units, and add a
paragraph on which customizations in Supabase-managed schemas the pg-delta
engine captures (user triggers, auth policies, storage and realtime policy
surfaces). Mirrors supabase/supabase#50220 so the next spec publish keeps
that text.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2
@avallete
avallete requested a review from a team as a code owner September 10, 2026 12:22
github-actions[bot]
github-actions Bot reviewed Sep 10, 2026
View reviewed changes

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI Review

Both independent reviews completed. Four unique findings remain after merging the shared pg_dump finding: three are confirmed and one is refuted. The PR inaccurately attributes managed-schema changes to pg_dump and omits the non-initial --schema limitation; it also leaves pre-existing stale start/reset examples. The alleged missing legacy filename documentation is not a current production issue.

Findings

Severity Location Category Sources Claim
🟡 MINOR apps/cli/docs/supabase/db/pull.md:23 documentation-accuracy claude+codex The paragraph incorrectly says the initial pg_dump baseline includes managed-schema trigger and RLS changes; those changes are instead appended by the subsequent migra pass.
🟡 MINOR apps/cli/docs/supabase/db/pull.md:23 documentation-accuracy claude The statement that pg-delta automatically captures managed-schema customizations is overbroad for non-initial pulls using --schema, which exclude actions outside the selected schemas.
⚪ NIT apps/cli/docs/templates/examples.yaml:42 documentation-accuracy claude The edited examples file still contains stale start/reset output strings: Creating custom roles supabase/roles.sql... and Seeding data supabase/seed.sql....

Findings outside the diff

  • ⚪ NIT apps/cli/docs/templates/examples.yaml:42 — The edited examples file still contains stale start/reset output strings: Creating custom roles supabase/roles.sql... and Seeding data supabase/seed.sql....
Refuted findings (kept for transparency, not posted as review comments)
  • apps/cli/docs/supabase/db/pull.md:15 (documentation-completeness): The split-plan documentation should also describe the writer's suffix-less fallback filenames such as _schema_changes.
    Refuted: apps/cli/src/command-internal/pgdelta-engine-runtime.layer.ts:18-19 establishes the next engine as the only production implementation. Its result type requires a string-or-null suffix, and pgdelta-engine.next.layer.ts:88-94 always propagates it. Multi-unit renderer tests verify _1 and _2; the cited pull test bypasses that implementation with an old suffix-less mock. The docs accurately describe current production output.

Stats

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

Comment thread apps/cli/docs/supabase/db/pull.md Outdated
Comment thread apps/cli/docs/supabase/db/pull.md Outdated
@claude
docs(cli): correct managed-schema capture details in db pull overlay
5d5278c 
The migra initial pull seeds the migration with a pg_dump that excludes
the managed schemas (buildSchemaDumpEnv applies INTERNAL_SCHEMAS when no
--schema is passed) and then appends the migra diff to the same file; it
is that second pass, not the dump, that carries trigger and RLS policy
changes in auth and storage. Say so instead of attributing them to the
baseline. Also note that --schema restricts later pg-delta pulls to the
listed schemas while the initial pull ignores it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2
@avallete avallete mentioned this pull request Sep 14, 2026
Merged
@avallete
avallete enabled auto-merge September 14, 2026 11:14
This was referenced Sep 14, 2026
Merged
Merged
avallete added a commit to supabase/supabase that referenced this pull request Sep 17, 2026
@avallete @claude
docs: restore pg-delta opt-in framing and address CodeRabbit findings (…
e736997 
…#50332)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Docs update. Stacked on
[#49280](#49280). Two commits:

1. Fixes for the four CodeRabbit findings from #49280's latest review
round (each verified against the head before changing).
2. Restores the pg-delta opt-in framing after a plan change.

## What is the current behavior?

**Plan change.**
[#50220](#50220) rewrote the
pages to describe `pg-delta` as the default for every project, matching
[supabase/cli#6391](supabase/cli#6391). That
breaking default flip will not ship before Select, so the CLI keeps its
current behavior: a project uses `pg-delta` only when `config.toml` sets
`[experimental.pgdelta] enabled = true`, which `supabase init` writes
for new projects. Existing projects stay on `migra` until they add it.
The branch currently says the opposite in the shared engine partial
(embedded in seven pages), the Diff engines page, the workflow and
declarative guides, the branching page, the config reference (`default:
'true'`), the `db diff` and `db pull` spec descriptions and flag
defaults, and the declarative AI prompt.

**CodeRabbit findings.**

- The branching troubleshooting page says migrations generated on
`pg-delta` "don't need manual reordering". The engine orders statements
within one generated migration, not across migrations generated
separately on branches that later merge.
- The working-with-branches page says `supabase db diff` "never uses
your schema files as its baseline" without qualifying the engine; on
`migra`, `db diff` does read `supabase/schemas/`.
- The declarative walkthroughs run `sync` (which prompts to apply) and
then apply manually with `supabase migration up`.
- Three pages and the `db pull` spec describe the declarative directory
as always `supabase/schemas`, though
`experimental.pgdelta.declarative_schema_path` changes it.

## What is the new behavior?

**Opt-in framing restored.**

- The shared partial and every page that restates the rule say
`pg-delta` is used when `[experimental.pgdelta] enabled = true` is
present, `migra` otherwise.
- Diff engines page: "Which engine" describes `init` writing the setting
and existing projects staying on `migra` until they add it; the
procedure is "Switch an existing project to `pg-delta`" again with "add
the setting" as step 1 (pinned anchor unchanged). The sentence claiming
`SUPABASE_EXPERIMENTAL_PG_DELTA` is ignored is removed, since that was
also tied to the CLI change.
- Config reference: `experimental.pgdelta.enabled` default `false` with
the opt-in description. Commands spec: `--use-migra` default `true`,
`--diff-engine` default `migra`, and the `db diff`, `db pull`, and
`--declarative` descriptions describe both engines by config.
- Declarative AI prompt: prerequisites tell the reader to ensure the
section is present, with `--experimental` as the single-run alternative.

**Kept from #50220 and this branch** because they hold regardless of the
default: the `schema_paths` warning fires only when the setting lists
paths; RLS policies on `auth` tables are captured; the migra initial
pull's `pg_dump` skips managed schemas and the diff pass that follows
appends the trigger and policy changes; and the four CodeRabbit fixes
(scoped reordering claim, engine-qualified baseline claim with a link to
the legacy section, `--no-apply` on the walkthrough `sync` commands,
configurable declarative directory).

## Additional context

Prettier passes with the repo config and both spec YAML files parse.
Eight files, 36 lines changed in the reframing commit; five files, eight
lines in the CodeRabbit commit. The companion
[supabase/cli#6557](supabase/cli#6557) is
unaffected: it updates the `db pull` reference examples and overlay
without asserting a default.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2

---------

Co-authored-by: Claude <noreply@anthropic.com>
avallete added a commit to supabase/supabase that referenced this pull request Sep 21, 2026
@avallete @claude @w3b6x9
docs(cli): update local development workflow docs for pg-delta defaul…
e357ec8 
…t diffing (#49280)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Docs update.

## What is the current behavior?

Linear:
[CLI-1618](https://linear.app/supabase/issue/CLI-1618/update-cli-workflow-docs-for-pg-delta-default-diffing)

Four docs pages lag the shipped CLI behavior now that `pg-delta` is the
default diff engine for projects created by a recent `supabase init`:

- **CLI workflows** claims `db diff` compares `supabase/schemas/`
against migrations. Under `pg-delta`, declarative files are never the
`db diff` baseline (and `[db.migrations].schema_paths` no longer changes
it) — the declarative flow goes through `supabase db schema declarative
sync`. The cleanup guidance describes `migra`-era output.
- **Declarative database schemas** teaches the old `db diff -f` +
`schema_paths` flow throughout, and its known-caveats list is the
`migra` issue list.
- **Managing environments** still presents `--use-migra` as an
"experimental flag" for a "more concise" diff — inverted now.
- **Backup and restore (migrating within Supabase)** and the CLI
workflows guide both steer users to `db diff`/`db pull` with `--schema
auth,storage`. Under `pg-delta`, `--schema` layers an extra exclude
policy on top of the Supabase profile: it can only narrow a diff, never
re-include managed schemas, and managed-schema selections can even fail
closed (e.g. `--schema auth` when a trigger function lives in `public`).
Unfiltered diffs are the supported path.

## What is the new behavior?

All claims verified against the CLI source at current `develop` —
including supabase/cli#6300, which upgraded the engine to
`@supabase/pg-delta` 1.0.0-alpha.46 — against the pinned pg-delta
package source (profile rules, format defaults, coverage doc), and
against a live dogfood run of the documented workflows on `develop`
`38f31b4` (two OSS corpus projects, warm shadow cache).

- **`cli-workflows.mdx`**: adds a "Which diff engine you're on" note
(`pg-delta` for new `supabase init` projects, `migra` for existing ones
until they opt in by adding `[experimental.pgdelta] enabled = true`;
per-run fallbacks `--use-migra` on `db diff` / `--diff-engine migra` on
`db pull`); corrects `db pull` and `db diff` mechanics (shadow built
from migrations vs. live database; the baseline history record is
offered, not unconditional); switches the declarative flow to `supabase
db schema declarative sync`; reworks the cleanup section around pg-delta
output (uppercase keywords at max width 180, `format_options`, per-unit
migration files with numeric segment suffixes, the `-- pg-delta:
transaction=false` directive on genuinely non-transactional files,
engine-neutral grant/revoke review guidance, coverage warnings +
`--strict-coverage`); documents what pg-delta captures in managed
schemas (user triggers, RLS policies on `auth` tables and on
`storage.objects`/`storage.buckets`/`realtime.messages`) versus what it
doesn't; adds key-command rows for the declarative commands and
troubleshooting entries (`db pull` non-zero exit when in sync, the
`schema_paths` warning, `PGDELTA_DEBUG=1` bundles under
`supabase/.temp/pgdelta/v2/debug/`).
- **`declarative-database-schemas.mdx`**: swaps `db diff -f` for `db
schema declarative sync -f` throughout; replaces
lexicographic/`schema_paths` ordering guidance with automatic dependency
ordering and the `generate` export layout (`_cluster/`, reserved
`_custom/`); bootstraps from production via `db schema declarative
generate --linked` (explicit target + `--overwrite` in scripts) and
refreshes via `db pull --declarative`; rewrites known caveats for
pg-delta (DML including storage buckets, untracked object kinds + the
`_custom/` escape hatch, managed schemas, extension-managed objects, and
the two gates when adopting an existing schema tree:
`[experimental.webhooks]` for `pg_net` migrations and declaring the
tree's extensions) keeping the `migra` workflow and issue list under a
legacy section for projects that haven't enabled it.
- **`managing-environments.mdx`**: frames the verbose grant sample as
legacy-engine output, notes that generated migrations can include grant
statements on any engine, describes `--use-migra` as a single-run
fallback, and adds a `db diff --strict-coverage` CI step.
- **`backup-restore.mdx`**: replaces `db diff --linked --schema
auth,storage` with a plain `db diff --linked` on `pg-delta` (keeping the
`--schema auth,storage` form for the legacy engine) and explains what
the engine includes (user triggers on managed tables, user RLS policies
on `auth`, `storage.objects`/`storage.buckets`/`realtime.messages`) and
what must be recreated manually.
- **New `diff-engines.mdx` page** (from #49889): the single home for how
the engine is selected, a behavior matrix for `pg-delta` versus `migra`,
the per-command fallback flags, a procedure for switching an existing
project (the first `db pull` after enabling may write a catch-up
migration), and how to go back with `enabled = false`. Registered in
navigation. A shared `diff_engine_check` partial replaces the inline
engine parentheticals across seven pages, and a
`managed_schemas_diff_capture` partial carries the managed-schema
capture rules.
- **CLI reference (`cli_v1_commands.yaml`, `cli_v1_config.yaml`)**: `db
pull`, `db schema declarative sync`/`generate` flags and descriptions,
`experimental.pgdelta.*` and `db.migrations.schema_paths` config keys,
and the `db diff` description updated to describe both engines. Note
that `cli_v1_commands.yaml` is generated from the CLI repo;
[supabase/cli#6557](supabase/cli#6557) carries
the matching `db pull` example and overlay text so the next publish
keeps it.
- **`examples/prompts/declarative-database-schema.md`**: rewritten for
the `db schema declarative sync` flow, with the `[experimental.pgdelta]`
prerequisite.

## Additional context

The first draft was written against pg-delta 1.0.0-alpha.42.
supabase/cli#6300 (engine upgrade to alpha.46) then changed two
documented behaviors, both reflected here: generated SQL now defaults to
uppercase pretty-printed keywords, and user RLS policies on
`storage.objects`/`storage.buckets`/`realtime.messages` are included via
the engine's `SUPABASE_USER_POLICY_SURFACES` allowlist. A follow-up
dogfood run on `develop` `38f31b4` then falsified three more claims
(pg-delta emits no grant noise, `_schema_changes`/`_after_enum_values`
multi-file names, directive on every split file), all corrected in the
last commit.

**Update (Sep 14 to 17):**
[#49889](#49889) and
[#50220](#50220) were merged
into this branch, so this PR now carries the full stack. #50220
corrected the `schema_paths` warning wording (the CLI warns only when
the setting lists paths), added `auth` RLS policies to the
managed-schema partial, and described the migra initial pull accurately
(the `pg_dump` skips managed schemas and the migra diff pass that
follows appends the trigger and policy changes). It also reframed
`pg-delta` as the default for every project ahead of supabase/cli#6391.
That plan changed: no breaking default flip before Select, so
[#50332](#50332) restores the
opt-in framing (`pg-delta` requires `[experimental.pgdelta] enabled =
true`, which `supabase init` writes for new projects) and also resolves
the four CodeRabbit findings from the latest review round.

Two claims are pending confirmation from the owning teams: that
branching runs every migration in a transaction and ignores the `--
pg-delta: transaction=false` directive, and the `--db-url`
pooler-versus-direct connection advice, which currently disagrees with
the CLI's own `db pull` docs.

Stale spots found in the CLI repo's own docs while verifying (out of
scope here, worth follow-ups): four `SIDE_EFFECTS.md` files still claim
lowercase output, `docs/supabase/db/diff.md` still lists `migra`-era
"known failure cases" that alpha.46 fully models, the `supabase init`
template's commented `format_options` example shows `maxWidth: 80`
against an actual default of 180, and the CLI upgrade recipe appends
`--experimental` even when the config already enables pg-delta.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01SUuaVmXLRbV6tZjzhka3cp

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Clarified `pg-delta` and legacy `migra` behavior, configuration, and
switching guidance.
* Expanded declarative schema workflows, including synchronization,
migration generation, baselines, deployment, and legacy-engine support.
* Documented managed schemas, permissions, extensions, transaction
handling, dependency ordering, and troubleshooting.
* Added guidance for strict coverage checks, output directories,
non-interactive workflows, and declarative pull modes.
* Added a dedicated diff engines guide and updated CLI navigation,
backup and restore, branching, deployment, and CI documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Wen Bo Xie <wenbox323@gmail.com>
ChloeGarciaMillerand pushed a commit to ChloeGarciaMillerand/supabase that referenced this pull request Sep 21, 2026
@avallete @claude
@w3b6x9 @ChloeGarciaMillerand
docs(cli): update local development workflow docs for pg-delta defaul…
99111bf 
…t diffing (supabase#49280)

## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.

YES

## What kind of change does this PR introduce?

Docs update.

## What is the current behavior?

Linear:
[CLI-1618](https://linear.app/supabase/issue/CLI-1618/update-cli-workflow-docs-for-pg-delta-default-diffing)

Four docs pages lag the shipped CLI behavior now that `pg-delta` is the
default diff engine for projects created by a recent `supabase init`:

- **CLI workflows** claims `db diff` compares `supabase/schemas/`
against migrations. Under `pg-delta`, declarative files are never the
`db diff` baseline (and `[db.migrations].schema_paths` no longer changes
it) — the declarative flow goes through `supabase db schema declarative
sync`. The cleanup guidance describes `migra`-era output.
- **Declarative database schemas** teaches the old `db diff -f` +
`schema_paths` flow throughout, and its known-caveats list is the
`migra` issue list.
- **Managing environments** still presents `--use-migra` as an
"experimental flag" for a "more concise" diff — inverted now.
- **Backup and restore (migrating within Supabase)** and the CLI
workflows guide both steer users to `db diff`/`db pull` with `--schema
auth,storage`. Under `pg-delta`, `--schema` layers an extra exclude
policy on top of the Supabase profile: it can only narrow a diff, never
re-include managed schemas, and managed-schema selections can even fail
closed (e.g. `--schema auth` when a trigger function lives in `public`).
Unfiltered diffs are the supported path.

## What is the new behavior?

All claims verified against the CLI source at current `develop` —
including supabase/cli#6300, which upgraded the engine to
`@supabase/pg-delta` 1.0.0-alpha.46 — against the pinned pg-delta
package source (profile rules, format defaults, coverage doc), and
against a live dogfood run of the documented workflows on `develop`
`38f31b4` (two OSS corpus projects, warm shadow cache).

- **`cli-workflows.mdx`**: adds a "Which diff engine you're on" note
(`pg-delta` for new `supabase init` projects, `migra` for existing ones
until they opt in by adding `[experimental.pgdelta] enabled = true`;
per-run fallbacks `--use-migra` on `db diff` / `--diff-engine migra` on
`db pull`); corrects `db pull` and `db diff` mechanics (shadow built
from migrations vs. live database; the baseline history record is
offered, not unconditional); switches the declarative flow to `supabase
db schema declarative sync`; reworks the cleanup section around pg-delta
output (uppercase keywords at max width 180, `format_options`, per-unit
migration files with numeric segment suffixes, the `-- pg-delta:
transaction=false` directive on genuinely non-transactional files,
engine-neutral grant/revoke review guidance, coverage warnings +
`--strict-coverage`); documents what pg-delta captures in managed
schemas (user triggers, RLS policies on `auth` tables and on
`storage.objects`/`storage.buckets`/`realtime.messages`) versus what it
doesn't; adds key-command rows for the declarative commands and
troubleshooting entries (`db pull` non-zero exit when in sync, the
`schema_paths` warning, `PGDELTA_DEBUG=1` bundles under
`supabase/.temp/pgdelta/v2/debug/`).
- **`declarative-database-schemas.mdx`**: swaps `db diff -f` for `db
schema declarative sync -f` throughout; replaces
lexicographic/`schema_paths` ordering guidance with automatic dependency
ordering and the `generate` export layout (`_cluster/`, reserved
`_custom/`); bootstraps from production via `db schema declarative
generate --linked` (explicit target + `--overwrite` in scripts) and
refreshes via `db pull --declarative`; rewrites known caveats for
pg-delta (DML including storage buckets, untracked object kinds + the
`_custom/` escape hatch, managed schemas, extension-managed objects, and
the two gates when adopting an existing schema tree:
`[experimental.webhooks]` for `pg_net` migrations and declaring the
tree's extensions) keeping the `migra` workflow and issue list under a
legacy section for projects that haven't enabled it.
- **`managing-environments.mdx`**: frames the verbose grant sample as
legacy-engine output, notes that generated migrations can include grant
statements on any engine, describes `--use-migra` as a single-run
fallback, and adds a `db diff --strict-coverage` CI step.
- **`backup-restore.mdx`**: replaces `db diff --linked --schema
auth,storage` with a plain `db diff --linked` on `pg-delta` (keeping the
`--schema auth,storage` form for the legacy engine) and explains what
the engine includes (user triggers on managed tables, user RLS policies
on `auth`, `storage.objects`/`storage.buckets`/`realtime.messages`) and
what must be recreated manually.
- **New `diff-engines.mdx` page** (from supabase#49889): the single home for how
the engine is selected, a behavior matrix for `pg-delta` versus `migra`,
the per-command fallback flags, a procedure for switching an existing
project (the first `db pull` after enabling may write a catch-up
migration), and how to go back with `enabled = false`. Registered in
navigation. A shared `diff_engine_check` partial replaces the inline
engine parentheticals across seven pages, and a
`managed_schemas_diff_capture` partial carries the managed-schema
capture rules.
- **CLI reference (`cli_v1_commands.yaml`, `cli_v1_config.yaml`)**: `db
pull`, `db schema declarative sync`/`generate` flags and descriptions,
`experimental.pgdelta.*` and `db.migrations.schema_paths` config keys,
and the `db diff` description updated to describe both engines. Note
that `cli_v1_commands.yaml` is generated from the CLI repo;
[supabase/cli#6557](supabase/cli#6557) carries
the matching `db pull` example and overlay text so the next publish
keeps it.
- **`examples/prompts/declarative-database-schema.md`**: rewritten for
the `db schema declarative sync` flow, with the `[experimental.pgdelta]`
prerequisite.

## Additional context

The first draft was written against pg-delta 1.0.0-alpha.42.
supabase/cli#6300 (engine upgrade to alpha.46) then changed two
documented behaviors, both reflected here: generated SQL now defaults to
uppercase pretty-printed keywords, and user RLS policies on
`storage.objects`/`storage.buckets`/`realtime.messages` are included via
the engine's `SUPABASE_USER_POLICY_SURFACES` allowlist. A follow-up
dogfood run on `develop` `38f31b4` then falsified three more claims
(pg-delta emits no grant noise, `_schema_changes`/`_after_enum_values`
multi-file names, directive on every split file), all corrected in the
last commit.

**Update (Sep 14 to 17):**
[supabase#49889](supabase#49889) and
[supabase#50220](supabase#50220) were merged
into this branch, so this PR now carries the full stack. supabase#50220
corrected the `schema_paths` warning wording (the CLI warns only when
the setting lists paths), added `auth` RLS policies to the
managed-schema partial, and described the migra initial pull accurately
(the `pg_dump` skips managed schemas and the migra diff pass that
follows appends the trigger and policy changes). It also reframed
`pg-delta` as the default for every project ahead of supabase/cli#6391.
That plan changed: no breaking default flip before Select, so
[supabase#50332](supabase#50332) restores the
opt-in framing (`pg-delta` requires `[experimental.pgdelta] enabled =
true`, which `supabase init` writes for new projects) and also resolves
the four CodeRabbit findings from the latest review round.

Two claims are pending confirmation from the owning teams: that
branching runs every migration in a transaction and ignores the `--
pg-delta: transaction=false` directive, and the `--db-url`
pooler-versus-direct connection advice, which currently disagrees with
the CLI's own `db pull` docs.

Stale spots found in the CLI repo's own docs while verifying (out of
scope here, worth follow-ups): four `SIDE_EFFECTS.md` files still claim
lowercase output, `docs/supabase/db/diff.md` still lists `migra`-era
"known failure cases" that alpha.46 fully models, the `supabase init`
template's commented `format_options` example shows `maxWidth: 80`
against an actual default of 180, and the CLI upgrade recipe appends
`--experimental` even when the config already enables pg-delta.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01SUuaVmXLRbV6tZjzhka3cp

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Clarified `pg-delta` and legacy `migra` behavior, configuration, and
switching guidance.
* Expanded declarative schema workflows, including synchronization,
migration generation, baselines, deployment, and legacy-engine support.
* Documented managed schemas, permissions, extensions, transaction
handling, dependency ordering, and troubleshooting.
* Added guidance for strict coverage checks, output directories,
non-interactive workflows, and declarative pull modes.
* Added a dedicated diff engines guide and updated CLI navigation,
backup and restore, branching, deployment, and CI documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Wen Bo Xie <wenbox323@gmail.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@github-actions github-actions[bot] github-actions[bot] left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@avallete @claude