feat(cli): port pg-delta catalog cache

apps/cli/docs/go-cli-porting-status.md

@@ -86,7 +86,7 @@ These commands exist in the TS CLI today but have no direct top-level equivalent
 | `db dump` | `ported` | `legacy/commands/db/dump/` | `n/a` | `n/a` | Native TS port. Streams `pg_dump`/`pg_dumpall` via a Docker container (`LegacyDockerRun`); schema/data/role modes, `--dry-run` script print, IPv4 transaction-pooler fallback. |
 | `db lint` | `ported` | `legacy/commands/db/lint/` | `n/a` | `n/a` | Native TS port. Runs `plpgsql_check` in a rolled-back transaction via LegacyDbConnection; emits Go-parity pretty JSON. |
 | `db pull` | `ported` | `legacy/commands/db/pull/` | `n/a` | `n/a` | Native TS port. Native pg-delta / migra migration + `--declarative` pg-delta export; reconciles `schema_migrations`. The initial-migra pull dumps the remote schema natively (`pg_dump`) then appends the migra diff. Only `--experimental` (structured dump) still delegates to Go, pending a TS PostgreSQL DDL parser for `format.WriteStructuredSchemas`. |
-| `db push` | `ported` | `legacy/commands/db/push/` | `n/a` | `n/a` | Native TS port. Connects local/linked/`--db-url`; pushes pending migrations, `--include-seed` seeds (`seed_files` hash tracking), `--include-roles`, `[db.vault]` secrets; `--dry-run`. `encrypted:` vault secrets + best-effort pg-delta catalog cache not ported (no output impact).  |
+| `db push` | `ported` | `legacy/commands/db/push/` | `n/a` | `n/a` | Native TS port. Connects local/linked/`--db-url`; pushes pending migrations, `--include-seed` seeds (`seed_files` hash tracking), `--include-roles`, `[db.vault]` secrets including decrypted `encrypted:` values; `--dry-run`; best-effort pg-delta migrations-catalog cache (warning-only on failure). |
 | `db reset` | `ported` | `legacy/commands/db/reset/` | `n/a` | `n/a` | Remote path native (drop user schemas, vault upsert, MigrateAndSeed, `--version`/`--last`, `--sql-paths` seed override). Local path native: running check, recreate + migrate + seed via the hidden Go `db __db-bootstrap` seam, storage-gated bucket seeding (reuses `seed buckets`), git-branch `Finished…` line. Only the niche `--experimental` remote schema-files path still delegates to the Go binary (telemetry-disabled). |
 | `db start` | `ported` | `legacy/commands/db/start/` | `n/a` | `n/a` | Native TS port. Validates config, checks "already running" (prints Go's line), else delegates the container bootstrap (create + health + initial schema/roles/migrations/seed + `_current_branch`) to the hidden Go `db __db-bootstrap --mode start` seam. No status table / `cli_stack_started` (those are `supabase start`). `--from-backup` supported. |
 | `inspect report` | `ported` | `legacy/commands/inspect/report/` | `n/a` | `n/a` | Native TS port. Runs every inspect query via server-side `COPY ... CSV`, writes 14 CSVs under `<output-dir>/<date>/`, then renders a Go-parity Glamour rules summary (bounded csvq-subset evaluator; custom `[experimental.inspect.rules]` supported). |

apps/cli/src/legacy/commands/db/diff/diff.handler.ts

@@ -8,7 +8,6 @@ import { LegacyCliConfig } from "../../../config/legacy-cli-config.service.ts";
 import { legacyAqua, legacyYellow } from "../../../shared/legacy-colors.ts";
 import { legacyReadDbToml } from "../../../shared/legacy-db-config.toml-read.ts";
 import { LegacyDbConfigResolver } from "../../../shared/legacy-db-config.service.ts";
-import type { LegacyPgConnInput } from "../../../shared/legacy-db-connection.service.ts";
 import type { LegacyDbConnType } from "../../../shared/legacy-db-target-flags.ts";
 import { legacyGetHostname } from "../../../shared/legacy-hostname.ts";
 import { legacyMakeDir } from "../../../shared/legacy-make-dir.ts";
@@ -45,23 +44,6 @@ import {
 const warnDiff = `WARNING: The diff tool is not foolproof, so you may need to manually rearrange and modify the generated migration.
 Run ${legacyAqua("supabase db reset")} to verify that the new migration does not generate errors.`;
 
-/** Builds a plain Postgres URL from a resolved connection (Go's `ToPostgresURL`). */
-const connToUrl = (conn: LegacyPgConnInput): string =>
- legacyToPostgresURL({
- host: conn.host,
- port: conn.port,
- user: conn.user,
- password: conn.password,
- database: conn.database,
- ...(conn.options !== undefined ? { options: conn.options } : {}),
- ...(conn.runtimeParams !== undefined ? { runtimeParams: conn.runtimeParams } : {}),
- // Preserve a `--db-url` connect_timeout; Go's ToPostgresURL serializes the
- // parsed ConnectTimeout (`connect.go`), defaulting to 10 only when unset.
- ...(conn.connectTimeoutSeconds !== undefined
- ? { connectTimeoutSeconds: conn.connectTimeoutSeconds }
- : {}),
- });
-
 /**
  * Rebuilds the `db diff` argv for the pgAdmin / pg-schema delegate path. Flags
  * stay flags (the Go-proxy channel-parity rule). The explicit `--from`/`--to` and
@@ -235,7 +217,7 @@ export const legacyDbDiff = Effect.fn("legacy.db.diff")(function* (flags: Legacy
  mergedLinkedRef = ref2;
  cfg = yield* legacyReadDbToml(fs, path, cliConfig.workdir, ref2);
  }
- return connToUrl(resolved.conn);
+ return legacyToPostgresURL(resolved.conn);
  }
  case "migrations":
  return yield* seam.exportCatalog({
@@ -362,7 +344,7 @@ export const legacyDbDiff = Effect.fn("legacy.db.diff")(function* (flags: Legacy
  });
  const linkedRef = Option.getOrUndefined(resolved.ref ?? Option.none());
  if (linkedRef !== undefined) linkedRefForCache = linkedRef;
- const targetUrl = connToUrl(resolved.conn);
+ const targetUrl = legacyToPostgresURL(resolved.conn);
 
  // Read config with the resolved linked ref so a matching `[remotes.<ref>]`
  // block merges before the engine/format/runtime are read — Go loads config

apps/cli/src/legacy/commands/db/pull/pull.handler.ts

@@ -91,23 +91,6 @@ const DEPRECATION_LINE =
 /** Migration-file mode for the initial pg_dump seed (Go's `OpenFile(..., 0644)`). */
 const MIGRATION_FILE_MODE = 0o644;
 
-/** Builds a plain Postgres URL from a resolved connection (Go's `ToPostgresURL`). */
-const connToUrl = (conn: LegacyPgConnInput): string =>
- legacyToPostgresURL({
- host: conn.host,
- port: conn.port,
- user: conn.user,
- password: conn.password,
- database: conn.database,
- ...(conn.options !== undefined ? { options: conn.options } : {}),
- ...(conn.runtimeParams !== undefined ? { runtimeParams: conn.runtimeParams } : {}),
- // Preserve a `--db-url` connect_timeout; Go's ToPostgresURL serializes the
- // parsed ConnectTimeout (`connect.go`), defaulting to 10 only when unset.
- ...(conn.connectTimeoutSeconds !== undefined
- ? { connectTimeoutSeconds: conn.connectTimeoutSeconds }
- : {}),
- });
-
 /** Rebuilds the `db pull` argv for the Go-delegated `--experimental` structured-dump branch. */
 const rebuildDelegateArgs = (flags: LegacyDbPullFlags): Array<string> => {
  const args = ["db", "pull"];
@@ -233,7 +216,7 @@ export const legacyDbPull = Effect.fn("legacy.db.pull")(function* (flags: Legacy
  });
  const linkedRef = Option.getOrUndefined(resolved.ref ?? Option.none());
  if (linkedRef !== undefined) linkedRefForCache = linkedRef;
- const targetUrl = connToUrl(resolved.conn);
+ const targetUrl = legacyToPostgresURL(resolved.conn);
 
  // Reload config with the resolved linked ref so a matching `[remotes.<ref>]`
  // block merges before the engine/format/runtime/declarative paths are read —
@@ -294,7 +277,7 @@ export const legacyDbPull = Effect.fn("legacy.db.pull")(function* (flags: Legacy
  .pipe(Effect.orElseSucceed(() => Option.none()));
  if (Option.isSome(pooler)) {
  yield* legacyEmitPoolerFallbackWarning(resolved.conn.host);
- return yield* attempt(connToUrl(pooler.value));
+ return yield* attempt(legacyToPostgresURL(pooler.value));
  }
  }
  return yield* Effect.fail(error);

apps/cli/src/legacy/commands/db/push/SIDE_EFFECTS.md

@@ -18,12 +18,12 @@ linked/remote Postgres database.
 
 ## Files Written
 
-| Path | Format | When |
-| ------------------------------------------------ | ------ | ------------------------------------------------------------------------- |
-| `~/.supabase/<workdir-hash>/linked-project.json` | JSON | on the `--linked` path (post-run cache, Go's `ensureProjectGroupsCached`) |
-| `~/.supabase/telemetry.json` | JSON | always (post-run telemetry flush) |
-
-No project files are written. All other effects are database mutations (below).
+| Path | Format | When |
+| ------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `~/.supabase/<workdir-hash>/linked-project.json` | JSON | on the `--linked` path (post-run cache, Go's `ensureProjectGroupsCached`) |
+| `~/.supabase/telemetry.json` | JSON | always (post-run telemetry flush) |
+| `<workdir>/supabase/.temp/pgdelta/catalog-<prefix>-migrations-<hash>-<ts>.json` | JSON | best-effort, after a successful migration apply, when pg-delta is enabled (`[experimental.pgdelta] enabled` or `SUPABASE_EXPERIMENTAL_PG_DELTA`); a failure only warns on stderr and never fails the push (Go's `pgcache.TryCacheMigrationsCatalog`) |
+| `<workdir>/supabase/.temp/pgdelta/pgdelta-target-ca.crt` | PEM | same gate as above, when the target requires SSL (`legacyPreparePgDeltaRef`) |
 
 ## Database Mutations
 
@@ -43,11 +43,13 @@ No project files are written. All other effects are database mutations (below).
 
 ## Environment Variables
 
-| Variable | Purpose | Required? |
-| ----------------------- | ------------------------------------------- | ------------------------------------------------------- |
-| `SUPABASE_ACCESS_TOKEN` | auth token for the `--linked` resolver path | no (falls back to keyring → `~/.supabase/access-token`) |
-| `SUPABASE_DB_PASSWORD` | password for the linked/remote connection | no (`--password`/`-p` takes precedence) |
-| `SUPABASE_YES` | auto-confirm prompts (Go's `viper YES`) | no (also `--yes`) |
+| Variable | Purpose | Required? |
+| ---------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `SUPABASE_ACCESS_TOKEN` | auth token for the `--linked` resolver path | no (falls back to keyring → `~/.supabase/access-token`) |
+| `SUPABASE_DB_PASSWORD` | password for the linked/remote connection | no (`--password`/`-p` takes precedence) |
+| `SUPABASE_YES` | auto-confirm prompts (Go's `viper YES`) | no (also `--yes`) |
+| `SUPABASE_EXPERIMENTAL_PG_DELTA` | enables the migrations-catalog cache when `[experimental.pgdelta].enabled` is unset | no (project `.env` or shell) |
+| `SUPABASE_INTERNAL_IMAGE_REGISTRY` | overrides the pg-delta edge-runtime image registry for the cache export | no (project `.env` or shell) |
 
 ## Exit Codes
 
@@ -97,8 +99,14 @@ stdout is payload-only. A single `result` object is emitted:
 - **`--dry-run`** prints the plan (roles / migrations / seeds) and applies nothing.
 - **`[db.migrations].enabled = false`** / **`[db.seed].enabled = false`** print a
  skip notice naming the project ref (empty for local/db-url).
-- **Vault**: only non-empty, non-`env()` `[db.vault]` literals are synced (Go syncs
- secrets with a non-empty SHA256). **Known gap vs Go**: `encrypted:`-prefixed
- vault secrets are currently skipped — dotenvx/ECIES decryption is not yet ported.
-- **Migrations catalog cache** (Go's best-effort `pgcache.TryCacheMigrationsCatalog`,
- warning-only) is not ported; it produces no output, so parity is preserved.
+- **Vault**: non-empty, non-`env()` `[db.vault]` values are synced after config
+ load, including decrypted `encrypted:` values.
+- **Migrations catalog cache**: ported (Go's best-effort `pgcache.TryCacheMigrationsCatalog`).
+ After a successful migration apply, when pg-delta is enabled, exports the target's
+ pg-delta catalog via the edge-runtime stack and writes it under
+ `supabase/.temp/pgdelta/`, pruning older snapshots for the same prefix (retains 2).
+ A failure only warns on stderr (`Warning: failed to cache migrations catalog: …`)
+ and never fails the push, matching Go exactly. Reuses `legacyExportCatalogPgDelta`
+ (the same pg-delta export path `db pull`/`db diff` use, which always mounts the
+ project root at `/workspace`) rather than a second copy, so the ENOENT bug fixed in
+ Go's `pgcache/cache.go` (supabase/cli#5921) has no TS equivalent.

apps/cli/src/legacy/commands/db/push/push.handler.ts

@@ -1,4 +1,4 @@
-import { Effect, FileSystem, Option, Path } from "effect";
+import { Clock, Effect, FileSystem, Option, Path } from "effect";
 
 import { CliArgs } from "../../../../shared/cli/cli-args.service.ts";
 import { LegacyDnsResolverFlag } from "../../../../shared/legacy/global-flags.ts";
@@ -9,6 +9,7 @@ import { LegacyProjectRefResolver } from "../../../config/legacy-project-ref.ser
 import { legacyAqua, legacyBold } from "../../../shared/legacy-colors.ts";
 import { LegacyDbConfigResolver } from "../../../shared/legacy-db-config.service.ts";
 import {
+ legacyApplyProjectEnv,
  legacyCheckDbToml,
  legacyLoadProjectEnv,
 } from "../../../shared/legacy-db-config.toml-read.ts";
@@ -18,10 +19,17 @@ import {
  legacySeedGlobals,
 } from "../../../shared/legacy-migration-apply.ts";
 import { legacyPromptYesNo } from "../../../shared/legacy-prompt-yes-no.ts";
+import { legacyToPostgresURL } from "../../../shared/legacy-postgres-url.ts";
 import { resolveLegacyDbTargetFlags } from "../../../shared/legacy-db-target-flags.ts";
 import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
 import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
-import { legacyListLocalMigrations } from "../shared/legacy-pgdelta.cache.ts";
+import { redactLegacyConnectionString } from "../../../shared/legacy-db-config.parse.ts";
+import { legacyParseBoolEnv } from "../shared/legacy-diff-engine.ts";
+import {
+ legacyListLocalMigrations,
+ legacyTryCacheMigrationsCatalog,
+} from "../shared/legacy-pgdelta.cache.ts";
+import { type LegacyPgDeltaContext } from "../shared/legacy-pgdelta.ts";
 import {
  LEGACY_ERR_MISSING_LOCAL,
  LEGACY_ERR_MISSING_REMOTE,
@@ -92,6 +100,7 @@ export const legacyDbPush = Effect.fn("legacy.db.push")(function* (flags: Legacy
  let linkedRefForCache: string | undefined;
 
  const body = Effect.gen(function* () {
+ yield* legacyApplyProjectEnv(projectEnv);
  const target = resolveLegacyDbTargetFlags(cliArgs.args);
  // cobra MarkFlagsMutuallyExclusive("db-url", "linked", "local"), keyed off the
  // explicitly-set flags (cobra's `Changed`), not the `--linked` default value.
@@ -286,9 +295,30 @@ export const legacyDbPush = Effect.fn("legacy.db.push")(function* (flags: Legacy
  }
  yield* legacyUpsertVaultSecrets(session, vaultSecrets);
  yield* legacyApplyMigrations(session, fs, path, pending, applyError);
- // Go best-effort caches the migrations catalog for pg-delta; a failure
- // only warns (`push.go:99-101`). The catalog cache is not yet ported, so
- // there is nothing to warn about — parity is preserved (no extra output).
+ const cacheEnabled =
+ toml.pgDelta.enabled ||
+ legacyParseBoolEnv(toml.envLookup("SUPABASE_EXPERIMENTAL_PG_DELTA"));
+ const pgDeltaCtx: LegacyPgDeltaContext = {
+ projectId: Option.getOrElse(cliConfig.projectId, () => ""),
+ cwd: workdir,
+ npmVersion: Option.getOrUndefined(toml.pgDelta.npmVersion),
+ denoVersion: toml.denoVersion,
+ };
+ yield* legacyTryCacheMigrationsCatalog(fs, path, pgDeltaCtx, {
+ enabled: cacheEnabled,
+ targetUrl: legacyToPostgresURL(cfg.conn),
+ conn: cfg.conn,
+ isLocal: cfg.isLocal,
+ migrationsDir: path.join(workdir, "supabase", "migrations"),
+ nowMillis: yield* Clock.currentTimeMillis,
+ }).pipe(
+ Effect.catch((error) =>
+ output.raw(
+ `Warning: failed to cache migrations catalog: ${redactLegacyConnectionString(error.message)}\n`,
+ "stderr",
+ ),
+ ),
+ );
  } else {
  yield* output.raw("Schema migrations are up to date.\n", "stderr");
  }
@@ -336,5 +366,6 @@ export const legacyDbPush = Effect.fn("legacy.db.push")(function* (flags: Legacy
  ),
  ),
  Effect.ensuring(telemetryState.flush),
+ Effect.scoped,
  );
 });