fix(cli): skip provisioned ledger ddl (CLI-2275) (#6422)

## TL;DR

stop sending the migration ledger DDL to remotes that already have the
ledger, which is the traffic the Supavisor session pooler kills...

## what's biting?

migration repair dies with a connection error over the session pooler
while migration list works on the same connection. every history command
runs the seven statement ledger setup transaction on every invocation,
even when the ledger already exists, and that DDL is what the pooler
drops. list only sends a SELECT.

## now fixed by:

a read-only probe with the same wire shape as the list SELECT. 
ledger fully there: no DDL is sent. anything less, or any odd probe
answer: the full unchanged DDL runs, so ledger upgrades behave exactly
as before. covers the history and seed ledgers...

## ref:
- closes: #6393

Author: 7ttp

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

@@ -30,10 +30,10 @@ before migrations unless `--skip-vault` is set.
 | Statement                                                                                                           | When                                                                                                                                                                                                                                    |
 | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `RESET ALL` + migration statements + `INSERT INTO supabase_migrations.schema_migrations(version, name, statements)` | per pending migration (after confirmation); compatible statements use an implicit extended-protocol batch with one final `Sync`, while pipeline-incompatible statements run standalone — see Notes                                      |
-| `CREATE SCHEMA/TABLE … supabase_migrations.schema_migrations`, `ALTER TABLE … ADD COLUMN …`                         | once before applying migrations (idempotent)                                                                                                                                                                                            |
+| `CREATE SCHEMA/TABLE … supabase_migrations.schema_migrations`, `ALTER TABLE … ADD COLUMN …`                         | once before applying migrations, when a read-only probe finds the ledger not yet provisioned (idempotent; supabase/cli#6393)                                                                                                            |
 | `roles.sql` statements (no history row)                                                                             | per `--include-roles` globals file (after confirmation); statements use an implicit extended-protocol batch with one final `Sync`                                                                                                       |
 | `SELECT id, name FROM vault.secrets …`, `SELECT vault.update_secret(...)`, `SELECT vault.create_secret(...)`        | when `[db.vault]` has syncable secrets, migrations are applied, and `--skip-vault` is not set                                                                                                                                           |
-| `CREATE TABLE … supabase_migrations.seed_files`, seed statements, `INSERT … seed_files(path, hash) … ON CONFLICT …` | per pending seed file with `--include-seed` (after confirmation); a dirty seed only refreshes the hash                                                                                                                                  |
+| `CREATE TABLE … supabase_migrations.seed_files`, seed statements, `INSERT … seed_files(path, hash) … ON CONFLICT …` | per pending seed file with `--include-seed` (after confirmation; the `seed_files` DDL only when a read-only probe finds that ledger not yet provisioned); a dirty seed only refreshes the hash                                          |
 | `SET SESSION ROLE postgres`                                                                                         | stepped-down sessions only (`cli_login_*`/`supabase_admin`): after each top-level role-reverting statement, at the end of each migration/globals/seed file, and before the history insert and the `seed_files` upsert (CLI-2205, #6236) |
 
 ## API Routes

apps/cli/src/legacy/commands/migration/repair/SIDE_EFFECTS.md

@@ -42,9 +42,11 @@
 When repairing specific versions, prints `Repaired migration history: [<versions>]
 => <status>` to stderr, then `Finished supabase migration repair.` to stdout and
 the suggestion `Run supabase migration list to show the updated migration history.`
-to stderr. The DB mutation is one transaction: create the history table, then (for
-repair-all) `TRUNCATE`, plus `applied` → per-version `UPSERT` from the local file,
-`reverted` → `DELETE ... WHERE version = ANY($1)`.
+to stderr. The DB work is the history-table provisioning (its own transaction,
+skipped entirely when a read-only probe finds the ledger already provisioned, so a
+provisioned remote runs no provisioning DDL — supabase/cli#6393) followed by one
+repair transaction: (for repair-all) `TRUNCATE`, plus `applied` → per-version
+`UPSERT` from the local file, `reverted` → `DELETE ... WHERE version = ANY($1)`.
 
 > **Atomicity note:** the old Go CLI ran the TRUNCATE/UPSERT/DELETE via a batched
 > pipeline (not an explicit transaction), so a partial failure mid-batch (e.g.

apps/cli/src/legacy/shared/legacy-migration-apply.unit.test.ts

@@ -391,7 +391,9 @@ describe("legacyApplyMigrationFile", () => {
           expect(action).toBeGreaterThan(set);
           expect(cleanup).toBeGreaterThan(action);
 
-          const history = calls.filter((call) => call.kind === "query");
+          const history = calls.filter(
+            (call) => call.kind === "query" && call.params !== undefined,
+          );
           expect(history).toHaveLength(1);
           expect(history[0]?.params).toEqual([
             "20240101120000",
@@ -422,7 +424,9 @@ describe("legacyApplyMigrationFile", () => {
           expect(Exit.isFailure(exit)).toBe(true);
           const execs = calls.filter((call) => call.kind === "exec").map((call) => call.sql);
           expect(execs.at(-1)).toBe("RESET ALL");
-          expect(calls.some((call) => call.kind === "query")).toBe(false);
+          expect(calls.some((call) => call.kind === "query" && call.params !== undefined)).toBe(
+            false,
+          );
           if (Exit.isFailure(exit)) {
             expect(JSON.stringify(exit.cause)).toContain("At statement: 1");
           }
@@ -474,7 +478,9 @@ describe("legacyApplyMigrationFile", () => {
           expect(execs.filter((sql) => sql === "BEGIN")).toHaveLength(2);
           expect(execs.filter((sql) => sql === "COMMIT")).toHaveLength(2);
           expect(execs).toContain("SET LOCAL check_function_bodies = off");
-          const history = calls.filter((call) => call.kind === "query");
+          const history = calls.filter(
+            (call) => call.kind === "query" && call.params !== undefined,
+          );
           expect(history).toHaveLength(1);
           expect(history[0]?.params?.[0]).toBe("20240101120000");
           rmSync(dir, { recursive: true, force: true });
@@ -510,7 +516,9 @@ describe("legacyApplyMigrationFile", () => {
             expect.stringContaining("supabase_migrations.schema_migrations"),
           ]);
           // No standalone history insert: it rides the same batch as the statements.
-          expect(calls.filter((call) => call.kind === "query")).toHaveLength(0);
+          expect(
+            calls.filter((call) => call.kind === "query" && call.params !== undefined),
+          ).toHaveLength(0);
           rmSync(dir, { recursive: true, force: true });
         }),
       ),
@@ -527,7 +535,9 @@ describe("legacyApplyMigrationFile", () => {
       Effect.tap((exit) =>
         Effect.sync(() => {
           expect(Exit.isFailure(exit)).toBe(true);
-          expect(calls.some((call) => call.kind === "query")).toBe(false);
+          expect(calls.some((call) => call.kind === "query" && call.params !== undefined)).toBe(
+            false,
+          );
           expect(calls.some((call) => call.kind === "exec" && call.sql === "ROLLBACK")).toBe(true);
           rmSync(dir, { recursive: true, force: true });
         }),
@@ -601,7 +611,9 @@ describe("legacyApplyMigrationFile", () => {
           const authoredCommit = calls.findLastIndex(
             (call) => call.kind === "exec" && call.sql === "COMMIT",
           );
-          const history = calls.findIndex((call) => call.kind === "query");
+          const history = calls.findIndex(
+            (call) => call.kind === "query" && call.params !== undefined,
+          );
           expect(lastRestore).toBeGreaterThan(authoredCommit);
           expect(history).toBeGreaterThan(lastRestore);
           rmSync(dir, { recursive: true, force: true });
@@ -801,7 +813,9 @@ describe("legacyApplyMigrationFile", () => {
           const execs = calls.filter((call) => call.kind === "exec").map((call) => call.sql);
           expect(execs.filter((sql) => sql === "SET SESSION ROLE postgres")).toHaveLength(1);
           expect(execs[execs.indexOf("reset role") + 1]).toBe("SET SESSION ROLE postgres");
-          expect(calls.filter((call) => call.kind === "query")).toHaveLength(1);
+          expect(
+            calls.filter((call) => call.kind === "query" && call.params !== undefined),
+          ).toHaveLength(1);
           rmSync(dir, { recursive: true, force: true });
         }),
       ),

apps/cli/src/legacy/shared/legacy-migration-history.ts

@@ -75,36 +75,77 @@ const SELECT_SEED_TABLE = "SELECT path, hash FROM supabase_migrations.seed_files
 /** `pkg/migration/file.go` — `<digits>_<name>.sql`. */
 export const MIGRATE_FILE_PATTERN = /^([0-9]+)_(.*)\.sql$/u;
 
+/**
+ * Read-only probe: `true` when the relation is an ordinary or partitioned table
+ * carrying every live column its DDL creates, i.e. when each setup statement
+ * below is a guaranteed no-op. Sent with no bind parameters, matching the wire
+ * shape of the `migration list` SELECT that demonstrably survives the poolers
+ * this setup DDL dies on (supabase/cli#6393). Any unexpected answer falls
+ * through to the DDL path, but a probe FAILURE deliberately aborts instead: a
+ * connection that cannot serve this SELECT will not serve the setup transaction
+ * either, and failing loudly surfaces the real error rather than masking it
+ * behind a DDL failure. Interpolates its arguments verbatim: callers pass
+ * compile-time literals only.
+ */
+const legacyProvisionedProbe = (relation: string, columns: ReadonlyArray<string>) =>
+  `SELECT count(*) = ${columns.length} AS provisioned FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid = a.attrelid WHERE a.attrelid = pg_catalog.to_regclass('${relation}') AND c.relkind IN ('r', 'p') AND NOT a.attisdropped AND a.attname IN (${columns.map((column) => `'${column}'`).join(", ")})`;
+
+const SELECT_VERSION_TABLE_PROVISIONED = legacyProvisionedProbe(
+  "supabase_migrations.schema_migrations",
+  ["version", "name", "statements"],
+);
+const SELECT_SEED_TABLE_PROVISIONED = legacyProvisionedProbe("supabase_migrations.seed_files", [
+  "path",
+  "hash",
+]);
+
+const legacyIsTableProvisioned = (session: LegacyDbSession, probe: string) =>
+  session.query(probe).pipe(Effect.map((rows) => rows[0]?.["provisioned"] === true));
+
 /**
  * Creates the migration-history schema/table (idempotent). `CreateMigrationTable`.
- * The setup runs in one transaction so `SET LOCAL lock_timeout` is scoped to it and
- * reverts on `COMMIT`, matching Go's implicit `pgconn.ExecBatch` transaction; the GUC
- * never leaks into the caller's subsequent work. A failed statement rolls back.
+ * Skipped entirely when the provisioning probe finds the ledger already current, so
+ * an already-provisioned remote runs no DDL (supabase/cli#6393); an older or partial
+ * ledger still gets the full setup. The setup runs in one transaction so
+ * `SET LOCAL lock_timeout` is scoped to it and reverts on `COMMIT`, matching Go's
+ * implicit `pgconn.ExecBatch` transaction; the GUC never leaks into the caller's
+ * subsequent work. A failed statement rolls back.
  */
 export const legacyCreateMigrationTable = (session: LegacyDbSession) =>
-  Effect.gen(function* () {
-    yield* session.exec("BEGIN");
-    yield* session.exec(SET_LOCAL_LOCK_TIMEOUT);
-    yield* session.exec(CREATE_VERSION_SCHEMA);
-    yield* session.exec(CREATE_VERSION_TABLE);
-    yield* session.exec(ADD_STATEMENTS_COLUMN);
-    yield* session.exec(ADD_NAME_COLUMN);
-    yield* session.exec("COMMIT");
-  }).pipe(Effect.tapError(() => session.exec("ROLLBACK").pipe(Effect.ignore)));
+  Effect.flatMap(
+    legacyIsTableProvisioned(session, SELECT_VERSION_TABLE_PROVISIONED),
+    (provisioned) =>
+      provisioned
+        ? Effect.void
+        : Effect.gen(function* () {
+            yield* session.exec("BEGIN");
+            yield* session.exec(SET_LOCAL_LOCK_TIMEOUT);
+            yield* session.exec(CREATE_VERSION_SCHEMA);
+            yield* session.exec(CREATE_VERSION_TABLE);
+            yield* session.exec(ADD_STATEMENTS_COLUMN);
+            yield* session.exec(ADD_NAME_COLUMN);
+            yield* session.exec("COMMIT");
+          }).pipe(Effect.tapError(() => session.exec("ROLLBACK").pipe(Effect.ignore))),
+  );
 
 /**
- * Creates the `seed_files` schema/table (idempotent). `CreateSeedTable`. Same
- * transaction-scoped `SET LOCAL lock_timeout` as `legacyCreateMigrationTable` so the
- * timeout reverts on `COMMIT` and never leaks into the seed SQL the caller runs next.
+ * Creates the `seed_files` schema/table (idempotent). `CreateSeedTable`. Probed and
+ * skipped when already provisioned; otherwise the same transaction-scoped
+ * `SET LOCAL lock_timeout` as `legacyCreateMigrationTable` so the timeout reverts on
+ * `COMMIT` and never leaks into the seed SQL the caller runs next.
  */
 export const legacyCreateSeedTable = (session: LegacyDbSession) =>
-  Effect.gen(function* () {
-    yield* session.exec("BEGIN");
-    yield* session.exec(SET_LOCAL_LOCK_TIMEOUT);
-    yield* session.exec(CREATE_VERSION_SCHEMA);
-    yield* session.exec(CREATE_SEED_TABLE);
-    yield* session.exec("COMMIT");
-  }).pipe(Effect.tapError(() => session.exec("ROLLBACK").pipe(Effect.ignore)));
+  Effect.flatMap(legacyIsTableProvisioned(session, SELECT_SEED_TABLE_PROVISIONED), (provisioned) =>
+    provisioned
+      ? Effect.void
+      : Effect.gen(function* () {
+          yield* session.exec("BEGIN");
+          yield* session.exec(SET_LOCAL_LOCK_TIMEOUT);
+          yield* session.exec(CREATE_VERSION_SCHEMA);
+          yield* session.exec(CREATE_SEED_TABLE);
+          yield* session.exec("COMMIT");
+        }).pipe(Effect.tapError(() => session.exec("ROLLBACK").pipe(Effect.ignore))),
+  );
 
 /** A recorded seed file's path + content hash. `migration.SeedFile`. */
 export interface LegacySeedRow {

apps/cli/src/legacy/shared/legacy-migration-history.unit.test.ts

@@ -5,6 +5,8 @@ import { stripAnsi } from "../../../tests/helpers/ansi.ts";
 import { LegacyDbExecError } from "./legacy-db-connection.errors.ts";
 import type { LegacyDbSession } from "./legacy-db-connection.service.ts";
 import {
+  legacyCreateMigrationTable,
+  legacyCreateSeedTable,
   legacyFindPendingMigrations,
   legacyListRemoteMigrations,
   legacyReconcileMigrations,
@@ -239,3 +241,81 @@ describe("legacyResolveMigrationFile (byte-ordered match, Go's sort.Strings via
     );
   });
 });
+
+describe("legacyCreateMigrationTable / legacyCreateSeedTable (provisioning probe, #6393)", () => {
+  const HISTORY_DDL = [
+    "BEGIN",
+    "SET LOCAL lock_timeout = '4s'",
+    "CREATE SCHEMA IF NOT EXISTS supabase_migrations",
+    "CREATE TABLE IF NOT EXISTS supabase_migrations.schema_migrations (version text NOT NULL PRIMARY KEY)",
+    "ALTER TABLE supabase_migrations.schema_migrations ADD COLUMN IF NOT EXISTS statements text[]",
+    "ALTER TABLE supabase_migrations.schema_migrations ADD COLUMN IF NOT EXISTS name text",
+    "COMMIT",
+  ];
+
+  const probedSession = (probeRows: ReadonlyArray<Record<string, unknown>>) => {
+    const execs: Array<string> = [];
+    const queries: Array<{ sql: string; params?: ReadonlyArray<unknown> }> = [];
+    const session: LegacyDbSession = {
+      exec: (sql) => {
+        execs.push(sql);
+        return Effect.void;
+      },
+      execBatch: () => Effect.die("unused"),
+      query: (sql, params) => {
+        queries.push({ sql, ...(params === undefined ? {} : { params }) });
+        return Effect.succeed(probeRows);
+      },
+      extensionExists: () => Effect.die("unused"),
+      copyToCsv: () => Effect.die("unused"),
+      queryRaw: () => Effect.die("unused"),
+    };
+    return { session, execs, queries };
+  };
+
+  it("puts no DDL on the wire when a ledger is already provisioned", async () => {
+    const { session, execs, queries } = probedSession([{ provisioned: true }]);
+    await Effect.runPromise(legacyCreateMigrationTable(session));
+    await Effect.runPromise(legacyCreateSeedTable(session));
+    expect(execs).toEqual([]);
+    expect(queries).toHaveLength(2);
+    expect(queries[0]?.sql).toContain("'supabase_migrations.schema_migrations'");
+    expect(queries[1]?.sql).toContain("'supabase_migrations.seed_files'");
+  });
+
+  it("keeps the probes on the simple query protocol: no bind parameters", async () => {
+    const { session, queries } = probedSession([{ provisioned: true }]);
+    await Effect.runPromise(legacyCreateMigrationTable(session));
+    await Effect.runPromise(legacyCreateSeedTable(session));
+    expect(queries).toHaveLength(2);
+    expect(queries.filter((q) => q.params !== undefined)).toEqual([]);
+    expect(queries.filter((q) => q.sql.includes("$"))).toEqual([]);
+  });
+
+  for (const [shape, rows] of [
+    ["an absent ledger (no rows)", []],
+    ["a partial ledger (provisioned: false)", [{ provisioned: false }]],
+    ["an unexpected result shape", [{ wat: 1 }]],
+  ] as const) {
+    it(`runs the full provisioning DDL in order against ${shape}`, async () => {
+      const { session, execs } = probedSession([...rows]);
+      await Effect.runPromise(legacyCreateMigrationTable(session));
+      expect(execs).toEqual(HISTORY_DDL);
+    });
+  }
+
+  it("propagates a probe failure without opening a transaction to roll back", async () => {
+    const error = new LegacyDbExecError({ message: "effect/sql/SqlError: Connection error" });
+    const execs: Array<string> = [];
+    const session: LegacyDbSession = {
+      ...failingSession(error),
+      exec: (sql) => {
+        execs.push(sql);
+        return Effect.void;
+      },
+    };
+    expect(await Effect.runPromise(Effect.flip(legacyCreateMigrationTable(session)))).toBe(error);
+    expect(await Effect.runPromise(Effect.flip(legacyCreateSeedTable(session)))).toBe(error);
+    expect(execs).toEqual([]);
+  });
+});