Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

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.mdx
index 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 up
With 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 --linked
This 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.mdx
index 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 = true
Existing 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.yaml
index 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] y
Resetting database...
...
- Declarative schema written to supabase/database
+ Declarative schema written to supabase/schemas
Finished supabase db schema declarative generate.
tags: []
links: []
@@ -2984,7 +2984,6 @@ commands:
- id: experimental
name: --experimental
description: enable experimental features
- required: true
default_value: 'false'
- id: no-cache
name: --no-cache
@@ -3048,7 +3047,6 @@ commands:
- id: experimental
name: --experimental
description: enable experimental features
- required: true
default_value: 'false'
- id: no-cache
name: --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 found
The remote database is already in sync with your local migrations — nothing to pull.
- exit status 1
- id: custom-schemas
name: Custom schemas
code: supabase db pull --schema public,extensions
@@ -3276,7 +3278,6 @@ commands:
Diffing schemas: public,extensions
No schema changes found
The remote database is already in sync with your local migrations — nothing to pull.
- exit status 1
tags: []
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.yaml
index 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'