## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
Docs update.
## What is the current behavior?
Linear:
[CLI-1618](https://linear.app/supabase/issue/CLI-1618/update-cli-workflow-docs-for-pg-delta-default-diffing)
Four docs pages lag the shipped CLI behavior now that `pg-delta` is the
default diff engine for projects created by a recent `supabase init`:
- **CLI workflows** claims `db diff` compares `supabase/schemas/`
against migrations. Under `pg-delta`, declarative files are never the
`db diff` baseline (and `[db.migrations].schema_paths` no longer changes
it) — the declarative flow goes through `supabase db schema declarative
sync`. The cleanup guidance describes `migra`-era output.
- **Declarative database schemas** teaches the old `db diff -f` +
`schema_paths` flow throughout, and its known-caveats list is the
`migra` issue list.
- **Managing environments** still presents `--use-migra` as an
"experimental flag" for a "more concise" diff — inverted now.
- **Backup and restore (migrating within Supabase)** and the CLI
workflows guide both steer users to `db diff`/`db pull` with `--schema
auth,storage`. Under `pg-delta`, `--schema` layers an extra exclude
policy on top of the Supabase profile: it can only narrow a diff, never
re-include managed schemas, and managed-schema selections can even fail
closed (e.g. `--schema auth` when a trigger function lives in `public`).
Unfiltered diffs are the supported path.
## What is the new behavior?
All claims verified against the CLI source at current `develop` —
including supabase/cli#6300, which upgraded the engine to
`@supabase/pg-delta` 1.0.0-alpha.46 — against the pinned pg-delta
package source (profile rules, format defaults, coverage doc), and
against a live dogfood run of the documented workflows on `develop`
`38f31b4` (two OSS corpus projects, warm shadow cache).
- **`cli-workflows.mdx`**: adds a "Which diff engine you're on" note
(`pg-delta` for new `supabase init` projects, `migra` for existing ones
until they opt in by adding `[experimental.pgdelta] enabled = true`;
per-run fallbacks `--use-migra` on `db diff` / `--diff-engine migra` on
`db pull`); corrects `db pull` and `db diff` mechanics (shadow built
from migrations vs. live database; the baseline history record is
offered, not unconditional); switches the declarative flow to `supabase
db schema declarative sync`; reworks the cleanup section around pg-delta
output (uppercase keywords at max width 180, `format_options`, per-unit
migration files with numeric segment suffixes, the `-- pg-delta:
transaction=false` directive on genuinely non-transactional files,
engine-neutral grant/revoke review guidance, coverage warnings +
`--strict-coverage`); documents what pg-delta captures in managed
schemas (user triggers, RLS policies on `auth` tables and on
`storage.objects`/`storage.buckets`/`realtime.messages`) versus what it
doesn't; adds key-command rows for the declarative commands and
troubleshooting entries (`db pull` non-zero exit when in sync, the
`schema_paths` warning, `PGDELTA_DEBUG=1` bundles under
`supabase/.temp/pgdelta/v2/debug/`).
- **`declarative-database-schemas.mdx`**: swaps `db diff -f` for `db
schema declarative sync -f` throughout; replaces
lexicographic/`schema_paths` ordering guidance with automatic dependency
ordering and the `generate` export layout (`_cluster/`, reserved
`_custom/`); bootstraps from production via `db schema declarative
generate --linked` (explicit target + `--overwrite` in scripts) and
refreshes via `db pull --declarative`; rewrites known caveats for
pg-delta (DML including storage buckets, untracked object kinds + the
`_custom/` escape hatch, managed schemas, extension-managed objects, and
the two gates when adopting an existing schema tree:
`[experimental.webhooks]` for `pg_net` migrations and declaring the
tree's extensions) keeping the `migra` workflow and issue list under a
legacy section for projects that haven't enabled it.
- **`managing-environments.mdx`**: frames the verbose grant sample as
legacy-engine output, notes that generated migrations can include grant
statements on any engine, describes `--use-migra` as a single-run
fallback, and adds a `db diff --strict-coverage` CI step.
- **`backup-restore.mdx`**: replaces `db diff --linked --schema
auth,storage` with a plain `db diff --linked` on `pg-delta` (keeping the
`--schema auth,storage` form for the legacy engine) and explains what
the engine includes (user triggers on managed tables, user RLS policies
on `auth`, `storage.objects`/`storage.buckets`/`realtime.messages`) and
what must be recreated manually.
- **New `diff-engines.mdx` page** (from #49889): the single home for how
the engine is selected, a behavior matrix for `pg-delta` versus `migra`,
the per-command fallback flags, a procedure for switching an existing
project (the first `db pull` after enabling may write a catch-up
migration), and how to go back with `enabled = false`. Registered in
navigation. A shared `diff_engine_check` partial replaces the inline
engine parentheticals across seven pages, and a
`managed_schemas_diff_capture` partial carries the managed-schema
capture rules.
- **CLI reference (`cli_v1_commands.yaml`, `cli_v1_config.yaml`)**: `db
pull`, `db schema declarative sync`/`generate` flags and descriptions,
`experimental.pgdelta.*` and `db.migrations.schema_paths` config keys,
and the `db diff` description updated to describe both engines. Note
that `cli_v1_commands.yaml` is generated from the CLI repo;
[supabase/cli#6557](https://github.com/supabase/cli/pull/6557) carries
the matching `db pull` example and overlay text so the next publish
keeps it.
- **`examples/prompts/declarative-database-schema.md`**: rewritten for
the `db schema declarative sync` flow, with the `[experimental.pgdelta]`
prerequisite.
## Additional context
The first draft was written against pg-delta 1.0.0-alpha.42.
supabase/cli#6300 (engine upgrade to alpha.46) then changed two
documented behaviors, both reflected here: generated SQL now defaults to
uppercase pretty-printed keywords, and user RLS policies on
`storage.objects`/`storage.buckets`/`realtime.messages` are included via
the engine's `SUPABASE_USER_POLICY_SURFACES` allowlist. A follow-up
dogfood run on `develop` `38f31b4` then falsified three more claims
(pg-delta emits no grant noise, `_schema_changes`/`_after_enum_values`
multi-file names, directive on every split file), all corrected in the
last commit.
**Update (Sep 14 to 17):**
[#49889](https://github.com/supabase/supabase/pull/49889) and
[#50220](https://github.com/supabase/supabase/pull/50220) were merged
into this branch, so this PR now carries the full stack. #50220
corrected the `schema_paths` warning wording (the CLI warns only when
the setting lists paths), added `auth` RLS policies to the
managed-schema partial, and described the migra initial pull accurately
(the `pg_dump` skips managed schemas and the migra diff pass that
follows appends the trigger and policy changes). It also reframed
`pg-delta` as the default for every project ahead of supabase/cli#6391.
That plan changed: no breaking default flip before Select, so
[#50332](https://github.com/supabase/supabase/pull/50332) restores the
opt-in framing (`pg-delta` requires `[experimental.pgdelta] enabled =
true`, which `supabase init` writes for new projects) and also resolves
the four CodeRabbit findings from the latest review round.
Two claims are pending confirmation from the owning teams: that
branching runs every migration in a transaction and ignores the `--
pg-delta: transaction=false` directive, and the `--db-url`
pooler-versus-direct connection advice, which currently disagrees with
the CLI's own `db pull` docs.
Stale spots found in the CLI repo's own docs while verifying (out of
scope here, worth follow-ups): four `SIDE_EFFECTS.md` files still claim
lowercase output, `docs/supabase/db/diff.md` still lists `migra`-era
"known failure cases" that alpha.46 fully models, the `supabase init`
template's commented `format_options` example shows `maxWidth: 80`
against an actual default of 180, and the CLI upgrade recipe appends
`--experimental` even when the config already enables pg-delta.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01SUuaVmXLRbV6tZjzhka3cp
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified `pg-delta` and legacy `migra` behavior, configuration, and
switching guidance.
* Expanded declarative schema workflows, including synchronization,
migration generation, baselines, deployment, and legacy-engine support.
* Documented managed schemas, permissions, extensions, transaction
handling, dependency ordering, and troubleshooting.
* Added guidance for strict coverage checks, output directories,
non-interactive workflows, and declarative pull modes.
* Added a dedicated diff engines guide and updated CLI navigation,
backup and restore, branching, deployment, and CI documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Wen Bo Xie <wenbox323@gmail.com>
## What kind of change does this PR introduce?
Docs update.
## What is the new behavior?
The branching docs now state consistently that every branch, preview or
persistent, is created as a clone of the base project, starting with
that project's schema, Edge Functions, and configuration. Data and
storage objects are not cloned by default.
## Additional context
This documents new branch-creation behavior. Two automated reviewers
flagged the clone wording and argued for a migration-replay description;
that reflects the previous implementation, so their findings don't apply
here and the clone framing stands.
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## Problem
The Docs E2E link checker found broken links throughout docs, starting
with `phone-login.mdx` pointing to `/docs/guides/cli/config` (404).
Old links like `/docs/guides/cli/config` still work on the live site
because `supabase.com` has redirects set up for them, but these links
break on the docs preview site, which is what the E2E check tests
against. These issues look clean on the live site, and I didn't catch
them in my first pass because I was testing production instead of the
preview.
The E2E check only tests the ~20 pages a given PR happens to touch, so
fixing the pages it flagged kept exposing more of the same problem one
page at a time as each fix pulled in a new file. To stop chasing this
incrementally, I cross-referenced every `/docs/guides/*` and
`/docs/reference/*` redirect source in `apps/www/lib/redirects.js`
against actual usage across all of `apps/docs`, and verified each
candidate against the live preview.
## Solution
Rather than updating the Docs E2E link checker, this PR resolves the
links. **Why:** we own these docs, so keeping the links clean without
redirects is keeping the house maintained. See [Broken Window
Theory](https://blog.codinghorror.com/the-broken-window-theory/).
Updated every link still using an old path to point straight at the
current page instead of relying on a redirect. This covers old links
like:
- `/docs/guides/cli/config` →
`/docs/guides/local-development/cli/config`
- `/docs/guides/cli/getting-started` →
`/docs/guides/local-development/cli/getting-started`
- `/docs/guides/cli/local-development` →
`/docs/guides/local-development/database-migrations`
- `/docs/guides/cli/managing-environments` →
`/docs/guides/deployment/managing-environments`
- `/docs/guides/cli/seeding-your-database` →
`/docs/guides/local-development/seeding-your-database`
- bare `/docs/guides/cli` → `/docs/guides/local-development`
- `/docs/guides/platform/compute-add-ons` →
`/docs/guides/platform/compute-and-disk`
- `/docs/guides/platform/shared-responsibility-model` →
`/docs/guides/deployment/shared-responsibility-model`
- `/docs/guides/database` → `/docs/guides/database/overview`
- `/docs/reference/javascript`, `/docs/reference/dart`,
`/docs/reference/kotlin`, `/docs/reference/python`,
`/docs/reference/csharp` → their `/introduction` pages (the redirect's
own destination, `/start`, turned out to be dead even on production — a
separate bug in `redirects.js` I didn't touch here)
- and about 35 more of the same pattern, listed in the commit messages
Also fixed a handful of dead heading anchors found along the way (links
that resolve to the right page but point at a `#section` that got
renamed or moved), including the original `#bigquery` anchor and a few
in `connecting-to-postgres.mdx` where content moved to its own dedicated
page.
Left alone on purpose:
- `content/guides/cli.mdx` — this page has no route in the docs app at
all (no `app/guides/cli/` directory), so it 404s even in production
before the `www` redirect ever fires. Fixing its internal link wouldn't
change that; it needs an actual routing/content decision, not a link
fix.
- A few candidates that already resolve fine as-is (`pg_partman`, bare
`/docs/reference/api`, bare `/docs/reference/cli`) — confirmed via curl,
left untouched.
## Manual testing
1. Confirmed every new link target actually exists by checking the
destination file/page and matching heading anchors.
2. Cross-referenced every `/docs/guides/*` and `/docs/reference/*`
redirect source in `apps/www/lib/redirects.js` against real usage in
`apps/docs`, and curl-verified each old path (404) and new path (200)
against the live PR preview before fixing it.
3. Ran the Docs E2E link checker locally against changed pages.
4. Spot-checked the original broken link from CI
(`/docs/guides/cli/config`) to confirm it now points to a working page.
This PR migrates the whole monorepo to use Tailwind v4:
- Removed `@tailwindcss/container-queries` plugin since it's included by
default in v4,
- Bump all instances of Tailwind to v4. Made minimal changes to the
shared config to remove non-supported features (`alpha` mentions),
- Migrate all apps to be compatible with v4 configs,
- Fix the `typography.css` import in 3 apps,
- Add missing rules which were included by default in v3,
- Run `pnpm dlx @tailwindcss/upgrade` on all apps, which renames a lot
of classes
- Rename all misnamed classes according to
https://tailwindcss.com/docs/upgrade-guide#renamed-utilities in all
apps.
---------
Co-authored-by: Jordi Enric <jordi.err@gmail.com>
## What kind of change does this PR introduce?
Docs update and UI copy improvement.
## What is the current behavior?
The GitHub integration working directory helper uses an inline tooltip
for examples. In the form layout, the tooltip alignment and inline code
wrapping can make the helper harder to scan.
The integration settings pages also mix markdown-rendered copy with JSX
copy, duplicate the integration cover image helper, and use slightly
different heading, spacing, and button copy patterns across GitHub,
Vercel, and AWS PrivateLink.
## What is the new behavior?
The GitHub working directory field now keeps the helper copy concise and
links to a dedicated docs section with examples for repository root and
nested `supabase/` directories.
The integration settings sections now use a more consistent JSX
structure and copy treatment across GitHub, Vercel, and AWS PrivateLink,
including shared cover imagery and matching explanatory section
hierarchy.
| Before | After |
| --- | --- |
| <img width="1838" height="696" alt="CleanShot 2026-04-24 at 14 35
32@2x"
src="https://github.com/user-attachments/assets/f9843018-fbf5-4c18-a0c3-1842b665f3fd"
/> | <img width="1842" height="700" alt="CleanShot 2026-04-24 at 14 30
21@2x-64E8726E-0B89-4C5A-8A47-CE1AA24F3D1A"
src="https://github.com/user-attachments/assets/bb017464-2b43-4dfe-94b8-a586aedea318"
/> |
| <img width="1884" height="1432" alt="CleanShot 2026-04-24 at 14 40
19@2x"
src="https://github.com/user-attachments/assets/b34e4573-cd7c-4588-83a0-0e1941019552"
/> | <img width="1844" height="1424" alt="CleanShot 2026-04-24 at 14 39
02@2x"
src="https://github.com/user-attachments/assets/4f82b01c-cb27-4f01-b2da-76b7f6e298a5"
/> |
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Clarified GitHub integration setup: provide a Working directory value,
how to compute it from the repo root (including "." for root), examples,
and updated “initialize” spelling.
* **Refactor**
* Simplified integration form descriptions (tooltips → inline text +
Learn more link).
* Reworked GitHub and Vercel integration content to use consistent
headings, layout, and shared image handling.
* Reorganized integration settings rendering for clearer UI states.
* **Style**
* Minor copy, casing, and button text/spacing adjustments.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## I have read the
[CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md)
file.
YES
## What kind of change does this PR introduce?
New Go landing page for the upcoming Bolt webinar. This is where we will
direct customers who want to learn more to go to request a meeting.
---------
Co-authored-by: Alan Daniel <stylesshjs@gmail.com>
* fix: rewrite relative URLs when syncing to GitHub discussion
Relative URLs back to supabse.com won't work in GitHub discussions, so
rewrite them back to absolute URLs starting with https://supabase.com
* fix: replace all supabase urls with relative urls
* chore: add linting for relative urls
* chore: bump linter version
* Prettier
---------
Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>
