docs(cli): refresh db pull reference examples and overlay for pg-delta

apps/cli/docs/supabase/db/pull.md

@@ -12,14 +12,16 @@ 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 `<ts>_remote_schema_schema_changes.sql` and `<ts+1s>_remote_schema_after_enum_values.sql`), each recorded in the migration history. The common case (a single unit) still produces exactly one `<ts>_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 `<ts>_remote_schema_1.sql` and `<ts+1s>_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 `<ts>_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.
 
 When `[experimental.pgdelta] enabled = true` (the default for projects created by a recent `supabase init`), the migration-file `db pull` workflow uses pg-delta for the shadow diff step by default; it does not switch to declarative output. Existing projects without the section are unaffected and keep using migra. To fall back to the legacy migra engine, set `enabled = false` under `[experimental.pgdelta]`, or pass `--diff-engine migra` for a single run.
 
 When pulling from a remote database with `--db-url`, prefer a direct connection (`db.<project-ref>.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.

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