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

[avallete]

Summary

The docs-spec generator (apps/cli/scripts/generate-docs-spec.ts, published into supabase/supabase by publish-docs-spec.ts) builds the public db pull reference from apps/cli/docs/supabase/db/pull.md and apps/cli/docs/templates/examples.yaml. Both still described the pre-pg-delta flow, so the next publish would overwrite the hand-edited reference in supabase/supabase#49889 and supabase/supabase#50220 with stale text. This carries the same content into the generator inputs.

examples.yaml, supabase-db-pull:

• Drop the retired "The auth and storage schemas are excluded. Run supabase db pull --schema auth,storage again to diff them." line. The CLI no longer prints it and no longer excludes those schemas from the baseline.
• Replace the migra-era "Setting up initial schema" / "Creating custom roles" progress lines with the current shadow-database output ("Creating shadow database", "Seeding globals from roles.sql", "Diffing schemas"), and show the in-sync message the command prints today instead of the generic --debug hint.
• Point the custom-schemas example at --schema public,extensions, since auth,storage is no longer the motivating case.

pull.md overlay:

• Name split plan files with the _1 / _2 suffixes the migration writer produces (${name}${suffix}, suffix from pg-delta's renderPlanFiles) instead of the older _schema_changes / _after_enum_values unit-name scheme, and mention the -- pg-delta: transaction=false directive on non-transactional units.
• Add a paragraph on which customizations in Supabase-managed schemas the pg-delta engine captures, matching the Supabase policy in pg-delta: user triggers on managed tables (function outside the managed schemas), RLS policies on any auth table, and the storage / realtime policy surfaces.

Deliberately not touched here: the paragraphs #6391 rewrites (engine default, initial-pull behavior, debug bundle path) and the --db-url direct-versus-pooler advice, which the docs PR and this overlay currently disagree on and which needs a CLI-team call. Text only, no behavior change.

Linked issue

Follow-up to #6391 (docs alignment); no separate issue.

• The linked issue is open and carries the open-for-contribution label (or I'm a Supabase maintainer).

Checklist

• The PR title follows Conventional Commits (e.g. fix(cli): …).
• Tests added or updated for the change. Not applicable: docs inputs only. The existing docs-spec unit tests, which validate examples.yaml ids and overlay paths, pass.
• From the repository root, pnpm check:all passes; relevant package tests pass for every touched workspace, and pnpm types:check passes for each touched TypeScript workspace (or workspace declaring it). Run locally: oxfmt --check on the two files and the src/docs/ unit tests in apps/cli. The full check:all is left to CI.

🤖 Generated with Claude Code

https://claude.ai/code/session_0191XKFXEZ8kHsMNWHAaKgE2

[github-actions]

🤖 AI Review

Both independent reviews completed. Four unique findings remain after merging the shared pg_dump finding: three are confirmed and one is refuted. The PR inaccurately attributes managed-schema changes to pg_dump and omits the non-initial --schema limitation; it also leaves pre-existing stale start/reset examples. The alleged missing legacy filename documentation is not a current production issue.

Findings

Severity	Location	Category	Sources	Claim
🟡 MINOR	apps/cli/docs/supabase/db/pull.md:23	documentation-accuracy	claude+codex	The paragraph incorrectly says the initial pg_dump baseline includes managed-schema trigger and RLS changes; those changes are instead appended by the subsequent migra pass.
🟡 MINOR	apps/cli/docs/supabase/db/pull.md:23	documentation-accuracy	claude	The statement that pg-delta automatically captures managed-schema customizations is overbroad for non-initial pulls using --schema, which exclude actions outside the selected schemas.
⚪ NIT	apps/cli/docs/templates/examples.yaml:42	documentation-accuracy	claude	The edited examples file still contains stale start/reset output strings: Creating custom roles supabase/roles.sql... and Seeding data supabase/seed.sql....

Findings outside the diff

• ⚪ NIT apps/cli/docs/templates/examples.yaml:42 — The edited examples file still contains stale start/reset output strings: Creating custom roles supabase/roles.sql... and Seeding data supabase/seed.sql....

Refuted findings (kept for transparency, not posted as review comments)

• apps/cli/docs/supabase/db/pull.md:15 (documentation-completeness): The split-plan documentation should also describe the writer's suffix-less fallback filenames such as _schema_changes.
  Refuted: apps/cli/src/command-internal/pgdelta-engine-runtime.layer.ts:18-19 establishes the next engine as the only production implementation. Its result type requires a string-or-null suffix, and pgdelta-engine.next.layer.ts:88-94 always propagates it. Multi-unit renderer tests verify _1 and _2; the cited pull test bypasses that implementation with an old suffix-less mock. The docs accurately describe current production output.

Stats

Claude findings: 4 · Codex findings: 1 · Confirmed: 3 · Refuted: 1 · Uncertain: 0

---

Models: claude-opus-5 + gpt-5.6-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[github-actions]

🟡 MINOR · documentation-accuracy · source: claude+codex

The paragraph incorrectly says the initial pg_dump baseline includes managed-schema trigger and RLS changes; those changes are instead appended by the subsequent migra pass.

Evidence: apps/cli/docs/supabase/db/pull.md:23 makes the claim, while apps/cli/src/command-internal/db-pull-run.ts:480-484 says migra appends objects pg_dump cannot emit. db-pull-run.ts:508-514 supplies an empty schema list, and pg-dump.env.ts:131-138 consequently excludes INTERNAL_SCHEMAS, including auth, realtime, and storage at lines 20-25.

Suggested fix: State that the initial pg_dump excludes managed schemas and the subsequent migra pass appends supported trigger and RLS changes to the same migration.

[github-actions]

🟡 MINOR · documentation-accuracy · source: claude

The statement that pg-delta automatically captures managed-schema customizations is overbroad for non-initial pulls using --schema, which exclude actions outside the selected schemas.

Evidence: apps/cli/src/command-internal/db-pull-run.ts:599-600 derives the schema filter for non-initial pulls and passes it to pg-delta at line 667. apps/cli/src/commands/db/shared/pgdelta-next-adapter.layer.ts:300-329 adds an exclusion policy for actions outside the selected schemas. apps/cli/docs/templates/examples.yaml:249 demonstrates --schema public,extensions.

Suggested fix: Explain that --schema restricts managed-schema capture on non-initial pulls, while initial pulls currently ignore the schema filter.