dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-05 09:25:06 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(cli): update local development workflow docs for pg-delta default diffing (#49280)

Browse Source 
## 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](https://github.com/supabase/cli/pull/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](https://github.com/supabase/supabase/pull/49889) and
[#50220](https://github.com/supabase/supabase/pull/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](https://github.com/supabase/supabase/pull/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 commit is contained in:
Andrew ValleteauClaudeWen Bo Xie
 authored and GitHub committed 2026-09-21 12:07:10 +02:00
1 parent ad30c04e0e
commit e357ec8f9f
19 files changed
+556 -190
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

examples/prompts/declarative-database-schema.md
+55 -42
View File
@@ -10,68 +10,81 @@ Mandatory Instructions for Supabase Declarative Schema Management
## 1. **Exclusive Use of Declarative Schema**
-**All database schema modifications must be defined within `.sql` files located in the `supabase/schemas/` directory. -**Do not\*\* create or modify files directly in the `supabase/migrations/` directory unless the modification is about the known caveats below. Migration files are to be generated automatically through the CLI.
- **All database schema modifications must be defined within `.sql` files located in the `supabase/schemas/` directory**
- **Do not** create or modify files directly in the `supabase/migrations/` directory unless the change falls under the known caveats below. Generate migration files through the CLI instead
- **Do not** modify the database directly through Studio, the SQL editor, or `psql`. The schema files are the source of truth. Direct database changes are invisible to the diff and are silently dropped
## 2. **Schema Declaration**
## 2. **Prerequisites**
-For each database entity (e.g., tables, views, functions), create or update a corresponding `.sql` file in the `supabase/schemas/` directory
-Ensure that each `.sql` file accurately represents the desired final state of the entity
## 3. **Migration Generation**
- Before generating migrations, **stop the local Supabase development environment**
```bash
supabase stop
- The declarative workflow requires the `pg-delta` diff engine. Ensure `supabase/config.toml` contains:
```toml
[experimental.pgdelta]
enabled = true
```
- Generate migration files by diffing the declared schema against the current database state
- Projects created with a recent `supabase init` have this enabled by default. On older projects, add the section above before generating migrations. Alternatively, pass the `--experimental` flag for a single command run
## 3. **Schema Declaration**
- For each database entity (e.g., tables, views, functions), create or update a corresponding `.sql` file in the `supabase/schemas/` directory
- Ensure that each `.sql` file accurately represents the desired final state of the entity
## 4. **Migration Generation**
- After editing files in `supabase/schemas/`, generate and apply a migration in one step:
```bash
supabase db diff -f <migration_name>
supabase db schema declarative sync -f <migration_name> --apply
```
Replace `<migration_name>` with a descriptive name for the migration
- `--apply` (or the global `--yes`) applies the generated migration to the local database without prompting. Without either flag, the command prompts in a terminal and only writes the file when run non-interactively. Pass `--no-apply` to only generate the file
- **Do not** run `supabase stop` first. The local stack can stay running because `sync` compares your schema files against your migration history, not the live database
- **Do not** use `supabase db diff` to generate migrations from schema files. It diffs a live database against your migrations and never uses `supabase/schemas/` as its baseline
- Review every generated migration file before committing it
## 4. **Schema File Organization**
## 5. **Schema File Organization**
- Schema files are executed in lexicographic order. To manage dependencies (e.g., foreign keys), name files to ensure correct execution order
- File names and directory layout are for readability only. The engine analyzes dependencies between statements (foreign keys, views over tables, functions used by triggers) and orders them automatically. Do not rely on lexicographic file ordering to manage dependencies
- When adding new columns, append them to the end of the table definition to prevent unnecessary diffs
- Reserve the `supabase/schemas/_custom/` directory for hand-authored SQL covering object kinds the engine does not track (see known caveats). Create the directory yourself. The CLI never creates, overwrites, or prunes it
## 5. **Rollback Procedures**
## 6. **Rollback Procedures**
- To revert changes
- Manually update the relevant `.sql` files in `supabase/schemas/` to reflect the desired state
- Generate a new migration file capturing the rollback
```bash
supabase db diff -f <rollback_migration_name>
```
- Review the generated migration file carefully to avoid unintentional data loss
- To revert a change that has **not** been deployed, reset the local database to a previous migration version, then edit the schema files and regenerate a single migration:
```bash
supabase db reset --version <timestamp>
supabase db schema declarative sync -f <migration_name>
```
- To revert a change that **has** been deployed, first update the relevant `.sql` files in `supabase/schemas/` to reflect the desired state, then generate a new forward migration:
```bash
supabase db schema declarative sync -f <rollback_migration_name>
```
- Review the generated migration file carefully to avoid unintentional data loss. Down migrations are usually destructive
## 6. **Known caveats**
## 7. **Known caveats**
The migra diff tool used for generating schema diff is capable of tracking most database changes. However, there are edge cases where it can fail.
If you need to use any of the entities below, remember to add them through versioned migrations instead.
Schema diffs are generated by the `pg-delta` engine, which models most database entities, including tables, views, materialized views, functions, triggers, RLS policies, grants, comments, domains, partitions, and publications. The cases below are not captured.
### Data manipulation language
- DML statements such as insert, update, delete, etc., are not captured by schema diff
- DML statements such as `insert`, `update`, and `delete` are never captured by a schema diff. This includes storage buckets, which are rows in `storage.buckets`, not schema objects
- A DML statement inside a declarative schema file is an error. Keep data changes in seed files or hand-written versioned migrations
### View ownership
### Untracked object kinds
- view owner and grants
- security invoker on views
- materialized views
- doesn’t recreate views when altering column type
- The engine does not track: casts, operators, operator classes and families, text search configurations, dictionaries, parsers, and templates, statistics objects, languages, transforms, and parameter ACLs. The engine reports them as warnings instead of silently dropping them
- To use these objects, put their SQL in the reserved `supabase/schemas/_custom/` directory so dependent objects still resolve, and deliver the change itself through a versioned migration. That migration must sort before the generated migration that depends on the object, or `db reset` and later `sync` runs fail
- Exception: manage parameter ACLs through versioned migrations only. Do not put them in `_custom/`
### RLS policies
### Supabase-managed schemas
- alter policy statements
- column privileges
- Other entities#
- schema privileges are not tracked because each schema is diffed separately
- comments are not tracked
- partitions are not tracked
- alter publication ... add table ...
- create domain statements are ignored
- grant statements are duplicated from default privileges
- Platform objects in Supabase-managed schemas (such as `auth` and `storage`) are excluded from diffs, but your own customizations on top of them are captured: triggers on managed tables whose trigger function lives outside the managed schemas (for example, a trigger on `auth.users` that calls a function in `public`), RLS policies on any table in `auth`, and RLS policies on `storage.objects`, `storage.buckets`, and `realtime.messages`. A trigger whose function lives inside `auth` or `storage` is excluded even if you created the function; deliver it through a versioned migration. Other objects you create inside these schemas, such as your own functions or indexes, are not diffed. Manage those through versioned migrations
### Extension-managed objects
- Objects that extensions create and manage, such as partitions maintained by `pg_partman` and queue tables created by `pgmq`, are never emitted as raw `create table` or `drop table` statements. Changes to them appear as calls to the extension's own API (for example `select pgmq.drop_queue('q');`), and the CLI flags those as destructive. Create and change these objects through the extension's own functions and review any generated API calls
### Legacy `migra` engine
- If `[experimental.pgdelta]` is not enabled, the project falls back to the legacy `migra`-based workflow (`supabase stop`, then `supabase db diff -f <migration_name>`), which has additional limitations around view owners and grants, security invoker on views, `alter policy`, column privileges, comments, publication membership, roles, and domains. Enable `pg-delta` instead of following that flow
---