Skip to content

perf(cli): reuse shadow baseline cache in migration squash and pgadmin diff #6220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
avallete wants to merge 6 commits into from
Open

perf(cli): reuse shadow baseline cache in migration squash and pgadmin diff #6220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8492f33
fix(stack): settle managed identity recovery safely (#6214)
jgoux Aug 15, 2026
23a5ba1
fix(cli): fail test db when no tests ran (CLI-2194) (#6210)
7ttp Aug 15, 2026
d408ee4
fix(cli): stop buffering piped output (#6212)
7ttp Aug 15, 2026
25ae5be
refactor(stack): simplify managed identity policy (#6216)
jgoux Aug 16, 2026
6c16b38
perf(cli): reuse shadow baseline cache in migration squash and pgadmi…
avallete Aug 16, 2026
d6289e6
Merge branch 'develop' into avallete/shadow-cache-squash-pgadmin
avallete Aug 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions apps/cli/docs/go-cli-divergences.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,12 @@ These commands exist in the TS CLI today but have no direct top-level equivalent
`supabase start`, `db start`, `--from-backup`, and shadow containers (the last is why the
shadow baseline cache's cold export can stop/start in ~1s). Timing is not part of the
Go-parity surface (ADR 0016).
- `test db` (and its `db test` alias) exits `1` when `pg_prove` ran no tests (CLI-2194, #6206).
`pg_prove` prints `Result: NOTESTS` and still exits `0` for an empty run, and Go returns that
code verbatim (`internal/db/test/test.go` → `DockerRunOnceWithConfig`), so a typo'd path, an
empty tests directory, or a bind the daemon resolved against a different filesystem than the
CLI's (a sibling-container Docker socket) all reported a green build that ran zero tests. The
TAP stream on stdout is unchanged; the diagnostic goes to stderr like every other failure.
- `functions serve` per-function env discovery (CLI-2184, #6179): without `--env-file`, each
`supabase/functions/<function-name>/.env` overrides matching values from the shared
`supabase/functions/.env` for that Function only; an explicit `--env-file` remains the
Expand Down
39 changes: 21 additions & 18 deletions apps/cli/src/legacy/commands/db/diff/SIDE_EFFECTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,17 +36,17 @@ it, and JSON `null` disables formatting without disabling safe compaction.

## Files Written

| Path | Format | When |
| --------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<workdir>/supabase/migrations/<YYYYMMDDHHMMSS>_<name>.sql` | SQL | non-empty `--file` diff; bundled pg-delta may emit ordered transaction-aware files, while pgAdmin always emits one |
| `<path>` (from `--output` / `-o`) | SQL | explicit `--from/--to` mode with `--output`; flattened review representation, not a portable apply script |
| `<workdir>/supabase/.temp/pgdelta/*.json` | JSON | legacy opt-out's explicit migrations catalog |
| `<workdir>/supabase/.temp/pgdelta/pgdelta-target-ca.crt` | PEM | legacy opt-out, for a Supabase TLS target |
| `<workdir>/supabase/.temp/pgdelta/v2/debug/<id>/*.json` | JSON | bundled engine with `PGDELTA_DEBUG` |
| `~/.supabase/cache/shadow-baseline/shadow-baseline-<key>.tar` | tar | cache-enabled (default) COLD shadow provision creates the current key's snapshot (native diff targets + the explicit `--from/--to migrations` catalog miss; never `--use-pgadmin`/`--use-pg-schema`); a warm hit `touch`es its mtime (LRU); every cache-eligible acquire may delete other keys under LRU keep-8 + 14-day mtime TTL — ~90MB (`SUPABASE_HOME` overrides the root) |
| `~/.supabase/cache/shadow-baseline/shadow-baseline-<key>.tar.<pid>.partial` | tar | during a cold export — the in-flight temp file, `rename`d into the tar above on success and removed on failure; only a crash/SIGKILL leaves it behind, and later cold exports / warm hits sweep leftovers older than an hour |
| `~/.supabase/<workdir-hash>/linked-project.json` | JSON | `--linked` (post-run cache) |
| `~/.supabase/telemetry.json` | JSON | every invocation (post-run) |
| Path | Format | When |
| --------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<workdir>/supabase/migrations/<YYYYMMDDHHMMSS>_<name>.sql` | SQL | non-empty `--file` diff; bundled pg-delta may emit ordered transaction-aware files, while pgAdmin always emits one |
| `<path>` (from `--output` / `-o`) | SQL | explicit `--from/--to` mode with `--output`; flattened review representation, not a portable apply script |
| `<workdir>/supabase/.temp/pgdelta/*.json` | JSON | legacy opt-out's explicit migrations catalog |
| `<workdir>/supabase/.temp/pgdelta/pgdelta-target-ca.crt` | PEM | legacy opt-out, for a Supabase TLS target |
| `<workdir>/supabase/.temp/pgdelta/v2/debug/<id>/*.json` | JSON | bundled engine with `PGDELTA_DEBUG` |
| `~/.supabase/cache/shadow-baseline/shadow-baseline-<key>.tar` | tar | cache-enabled (default) COLD shadow provision creates the current key's snapshot (native diff targets, `--use-pgadmin`, and the explicit `--from/--to migrations` catalog miss; never `--use-pg-schema`, which delegates to the bundled Go binary); a warm hit `touch`es its mtime (LRU); every cache-eligible acquire may delete other keys under LRU keep-8 + 14-day mtime TTL — ~90MB (`SUPABASE_HOME` overrides the root) |
| `~/.supabase/cache/shadow-baseline/shadow-baseline-<key>.tar.<pid>.partial` | tar | during a cold export — the in-flight temp file, `rename`d into the tar above on success and removed on failure; only a crash/SIGKILL leaves it behind, and later cold exports / warm hits sweep leftovers older than an hour |
| `~/.supabase/<workdir-hash>/linked-project.json` | JSON | `--linked` (post-run cache) |
| `~/.supabase/telemetry.json` | JSON | every invocation (post-run) |

## Docker

Expand All @@ -62,9 +62,10 @@ it, and JSON `null` disables formatting without disabling safe compaction.
called with `targetLocal: false`/`usePgDelta: false` to skip the declarative-schema-override
branch — not a second, `__catalog`-specific shadow, and not a shared `mode: "diff"` parameter
(that seam-era concept no longer exists). `--use-pgadmin` provisions its OWN shadow via a
narrower composition — `legacyCreateShadowDatabase` -> health-wait -> `legacyMigrateShadowDatabase`
directly (`diff.handler.ts`'s pgadmin branch) — with no declarative-schema-override branch and
no `targetUrlOverride`.
narrower composition — `legacyWithShadowDatabase` (the same cached acquire/release seam as the
native branch) -> `legacyWaitForShadowReady` (the same connect probe, not the Docker
HEALTHCHECK) -> `legacyMigrateShadowDatabase` directly (`diff.handler.ts`'s pgadmin branch) —
with no declarative-schema-override branch and no `targetUrlOverride`.
- `supabase/migra` container — the migra OOM bash fallback only.
- **Differ container** (`--use-pgadmin`, CLI-1968) — `supabase/pgadmin-schema-diff:cli-0.0.5`
(`dockerfileServiceImage("differ")`). One `docker run --rm` when no `--schema` is given; one
Expand Down Expand Up @@ -107,8 +108,9 @@ of this command's own target resolve, ahead of the differ container.
| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | overrides the differ's / shadow's image registry (shell **or** project `.env`, applied for the run via `legacyApplyProjectEnv`, matching `db push`/`db pull`/`db dump`) | no |

`SUPABASE_DB_SHADOW_PORT`/`SUPABASE_NETWORK_ID`/`--network-id`/`SUPABASE_PROJECT_ID`/
`SUPABASE_DB_HEALTH_TIMEOUT` all apply to `--use-pgadmin` too — its shadow is provisioned
through the same primitives.
`SUPABASE_DB_HEALTH_TIMEOUT`/`SUPABASE_HOME`/`SUPABASE_SHADOW_CACHE`/`SUPABASE_SHADOW_DEBUG` all
apply to `--use-pgadmin` too — its shadow is provisioned through the same primitives, including
the same cached acquire.

`SUPABASE_EXPERIMENTAL_PG_DELTA` is **read, no effect** on the pgadmin path: the pg-delta
engine-selection lookup (`legacyShouldUsePgDelta`) runs unconditionally, before the
Expand Down Expand Up @@ -245,8 +247,9 @@ Container lifecycle is identical to the uncached path except a cold run drops `-
on release). A cache anomaly never fails the command — a warm-path anomaly cold-provisions instead,
a cold export failure only warns and leaves the run uncached (one exception: a shadow that
fails to come back up after the snapshot fails the run rather than reporting a false success). See `shared/db-bootstrap/
shadow-cache.ts`'s doc comment for the mechanics. `--use-pgadmin` is NOT cached — its shadow keeps
the plain create/remove lifecycle.
shadow-cache.ts`'s doc comment for the mechanics. `--use-pgadmin` shares this cache and these
snapshots: its shadow runs the same forced-on Webhooks/`pg_net` baseline
(`legacyMigrateShadowDatabase`), so it keys to the same tars as the native branch.

### `--use-pgadmin` parity quirks and deliberate divergence (CLI-1968)

Expand Down
Loading
Loading