From d360c47fa1dac9ff9c11665d5f0df67fbde27984 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 10 Sep 2026 12:21:30 +0000 Subject: [PATCH 1/2] docs(cli): refresh db pull reference examples and overlay for pg-delta 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 Claude-Session: https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2 --- apps/cli/docs/supabase/db/pull.md | 4 +++- apps/cli/docs/templates/examples.yaml | 17 +++++++++-------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/apps/cli/docs/supabase/db/pull.md b/apps/cli/docs/supabase/db/pull.md index c0b917a4c5..6c4d379a1f 100644 --- a/apps/cli/docs/supabase/db/pull.md +++ b/apps/cli/docs/supabase/db/pull.md @@ -12,7 +12,7 @@ If no entries exist in the migration history table, the default diff engine uses Pass `--diff-engine pg-delta` to keep the migration-file `db pull` workflow while using pg-delta for the shadow diff step. On initial pull, pg-delta replaces `pg_dump` and produces the full migration from the shadow diff alone. Pass `--declarative` to switch to the declarative pg-delta export workflow instead. -pg-delta plans are execution-aware: when a plan crosses a transaction boundary — for example `ALTER TYPE ... ADD VALUE` followed by a statement that uses the new enum value, which cannot run in the same transaction — `db pull` writes one ordered migration file per plan unit instead of a single file (for example `_remote_schema_schema_changes.sql` and `_remote_schema_after_enum_values.sql`), each recorded in the migration history. The common case (a single unit) still produces exactly one `_remote_schema.sql` file. +pg-delta plans are execution-aware: when a plan crosses a transaction boundary — for example `ALTER TYPE ... ADD VALUE` followed by a statement that uses the new enum value, which cannot run in the same transaction — `db pull` writes one ordered migration file per plan unit instead of a single file (for example `_remote_schema_1.sql` and `_remote_schema_2.sql`), each recorded in the migration history. Units whose statements cannot run inside a transaction start with a `-- pg-delta: transaction=false` directive that the CLI apply paths honor. The common case (a single unit) still produces exactly one `_remote_schema.sql` file. By default the emitted SQL is formatted with the same settings the declarative export uses (uppercase keywords, wrapped at a max width of 180, indented and column-aligned). Configure overrides with `[experimental.pgdelta] format_options` in `config.toml`, or set `format_options = "null"` to opt out and emit raw, unformatted statements. @@ -20,6 +20,8 @@ When `[experimental.pgdelta] enabled = true` (the default for projects created b When pulling from a remote database with `--db-url`, prefer a direct connection (`db..supabase.co:5432`) over the connection pooler so pg-delta can introspect the full catalog reliably. +Under the pg-delta engine, your own customizations in Supabase-managed schemas are captured automatically: triggers on managed tables whose function lives outside the managed schemas (for example a trigger on `auth.users` calling a function in `public`), RLS policies on any `auth` table, and RLS policies on `storage.objects`, `storage.buckets`, and `realtime.messages`. Other objects you create inside managed schemas, such as your own functions or indexes, are not diffed. Under the legacy migra engine, trigger and RLS policy changes in managed schemas are diffed, and the initial `pg_dump` baseline includes them too. + ## Debugging empty pg-delta pulls If `db pull --diff-engine pg-delta` reports `No schema changes found` but you expect schema output, set `PGDELTA_DEBUG=1` before running the command. Unlike `--debug`, this keeps SSL enabled for remote Supabase connections. diff --git a/apps/cli/docs/templates/examples.yaml b/apps/cli/docs/templates/examples.yaml index bc451edb14..b11b130a5f 100644 --- a/apps/cli/docs/templates/examples.yaml +++ b/apps/cli/docs/templates/examples.yaml @@ -232,28 +232,29 @@ supabase-db-pull: Update remote migration history table? [Y/n] Repaired migration history: [20240414044403] => applied Finished supabase db pull. - The auth and storage schemas are excluded. Run supabase db pull --schema auth,storage again to diff them. - id: local-studio name: Local studio code: supabase db pull --local response: | Connecting to local database... - Setting up initial schema.... - Creating custom roles supabase/roles.sql... + Creating shadow database... + Seeding globals from roles.sql... Applying migration 20240414044403_remote_schema.sql... + Diffing schemas... No schema changes found - The auth and storage schemas are excluded. Run supabase db pull --schema auth,storage again to diff them. + 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 auth,storage + code: supabase db pull --schema public,extensions response: | Connecting to remote database... - Setting up initial schema.... - Creating custom roles supabase/roles.sql... + Creating shadow database... + Seeding globals from roles.sql... Applying migration 20240414044403_remote_schema.sql... + Diffing schemas: public,extensions No schema changes found - Try rerunning the command with --debug to troubleshoot the error. + The remote database is already in sync with your local migrations — nothing to pull. exit status 1 supabase-db-push: - id: basic-usage From 5d5278ce8cde174ed52bc6991bd1c271fd158d69 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 14 Sep 2026 11:01:55 +0000 Subject: [PATCH 2/2] docs(cli): correct managed-schema capture details in db pull overlay 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 Claude-Session: https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2 --- apps/cli/docs/supabase/db/pull.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/cli/docs/supabase/db/pull.md b/apps/cli/docs/supabase/db/pull.md index 6c4d379a1f..b7ec1db3d8 100644 --- a/apps/cli/docs/supabase/db/pull.md +++ b/apps/cli/docs/supabase/db/pull.md @@ -20,7 +20,7 @@ When `[experimental.pgdelta] enabled = true` (the default for projects created b When pulling from a remote database with `--db-url`, prefer a direct connection (`db..supabase.co:5432`) over the connection pooler so pg-delta can introspect the full catalog reliably. -Under the pg-delta engine, your own customizations in Supabase-managed schemas are captured automatically: triggers on managed tables whose function lives outside the managed schemas (for example a trigger on `auth.users` calling a function in `public`), RLS policies on any `auth` table, and RLS policies on `storage.objects`, `storage.buckets`, and `realtime.messages`. Other objects you create inside managed schemas, such as your own functions or indexes, are not diffed. Under the legacy migra engine, trigger and RLS policy changes in managed schemas are diffed, and the initial `pg_dump` baseline includes them too. +Under the pg-delta engine, a plain `db pull` captures your own customizations in Supabase-managed schemas: triggers on managed tables whose function lives outside the managed schemas (for example a trigger on `auth.users` calling a function in `public`), RLS policies on any `auth` table, and RLS policies on `storage.objects`, `storage.buckets`, and `realtime.messages`. Other objects you create inside managed schemas, such as your own functions or indexes, are not diffed. On later pulls, `--schema` restricts the diff to the listed schemas, so a customization in `auth` is only captured when `auth` is listed or `--schema` is omitted; the initial pull ignores `--schema`. Under the legacy migra engine, the initial pull's `pg_dump` skips the managed schemas, and the migra diff pass that follows appends your trigger and RLS policy changes there to the same migration file. ## Debugging empty pg-delta pulls