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

[avallete]

Summary

Stacked on #6215 (← #6203 ← #6184 ← #6102).

migration squash and db diff --use-pgadmin were the last two shadow-database consumers still provisioning bare cold shadows — every run re-paid the full platform baseline (init schema + the PG15+ realtime/storage/auth one-shot migrate jobs, ~15s) that the shadow-baseline cache already eliminates for db diff/db pull. Both now provision through legacyWithShadowDatabase and warm-restore the cached pg_data tar when eligible.

The shared prologue (connect → prelude → legacySetupDatabase, with the warm/cold/cold-snapshotting branches) is extracted into legacyOpenShadowBaselineSession in shadow-database.ts; legacySetupShadowDatabase and the migrate path delegate to it, and squash calls it directly so its pre-migration auth/storage dumps stay exactly at the baseline seam. Squash keys config-following (its baseline always followed config.toml); pgadmin keys webhooks: "enabled" to share the legacy migra branch's forced-pg_net tars.

Two defects surfaced while wiring this in, both fixed here:

• Cache-key/cluster-state mismatch (correctness): db pull and db diff's native branch hardcoded { webhooks: "enabled" } as the cache-key opts even in pg-delta next mode, where the actual provisioning (legacyMigrateNextShadowDatabase) follows config.toml. On a project with webhooks disabled, a cold next-mode run published a pg_net-less tar under the "enabled" key — which the newly cached pgadmin branch (and the reverse direction) could then silently warm-restore. The key opts now follow the migration mode at all call sites; legacyResolveMigrationsCatalogRef in legacy-pgdelta.cache.ts had the same drift (keyed config-following, provisioned forced-on) and is fixed too. A regression test asserts a next-mode diff and a pgadmin diff on a webhooks-disabled config never share tars (verified failing pre-fix).
• Readiness gate (perf): both call sites gated on legacyWaitForHealthyServices (Docker HEALTHCHECK, first probe at t+10s, ~6.5s pure wait) instead of the legacyWaitForShadowReady connect probe every other cached consumer uses. Swapped, so the warm restore actually lands its win. The now-dead neverHealthy mock knob is deleted; the interrupt/timeout tests model a connect-refusing shadow instead.

Test-helper cleanups ride along: a shared withLegacyShadowCacheEnabled in tests/helpers/legacy-mocks.ts replaces per-file env stash/restore copies, and the squash test uses legacyShadowBaselineCacheDir instead of a hand-built path.

Transcript note: on a warm hit both commands skip the Initialising schema... / Seeding globals from roles.sql... lines, matching the existing warm behavior of db diff/db pull. All dumps, migration-replay lines, and result output are unchanged.

Linked issue

Closes #

• 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.
• pnpm check:all and pnpm test pass for the workspace(s) I touched.

🤖 Generated with Claude Code

[github-actions]

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@d6289e62c2e0685e53de5dd402153eabec34242c

Preview package for commit d6289e6.

[chatgpt-codex-connector]

💡 Codex Review

cli/apps/cli/src/legacy/shared/db-bootstrap/shadow-cache.live.test.ts

Line 50 in d6289e6

describeLive("shadow baseline cache (live Docker)", () => {

Gate the shadow-cache live suite on Docker availability

When SUPABASE_ACCESS_TOKEN is configured on a developer machine or runner without a reachable Docker daemon, describeLive activates this suite and the first container operation fails instead of skipping it. This scenario directly requires Docker, so use describeDockerLive, which performs the required docker info gate.

AGENTS.md reference: apps/cli/AGENTS.md:L524-L526

---

cli/apps/cli/src/legacy/shared/db-bootstrap/health-check.ts

Lines 585 to 588 in d6289e6

	// Same policy as `legacyWaitForHealthyServices` (Go's
	// `NewBackoffPolicy(ctx, timeout)`): a 1-second constant delay, capped at
	// `timeoutSeconds` retries after the initial attempt.
	const schedule = Schedule.max([Schedule.spaced("1 seconds"), Schedule.recurs(timeoutSeconds)]);

Bound shadow readiness by elapsed timeout

When the published port blackholes TCP connections rather than refusing them, each probe can consume its full 2-second connect timeout, while this schedule still permits timeoutSeconds retries with one-second delays. The default 30-second health timeout can therefore take roughly 90 seconds before failing, changing the established shadow Docker behavior for every migrated caller; apply an elapsed-time deadline to the whole retry loop rather than treating the timeout as only a retry count.

AGENTS.md reference: apps/cli/AGENTS.md:L53-L56

---

cli/apps/cli/src/legacy/commands/db/shared/legacy-pgdelta-migrations.write.ts

Line 190 in d6289e6

written.push(w);

Track the current migration before its write can fail

When writeFileString creates the exclusive file but then fails while writing it, such as on a full disk or an interrupted filesystem write, this push is never reached. The error cleanup consequently removes previously completed files but leaves the current partial .sql file in supabase/migrations, where a later command can treat it as a real migration or collide with its version; include the current path in cleanup as soon as creation begins.

---

cli/apps/cli/src/legacy/shared/db-bootstrap/shadow-cache.live.test.ts

Line 64 in d6289e6

process.env.SUPABASE_HOME = supabaseHome;

Restore shadow-cache environment after the live test

When another live test runs later in the same Vitest worker, this direct process.env mutation remains after the scoped temporary directory has been deleted; the test also leaves SUPABASE_SHADOW_CACHE=1 set below. Subsequent tests can therefore unexpectedly enable caching against a nonexistent former home or lose the caller's original environment values. Scope both assignments with the existing withLegacyShadowCacheEnabled helper or restore them in a finalizer.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".