Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Advanced Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
the
documentation
w3b6x9
force-pushed
the
docs/pg-delta-diff-engines
branch
from
September 2, 2026 10:20
f158bc9 to
fc5dbf6
Compare
w3b6x9
commented
Sep 2, 2026
|
|
||
| If your project uses [declarative schemas](/docs/guides/local-development/declarative-database-schemas), the files in `supabase/schemas/` are not applied by branching. Run `supabase db schema declarative sync` to generate a migration from your schema changes, and commit the generated migration alongside your schema files. | ||
|
|
||
| Branching runs each migration file inside a single transaction and does not honor the `-- pg-delta: transaction=false` directive. A migration that can't run in a transaction (for example, one that uses `create index concurrently`, or a [`pg-delta`](/docs/guides/local-development/diff-engines) file that carries the directive) applies with `supabase db push` but fails when branching deploys it. |
Member
Author
There was a problem hiding this comment.
The team is currently working out a solution so this is subject to change.
w3b6x9
commented
Sep 2, 2026
| `db reset`, `db push`, and `migration up` honor it by running the file's statements without a wrapping transaction. Never delete that line. Not every split file carries it: `alter type ... add value` runs in its own transaction, so its file is separate but has no directive. | ||
| `db reset`, `db push`, and `migration up` honor it by running the file's statements without a wrapping transaction. Keep the line. The CLI detects `create index concurrently` on its own and runs it standalone even without the directive, but other statements that can't run in a transaction depend on it. The directive also changes what happens on failure. Without a wrapping transaction, a failed statement leaves the earlier statements in the file applied. | ||
|
|
||
| Deploys through the [GitHub integration](/docs/guides/deployment/branching/github-integration) don't honor the directive and run every migration inside a transaction, so these migrations fail there. Not every split file carries it. `alter type ... add value` runs in its own transaction, so its file is separate but has no directive. |
Member
Author
There was a problem hiding this comment.
The team is looking into this so this is subject to change.
New projects use the pg-delta diff engine, but existing projects stay on migra until they opt in. The docs described only pg-delta, so commands that behave differently per engine, such as db diff reading supabase/schemas/ and the initial db pull, were documented as if every project were on the new engine. Add a Diff engines guide as the single home for engine detection, a behavior matrix, the per-command fallback flags, and a procedure for switching an existing project. Replace the repeated inline engine parentheticals with a shared partial, and add a legacy migra section to the declarative schemas guide so existing workflows stay documented. Register the new page in navigation and expand the CLI reference for db pull, db schema declarative sync and generate, and the experimental.pgdelta config keys. migra baseline pulls no longer exclude auth and storage, extension-managed objects are diffed through the extension API and flagged destructive, the split-file example uses a check constraint, _custom/ is user-created, non-interactive sync only prints the adoption recipe, remotes gating is by protected branch, the transaction directive paragraph explains create index concurrently auto-detection and partial-state failure, and db pull --declarative breaks db diff on the legacy engine. Document the open pg-delta gap where an in-place column default change to a new enum value is ordered before the add value statement.
w3b6x9
force-pushed
the
docs/pg-delta-diff-engines
branch
from
September 2, 2026 11:15
fc5dbf6 to
3f87d28
Compare
This was referenced Sep 10, 2026
…50220) ## 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 [#49889](#49889) (which is itself stacked on [#49280](#49280)); merge bottom-up. ## What is the current behavior? #49889 documents the engine rule as "projects created by a recent `supabase init` use `pg-delta`, existing projects stay on `migra` until they add `[experimental.pgdelta] enabled = true`". That rule is inherited from #49280 and is repeated in the shared `diff_engine_check` partial (embedded in seven pages), the Diff engines page, the config reference (`experimental.pgdelta.enabled` default `false`), the commands spec (`db diff --use-migra` default `true`, `db pull --diff-engine` default `migra`), and the declarative-schema AI prompt. [supabase/cli#6391](supabase/cli#6391) makes `pg-delta` the default for every project: an absent `[experimental.pgdelta]` section or an omitted `enabled` key resolves to `pg-delta`, and only an explicit `enabled = false` selects `migra`. The CLI PR's own docs, JSON schema default, and `supabase init` template all say this. Two other claims in #49889 don't match the CLI source: - The `[db.migrations].schema_paths` warning is described as firing "whenever the setting is present, even when empty". Both `db diff` and migration-style `db pull` only warn when the list is non-empty, and the current `init` template still writes `schema_paths = []`. - The managed-schema partial lists RLS policies on `storage.objects`, `storage.buckets`, and `realtime.messages` as captured. pg-delta's Supabase profile also treats every RLS policy in the `auth` schema as user-authored, and the local database-migrations page opens with "triggers or RLS policies on your `auth` schema" but then only says triggers are captured. ## What is the new behavior? - The shared partial and every page that restates the rule now say `pg-delta` is used unless `config.toml` sets `enabled = false`. - The Diff engines page's "Which engine" section describes the default plus the rollback, and the "Switch an existing project" procedure becomes "Upgrade an existing project": no config change is needed, the first `db pull` after upgrading may produce a catch-up migration, and `enabled = false` is the rollback. The pinned anchor `#switch-an-existing-project-to-pg-delta` is kept so existing links resolve. The now-ignored `SUPABASE_EXPERIMENTAL_PG_DELTA` environment variable is called out. - Config reference: `experimental.pgdelta.enabled` default is `true` with a rewritten description. Commands spec: `--use-migra` default `false`, `--diff-engine` default `pg-delta`, the `db diff` description no longer says migra runs by default (its known-miss list is scoped to migra), the `db pull` description drops the "pass `--diff-engine pg-delta`" framing, and the `--declarative` note is reworded for opt-out projects. - The `schema_paths` warning wording is corrected in the three places it appears. - `auth` RLS policies are added to the managed-schema partial and the local database-migrations page. - The declarative AI prompt's prerequisites describe the default and warn against `enabled = false` instead of telling older projects to add the section. ## Additional context `apps/docs/spec/cli_v1_commands.yaml` is generated by the CLI repo's docs-spec generator (`apps/cli/scripts/generate-docs-spec.ts`, published by `publish-docs-spec.ts`). The flag entries regenerate from the command definitions, but the command descriptions and examples come from the CLI repo's `apps/cli/docs/supabase/db/*.md` overlays and `docs/templates/examples.yaml`. The spec edits here (and the ones in #49889) will be replaced on the next publish, so a companion CLI PR carries the same `db pull` example and overlay text into the generator inputs. The `db diff` description already matches what cli#6391 puts in `diff.md`. Two items from #49889 are intentionally left as they are, since they need a decision from the owning teams rather than an edit: the claim that branching ignores the `-- pg-delta: transaction=false` directive (the author's own review threads mark it as subject to change), and the `--db-url` pooler-versus-direct advice, which contradicts the CLI's own `db pull` docs. Verified locally: Prettier passes on all changed files with the repo config, both spec YAML files parse, every in-page anchor and cross-page link target in the changed files resolves. `supa-mdx-lint` could not be run in this environment and is left to CI. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2 --- _Generated by [Claude Code](https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
Member
|
#50220 merged into this branch, so the pages now describe The Generated by Claude Code |
avallete
merged commit Sep 14, 2026
1936074
into
claude/cli-workflow-docs-pg-delta-d8rx6z
15 of 23 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
New projects use the pg-delta diff engine, but existing projects stay on migra until they opt in. The docs described only pg-delta, so commands that behave differently per engine, such as db diff reading supabase/schemas/ and the initial db pull, were documented as if every project were on the new engine.
Add a Diff engines guide as the single home for engine detection, a behavior matrix, the per-command fallback flags, and a procedure for switching an existing project. Replace the repeated inline engine parentheticals with a shared partial, and add a legacy migra section to the declarative schemas guide so existing workflows stay documented. Register the new page in navigation and expand the CLI reference for db pull, db schema declarative sync and generate, and the experimental.pgdelta config keys.
migra baseline pulls no longer exclude auth and storage, extension-managed objects are diffed through the extension API and flagged destructive, the split-file example uses a check constraint, _custom/ is user-created, non-interactive sync only prints the adoption recipe, remotes gating is by protected branch, the transaction directive paragraph explains create index concurrently auto-detection and partial-state failure, and db pull --declarative breaks db diff on the legacy engine. Document the open pg-delta gap where an in-place column default change to a new enum value is ordered before the add value statement.