feat(cli): cache the shadow database baseline as a PGDATA snapshot (CLI-2191)

apps/cli-go/internal/db/declarative/declarative_test.go

@@ -45,7 +45,7 @@ func TestWriteDeclarativeSchemas(t *testing.T) {
 
 	cfg, err := afero.ReadFile(fsys, utils.ConfigPath)
 	require.NoError(t, err)
-	assert.Contains(t, string(cfg), `"database"`)
+	assert.Contains(t, string(cfg), `"schemas"`)
 }
 
 func TestWriteDeclarativeSchemasSkipsConfigUpdateWhenPgDeltaEnabled(t *testing.T) {

apps/cli-go/internal/utils/misc.go

@@ -99,7 +99,7 @@ var (
 	CurrBranchPath       = filepath.Join(SupabaseDirPath, ".branches", "_current_branch")
 	// DeclarativeDir is the canonical location for pg-delta declarative schema
 	// files generated or synced by `supabase db schema declarative` commands.
-	DeclarativeDir        = filepath.Join(SupabaseDirPath, "database")
+	DeclarativeDir        = filepath.Join(SupabaseDirPath, "schemas")
 	ClusterDir            = filepath.Join(SupabaseDirPath, "cluster")
 	SchemasDir            = filepath.Join(SupabaseDirPath, "schemas")
 	MigrationsDir         = filepath.Join(SupabaseDirPath, "migrations")

apps/cli-go/pkg/config/templates/config.toml

@@ -409,6 +409,6 @@ s3_secret_key = "env(S3_SECRET_KEY)"
 [experimental.pgdelta]
 enabled = {{ .Experimental.PgDeltaInitEnabled }}
 # Directory under `supabase/` where declarative files are written.
-# declarative_schema_path = "./database"
+# declarative_schema_path = "./schemas"
 # JSON string passed through to pg-delta SQL formatting.
 # format_options = "{\"keywordCase\":\"upper\",\"indent\":2,\"maxWidth\":80,\"commaStyle\":\"trailing\"}"

apps/cli/AGENTS.md

@@ -522,7 +522,8 @@ Live tests are black-box CLI subprocess tests — like `*.e2e.test.ts`, but run
 - **Where they run:** authored in this repo, but executed by the [`supabase/cli-e2e-ci`](https://github.com/supabase/cli-e2e-ci) harness, which builds this CLI, brings up a full supabox stack (and has a real Docker daemon, since that's how supabox itself runs), and invokes the `live` Vitest project (`nx run-many -t test:live`). They never run as part of the default unit/integration/e2e loop, and locally they no-op unless the live environment is configured (see below) — there is no need to stand up supabox yourself to develop other code.
 - **Add one whenever you add or change a command whose correctness genuinely depends on a real backend** — a new Management API command, or a change to `start`/`stop`/`status`'s real Docker interaction. Colocate it with the command, same as `*.e2e.test.ts`: `src/legacy/commands/<command>/[<subcommand>/]<subcommand>.live.test.ts`.
 - **Gating:** every live suite must be wrapped in one of `tests/helpers/live.ts`'s `describe.skipIf` gates so the file is inert (skipped, not failed) outside the cli-e2e-ci runner:
-  - `describeLive` — runs whenever `SUPABASE_ACCESS_TOKEN` is set (the live env is configured at all). Reuse this even for commands that don't call the Management API themselves (e.g. `stop`/`status`) — it doubles as the "we're in the full cli-e2e-ci runner, which also has a real Docker daemon" signal, and there is no dedicated Docker-availability gate today.
+  - `describeLive` — runs whenever `SUPABASE_ACCESS_TOKEN` is set (the live env is configured at all). Reuse this even for commands that don't call the Management API themselves (e.g. `stop`/`status`) — it doubles as the "we're in the full cli-e2e-ci runner, which also has a real Docker daemon" signal.
+  - `describeDockerLive` — the configured-live gate composed with a `docker info` probe; use for local-stack suites whose scenarios additionally need a reachable Docker daemon at collection time. It never runs on a machine that merely exposes Docker — `SUPABASE_ACCESS_TOKEN` must still be set, so the file stays inert outside the cli-e2e-ci runner like every other live suite.
   - `describeLiveProject` — additionally requires a provisioned project (`SUPABASE_LIVE_PROJECT_REF`); use for project-scoped Management API commands (branches, functions, project-scoped db).
   - `describeLiveDataPlane` — additionally requires the project's own Postgres instance to be `ACTIVE_HEALTHY`; use for commands that talk to the project's data plane (migration, db, storage).
 - **Invocation:** use `runSupabaseLive(args, options?)` (wraps `runSupabase` with the `legacy` entrypoint and the live profile/timeout defaults) rather than calling `runSupabase` directly, so every live test picks up the same environment plumbing.

apps/cli/docs/go-cli-divergences.md

@@ -20,6 +20,14 @@ These commands exist in the TS CLI today but have no direct top-level equivalent
 
 ## Flag divergences from the Go reference
 
+- `db diff`, `db pull`, and `db schema declarative generate`/`sync` have a TS-only
+  `--strict-coverage` flag (no Go equivalent). It applies only when the bundled
+  pg-delta next engine is active (the default): coverage gaps that the engine
+  reports — statements it skipped or objects it could not represent — normally
+  surface as warnings, and `--strict-coverage` promotes them to hard failures.
+  Under the `SUPABASE_USE_PG_DELTA_NEXT=false` legacy opt-out the flag is
+  accepted but has no effect, since the legacy edge-runtime engine does not
+  emit coverage diagnostics. Default behavior (omitted flag) matches Go.
 - `db push` has a TS-only `--skip-vault` flag. It applies migrations without
   resolving or updating `[db.vault]` secrets; default behavior still matches Go.
 - Every legacy command that resolves a linked project ref for its own database
@@ -71,6 +79,18 @@ These commands exist in the TS CLI today but have no direct top-level equivalent
 
 ## Behavioral divergences from the Go reference
 
+- `db diff`/`db pull`/`db schema declarative sync` shadow baseline cache (#6184): the shadow
+  database's platform baseline is cached as a PGDATA snapshot under
+  `supabase/.temp/pgdelta/shadow-baseline-<key>.tar` (~90MB, current key only) and restored into a
+  fresh container on later runs, cutting shadow provisioning from ~15s to a few seconds. TS-only,
+  default ON; `SUPABASE_SHADOW_CACHE=false`/`=0` opts out (ambient env or project dotenv), `sync
+--no-cache` bypasses it per-invocation, and `SUPABASE_SHADOW_DEBUG=1` prints stderr-only phase
+  timings. OrioleDB clusters and PG <= 14 are cache-ineligible (external S3 state and mid-session
+  role-default mutation respectively — see `shadow-cache.ts`). Known session-semantics caveat on
+  the cached paths: migrations run on a session opened after the baseline, so role-level defaults
+  a user's `roles.sql` installs (`ALTER ROLE … SET …`) apply to migrations, whereas Go's
+  single-connection flow ran migrations before those defaults took effect; opting out restores
+  Go's exact single-session behavior.
 - `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
@@ -151,3 +171,10 @@ These commands exist in the TS CLI today but have no direct top-level equivalent
   redirect the service-role key to an attacker-controlled host. Intentional
   TS-only hardening, not a parity bug — see
   [`services/SIDE_EFFECTS.md`](../src/legacy/commands/services/SIDE_EFFECTS.md).
+- `db pull` in-sync (`"No schema changes found"`) keeps Go's message and its non-zero
+  exit code, but replaces the generic "Try rerunning the command with --debug to
+  troubleshoot the error." stderr footer with an explanatory suggestion line
+  ("The remote database is already in sync with your local migrations — nothing to
+  pull."). An in-sync database is a finding, not a failure to troubleshoot, so the
+  debug hint sent users chasing a non-existent bug. Message text and exit code — the
+  parts scripts depend on — are unchanged.

apps/cli/docs/templates/examples.yaml

@@ -310,7 +310,7 @@ supabase-db-schema-declarative-sync:
       Reset local database to match migrations first? (local data will be lost) [y/N] y
       Resetting database...
       ...
-      Declarative schema written to supabase/database
+      Declarative schema written to supabase/schemas
       Finished supabase db schema declarative generate.
 supabase-test-db:
   - id: basic-usage

apps/cli/package.json

@@ -55,6 +55,8 @@
     "@parcel/watcher": "^2.6.0",
     "@supabase/api": "workspace:*",
     "@supabase/config": "workspace:*",
+    "@supabase/pg-delta": "1.0.0-alpha.40",
+    "@supabase/pg-topo": "1.0.0-alpha.5",
     "@supabase/process-compose": "workspace:*",
     "@supabase/stack": "workspace:*",
     "@tsconfig/bun": "catalog:",

apps/cli/scripts/build-binary.integration.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const fixturePath = fileURLToPath(
+  new URL("../tests/fixtures/compiled-libpg-query.ts", import.meta.url),
+);
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true })),
+  );
+});
+
+describe("compiled binary assets", () => {
+  test("embeds and loads libpg-query.wasm", async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), "supabase-compiled-wasm-"));
+    temporaryDirectories.push(directory);
+    const executable = path.join(directory, "parser-probe");
+    const bunExecutable = Bun.which("bun");
+    if (!bunExecutable) {
+      throw new Error("Bun executable not found");
+    }
+
+    const build = Bun.spawn(
+      [bunExecutable, "build", fixturePath, "--compile", `--outfile=${executable}`],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const [buildExitCode, buildStderr] = await Promise.all([
+      build.exited,
+      new Response(build.stderr).text(),
+    ]);
+    expect(buildExitCode, buildStderr).toBe(0);
+
+    const probe = Bun.spawn([executable], {
+      cwd: directory,
+      env: {},
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [probeExitCode, stdout, stderr] = await Promise.all([
+      probe.exited,
+      new Response(probe.stdout).text(),
+      new Response(probe.stderr).text(),
+    ]);
+
+    expect(probeExitCode, stderr).toBe(0);
+    expect(stdout).toContain("libpg-query.wasm loaded");
+  }, 20_000);
+});