The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs(cli): align declarative schema and diff engine docs with CLI behavior (#51609)
Wen Bo Xie21f7e306ee6a
diff --git a/apps/docs/content/guides/local-development/declarative-database-schemas.mdx b/apps/docs/content/guides/local-development/declarative-database-schemas.mdxindex 8ec5bef3d8d..e82961d30b7 100644--- a/apps/docs/content/guides/local-development/declarative-database-schemas.mdx+++ b/apps/docs/content/guides/local-development/declarative-database-schemas.mdx@@ -91,7 +91,7 @@ supabase migration upWith declarative schemas, the files in `supabase/schemas/` are the source of truth. `supabase db schema declarative sync` compares those files against your migrations. It does not read the live database. Changes you make directly (Studio, the SQL editor, `psql`) are invisible to the diff, which reports "No schema changes found" and silently drops the change. Always edit the schema files, then run `sync`.-Don't use `supabase db diff` here, because it diffs a live database against your migrations and never uses `supabase/schemas/` as its baseline.+Don't use `supabase db diff` here, because it diffs a live database against your migrations and never uses `supabase/schemas/` as its baseline. If you run `supabase db diff -f` while schema files exist, the CLI prints a note that it ignored them. When your migrations are empty or outdated, the migration it writes can include objects your schema files already declare.</Admonition>@@ -283,6 +283,15 @@ supabase db schema declarative generate --linkedThis writes per-object SQL files under `supabase/schemas/` (or the directory set by `experimental.pgdelta.declarative_schema_path`), organized by database schema. In scripts, pass the target explicitly (`--local`, `--linked`, or `--db-url`) and add `--overwrite` to replace an existing tree without prompting. To later refresh the declarative tree from the remote database (for example, after a change was deployed outside your local workflow), run `supabase db pull --declarative`. It replaces the schema files without creating a migration or touching migration history.+<Admonition type="note" label="Schema files in `supabase/database`">++CLI versions before 2.115.0 wrote the declarative tree to `supabase/database`. Version 2.115.0 and later read `supabase/schemas` and warn when `supabase/database` holds schema files, `supabase/schemas` is empty, and `declarative_schema_path` is unset. To clear the warning, do one of the following:++- Move the tree to `supabase/schemas/`.+- Keep the tree in place and set `declarative_schema_path = "./database"` under `[experimental.pgdelta]`.++</Admonition>+`generate` writes schema files only. Because `sync` diffs your schema files against your migration history, that history must describe the same database before your first `sync`. If your project has no migrations yet, run `supabase db pull` first to create a baseline migration. Without a baseline, the first `sync` regenerates the entire schema as one migration. That migration can apply cleanly to an empty local database and still fail on `db push`, because the remote database already has those objects.### Rolling back a schema change@@ -348,7 +357,12 @@ Projects that haven't enabled `pg-delta` can still use declarative schemas. The<Admonition type="caution">-On the legacy engine, don't run `supabase db pull --declarative`. The command runs regardless of the `[experimental.pgdelta]` setting, but the tree it writes is only readable by the `db schema declarative` commands. `db diff` on the legacy engine tries to load that tree as its baseline, in lexicographic order, and fails on the first file. If you've already run it, delete the generated tree under `supabase/schemas/` or [switch to `pg-delta`](#switching-to-pg-delta).+On the legacy engine, don't run `supabase db pull --declarative`. The command runs regardless of the `[experimental.pgdelta]` setting and writes a per-object tree meant for the `db schema declarative` commands. It also points `[db.migrations].schema_paths` in `config.toml` at that tree. The next local `db diff` applies the files in lexicographic order without resolving dependencies between them, so it fails when a file sorts before an object it depends on.++If you've already run it, [switch to `pg-delta`](#switching-to-pg-delta), or undo both changes:++1. Delete the files the export wrote to the declarative directory (`supabase/schemas/` by default). Files that were already there are left in place.+2. Restore `[db.migrations].schema_paths` in `config.toml` to its previous value, or remove it if the export added it.</Admonition>diff --git a/apps/docs/content/guides/local-development/diff-engines.mdx b/apps/docs/content/guides/local-development/diff-engines.mdxindex e357a2ea0da..f8180dafafe 100644--- a/apps/docs/content/guides/local-development/diff-engines.mdx+++ b/apps/docs/content/guides/local-development/diff-engines.mdx@@ -24,12 +24,15 @@ enabled = trueExisting projects without that section keep the legacy `migra` engine until they add it. See [Switch an existing project to `pg-delta`](#switch-an-existing-project-to-pg-delta).-To use `migra` for a single run without changing `config.toml`, the flag depends on the command:+To switch engines for a single run without changing `config.toml`, the flag depends on the command:-| Command | Flag to fall back to `migra` |-| --------- | ---------------------------- |-| `db diff` | `--use-migra` |-| `db pull` | `--diff-engine migra` |+| Command | Flag to use `pg-delta` | Flag to use `migra` |+| ------------------------------------------- | ------------------------ | --------------------- |+| `db diff` | `--use-pg-delta` | `--use-migra` |+| `db pull` | `--diff-engine pg-delta` | `--diff-engine migra` |+| `db schema declarative generate` and `sync` | `--experimental` | Not available |++For `db diff` and `db pull`, setting `SUPABASE_EXPERIMENTAL_PG_DELTA=1` in your shell or in `supabase/.env` has the same effect as `enabled = true`. An explicit engine flag on the command still wins.To opt out entirely, set `enabled = false` under `[experimental.pgdelta]`.@@ -45,7 +48,7 @@ The commands and the migration workflow are the same on both engines. What diffe| Ordering of declarative files | Automatic, based on dependencies between statements. `[db.migrations].schema_paths` is ignored, and the CLI warns when the setting lists any paths. | Lexicographic by default. `[db.migrations].schema_paths` overrides the order. Files in `supabase/schemas/` are used even when the setting is empty. || Initial `db pull` (empty migration history) | Diffs the remote database against an empty shadow database. Your customizations in managed schemas, such as triggers on `auth.users` and RLS policies on `storage.objects`, are included. | Seeds the migration with `pg_dump`, which skips managed schemas, then appends a diff of your triggers and RLS policies in `auth` and `storage`. Older versions excluded those schemas and told you to run `supabase db pull --schema auth,storage`. || Later `db pull` runs | Diffs the remote database against your migrations. | Same. Trigger and RLS policy changes in managed schemas are included. |-| `db pull --declarative` | Replaces `supabase/schemas/` from the selected database without creating a migration. | Runs, but don't use it. The tree it writes is only readable by the `db schema declarative` commands. `db diff` on the legacy engine then tries to load that tree as its baseline and fails. |+| `db pull --declarative` | Replaces `supabase/schemas/` from the selected database without creating a migration. | Runs, but don't use it. The command also points `[db.migrations].schema_paths` at the tree it writes. The next local `db diff` applies those files in lexicographic order and fails when a file sorts before an object it depends on. || Objects the engine doesn't track | Reported as warnings and never silently dropped. Pass `--strict-coverage` to turn the warnings into failures. | Silently omitted. `--strict-coverage` has no effect. || Generated SQL | Uppercase keywords wrapped at 180 characters. Configurable with `[experimental.pgdelta] format_options`. | Engine default formatting. || Migration files per run | Usually one. When a change crosses a transaction boundary, it may write one ordered file per unit with `_1`, `_2` suffixes. Files whose statements can't run in a transaction start with `-- pg-delta: transaction=false`. | One file. |diff --git a/apps/docs/spec/cli_v1_commands.yaml b/apps/docs/spec/cli_v1_commands.yamlindex 0af1323dc4a..dcc6a0a8a3d 100644--- a/apps/docs/spec/cli_v1_commands.yaml+++ b/apps/docs/spec/cli_v1_commands.yaml@@ -2947,7 +2947,7 @@ commands:Reset local database to match migrations first? (local data will be lost) [y/N] yResetting database......- Declarative schema written to supabase/database+ Declarative schema written to supabase/schemasFinished supabase db schema declarative generate.tags: []links: []@@ -2984,7 +2984,6 @@ commands:- id: experimentalname: --experimentaldescription: enable experimental features- required: truedefault_value: 'false'- id: no-cachename: --no-cache@@ -3048,7 +3047,6 @@ commands:- id: experimentalname: --experimentaldescription: enable experimental features- required: truedefault_value: 'false'- id: no-cachename: --no-cache@@ -3240,7 +3238,12 @@ commands:If no entries exist in the migration history table, the behavior depends on the diff engine. Under `pg-delta`, the remote database is diffed against an empty shadow database. Under the legacy `migra` engine, the CLI uses `pg_dump` to capture all contents of the remote schemas you have created. Otherwise, this command only diffs schema changes against the remote database, similar to running `db diff --linked`.- When `[experimental.pgdelta] enabled = true`, the migration-file `db pull` workflow uses pg-delta for the shadow diff step; pass `--diff-engine migra` to fall back for a single run. Projects without that setting use migra; pass `--diff-engine pg-delta` to use pg-delta for a single run. Pass `--declarative` to replace the declarative schema tree (`supabase/schemas` by default, configurable with `experimental.pgdelta.declarative_schema_path`) from the selected database instead of creating a migration.+ When `[experimental.pgdelta] enabled = true`, the migration-file `db pull` workflow uses pg-delta for the shadow diff step; pass `--diff-engine migra` to fall back for a single run. Projects without that setting use migra; pass `--diff-engine pg-delta` to use pg-delta for a single run. Pass `--declarative` to export the selected database into the declarative schema tree (`supabase/schemas` by default, configurable with `experimental.pgdelta.declarative_schema_path`) instead of creating a migration.++ On a project without pg-delta enabled, don't use `--declarative`. The export also points `[db.migrations].schema_paths` at the tree it writes. The next local `db diff` applies those files in lexicographic order without resolving dependencies between them, so it fails when a file sorts before an object it depends on. If you've already run it, enable pg-delta, or undo both changes:++ 1. Delete the files the export wrote to the declarative directory (`supabase/schemas/` by default). Files that were already there are left in place.+ 2. Restore `[db.migrations].schema_paths` in `config.toml` to its previous value, or remove it if the export added it.Under the pg-delta engine, your own customizations in Supabase-managed schemas are captured automatically, such as triggers on managed tables like `auth.users` and RLS policies on `storage.objects` and `storage.buckets`. Under the legacy migra engine, the initial pull's `pg_dump` skips managed schemas, but the diff pass that follows appends your trigger and RLS policy changes there to the same migration. If an older CLI reports that `auth` and `storage` were excluded, capture existing customizations there with `--schema auth,storage`.examples:@@ -3264,7 +3267,6 @@ commands:Diffing schemas...No schema changes foundThe remote database is already in sync with your local migrations — nothing to pull.- exit status 1- id: custom-schemasname: Custom schemascode: supabase db pull --schema public,extensions@@ -3276,7 +3278,6 @@ commands:Diffing schemas: public,extensionsNo schema changes foundThe remote database is already in sync with your local migrations — nothing to pull.- exit status 1tags: []links: []usage: supabase db pull [migration name] [flags]@@ -3524,7 +3525,7 @@ commands:Requires the local development stack to be running when diffing against the local database. To diff against a remote or self-hosted database, specify the `--linked` or `--db-url` flag respectively.- Compares schema differences between the target database and a shadow database. Projects with `[experimental.pgdelta] enabled = true` use the bundled pg-delta engine; other projects run the legacy [djrobstep/migra](https://github.com/djrobstep/migra) engine in a container. The shadow database is created by applying migrations in local `supabase/migrations` directory in a separate container. Output is written to stdout by default. For convenience, you can also save the schema diff as a new migration file by passing in `-f` flag.+ Compares schema differences between the target database and a shadow database. Projects with `[experimental.pgdelta] enabled = true` use the bundled pg-delta engine; other projects run the legacy [djrobstep/migra](https://github.com/djrobstep/migra) engine in a container, unless you pass `--use-pg-delta` for a single run. The shadow database is created by applying migrations in local `supabase/migrations` directory in a separate container. Output is written to stdout by default. For convenience, you can also save the schema diff as a new migration file by passing in `-f` flag.By default, all schemas in the target database are diffed. Use the `--schema public,extensions` flag to restrict diffing to a subset of schemas.diff --git a/apps/docs/spec/cli_v1_config.yaml b/apps/docs/spec/cli_v1_config.yamlindex fb2436569d0..b956dbb6ac5 100644--- a/apps/docs/spec/cli_v1_config.yaml+++ b/apps/docs/spec/cli_v1_config.yaml@@ -468,7 +468,7 @@ parameters:default: '[]'description: |An ordered list of schema files, directories, or glob patterns describing your database, relative to the `supabase` directory. For example: `["./schemas/*.sql"]`.- Only the legacy `migra` diff engine uses this setting, where it controls the order in which declarative schema files are applied. The `pg-delta` diff engine (see `experimental.pgdelta.enabled`) ignores it and orders declarative files automatically based on the dependencies between statements.+ Only the legacy `migra` diff engine uses this setting, where it controls the order in which declarative schema files are applied. On that engine, `supabase db pull --declarative` sets it to the declarative schema directory automatically. The `pg-delta` diff engine (see `experimental.pgdelta.enabled`) ignores it and orders declarative files by the dependencies between statements. It warns when the setting lists any paths.links:- name: 'Declarative database schemas'link: 'https://supabase.com/docs/guides/local-development/declarative-database-schemas'@@ -1855,6 +1855,7 @@ parameters:default: './schemas'description: |The directory where the `pg-delta` engine reads and writes declarative schema files. Relative paths resolve from the `supabase` directory.+ CLI versions before 2.115.0 defaulted to `./database`. If that directory still holds schema files, `./schemas` is empty, and this setting is unset, the CLI warns and reads `./schemas` instead. To keep that tree, set `./database` here.Note: This is an experimental feature and may change in future releases.links:- name: 'Declarative database schemas'