diff --git a/apps/cli/docs/supabase/db/pull.md b/apps/cli/docs/supabase/db/pull.md index c0b917a4c5..b7ec1db3d8 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, 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 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