fix(cli): close test db Go-parity gaps from Codex review

Address the parity divergences flagged in the Codex review of the
`test db` port:

- Sanitize the configured `project_id` before naming the local docker
  network. Go runs `sanitizeProjectId` on `c.ProjectId`
  unconditionally (config.go:471) before `GetId` derives
  `supabase_network_<id>`, so a configured value like "my project"
  joins the same network the local stack created. The port previously
  only sanitized the cwd-basename fallback.
- Enable TLS for remote connections. Go uses TLS for remote
  (`ConnectByUrl`: pgx `sslmode=prefer` with non-TLS fallbacks
  stripped) and disables it for local (`ConnectLocalPostgres` sets
  `TLSConfig=nil`). The driver now sets `ssl: { rejectUnauthorized:
  false }` for remote (no cert verification, matching pgx) via a new
  `isLocal` connect option, threaded from the resolver and the pooler
  temp-role probe.
- Keep stdout reserved for the pg_prove TAP stream. Go writes
  "Connecting to {local|remote} database..." to stderr; the port used
  `output.task`, which renders a clack spinner on stdout (text) and
  emits JSON log events on stdout (stream-json), corrupting the TAP
  stream. Emit the diagnostic via `output.raw(..., "stderr")` instead.

Updates SIDE_EFFECTS.md and the connect-path e2e comment, and adds
integration coverage for the stderr diagnostic, the remote label, and
project_id sanitization.

Author: Coly010

apps/cli-e2e/src/tests/database-core.e2e.test.ts

@@ -365,5 +365,19 @@ describe("test db", () => {
     expect(result.stderr).toContain("connect");
   });
 
-  testParity(["test", "db", "--local"]);
+  // No testParity for `test db --local`: with no local Postgres listening in the
+  // harness, the only reachable path is the connection-failure path, and its
+  // stderr diverges by driver in ways that aren't cosmetic and can't be
+  // normalized away. Both now emit Go's leading diagnostic to stderr:
+  //   Connecting to local database...
+  // but the connect-error body and trailing hint still differ by driver. Go (pgx):
+  //   failed to connect to postgres: failed to connect to `host=… user=… database=…`: dial error (dial tcp …: connect: connection refused)
+  //   Make sure your local IP is allowed in Network Restrictions and Network Bans.
+  //   http://…/project/_/database/settings
+  // The TS port (@effect/sql-pg) prints the effect SqlError and the --debug hint:
+  //   failed to connect to postgres: effect/sql/SqlError: PgClient: Failed to connect
+  //   Try rerunning the command with --debug to troubleshoot the error.
+  // The meaningful contract (non-zero exit + a connect error on stderr) is
+  // covered by the behaviour test above. A real connect-path parity test would
+  // need a live local database in the harness.
 });

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

@@ -31,7 +31,7 @@ One-shot `docker run --rm supabase/pg_prove:3.36`:
 
 - `-v <hostpath>:<dockerpath>:ro` for each test path
 - `--security-opt label:disable`
-- `--network supabase_network_<project_id>` (local) with env `PGHOST=db PGPORT=5432`, or `--network host` (db-url / linked) with the resolved host/port
+- `--network supabase_network_<project_id>` (local) with env `PGHOST=db PGPORT=5432`, or `--network host` (db-url / linked) with the resolved host/port. `<project_id>` is sanitized exactly as Go's `config.Load` does (`sanitizeProjectId`), so an invalid configured value (e.g. `"my project"`) joins the same network the local stack created
 - `-e PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE`
 - cmd `pg_prove --ext .pg --ext .sql -r <paths> [--verbose]` (`--verbose` when `--debug`)
 
@@ -70,16 +70,24 @@ stream with no structured equivalent.
 
 ### `--output-format text` (Go CLI compatible)
 
-TAP streams to stdout; connection/enable progress shows as spinners (text mode only).
+TAP streams to stdout. The connection diagnostic `Connecting to {local|remote} database...`
+is written to **stderr** (matching Go's `ConnectByConfigStream`), never to stdout — no
+spinner is used, so stdout carries only the raw TAP bytes.
 
 ### `--output-format json` / `stream-json`
 
-No machine envelope is emitted (Go has none). stdout carries the raw TAP stream and
-spinners are suppressed; a non-zero `pg_prove` exit still fails the command (exit 1).
+No machine envelope is emitted (Go has none). stdout carries the raw TAP stream only; the
+connection diagnostic still goes to stderr (no task JSON-log events are written to stdout,
+which would otherwise corrupt the TAP stream). A non-zero `pg_prove` exit still fails the
+command (exit 1).
 
 ## Notes
 
 - Native TypeScript port (Phase 1+); no Go proxy. Hidden command (matches Go).
+- Postgres TLS matches Go (`internal/utils/connect.go`): remote (`--db-url` / `--linked`)
+  connections use TLS without certificate verification (pgx `sslmode=prefer` with non-TLS
+  fallbacks stripped); local connections disable TLS (`ConnectLocalPostgres` sets
+  `cc.TLSConfig = nil`).
 - Postgres access uses `@effect/sql-pg`. Go detects "pgTAP already installed" via a
   `pgx` `OnNotice` (code 42710 `duplicate_object`) callback, which `@effect/sql-pg`
   does not expose; the port instead checks `pg_extension` by extension name (any

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

@@ -99,17 +99,30 @@ export const legacyTestDb = Effect.fn("legacy.test.db")(function* (flags: Legacy
         : isLocal
           ? yield* Effect.gen(function* () {
               const toml = yield* legacyReadDbToml(fs, path, cliConfig.workdir);
-              const projectId = Option.getOrElse(toml.projectId, () =>
-                sanitizeProjectId(nodePath.basename(cliConfig.workdir)),
+              // Go sanitizes `c.ProjectId` unconditionally (`config.go:471`) —
+              // whether it came from `config.toml` or the cwd-basename fallback —
+              // before deriving the network name `supabase_network_<id>`
+              // (`config.go:57-58`, `GetId`). A configured `project_id` like
+              // "my project" must join the same sanitized network the local stack
+              // created, not the literal raw value.
+              const projectId = sanitizeProjectId(
+                Option.getOrElse(toml.projectId, () => nodePath.basename(cliConfig.workdir)),
               );
               return { _tag: "named" as const, name: `supabase_network_${projectId}` };
             })
           : { _tag: "host" as const };
 
     const exitCode = yield* Effect.scoped(
       Effect.gen(function* () {
-        const connecting = yield* output.task("Connecting to database...");
-        const session = yield* dbConn.connect(conn).pipe(Effect.tapError(() => connecting.fail()));
+        // stdout is reserved for the pg_prove TAP stream (the docker subprocess
+        // writes it there directly), so connection diagnostics must go to stderr —
+        // exactly as Go does (`ConnectByConfigStream` writes "Connecting to …
+        // database…" to `os.Stderr`, `connect.go:205-228`). A `Output.task`
+        // spinner would corrupt the TAP stream: clack writes spinner ANSI to
+        // stdout in text mode, and the stream-json layer emits task JSON log
+        // events to stdout. Go has no "Running pgTAP tests…" line at all.
+        yield* output.raw(`Connecting to ${isLocal ? "local" : "remote"} database...\n`, "stderr");
+        const session = yield* dbConn.connect(conn, { isLocal });
 
         // Detect pre-existence before enabling so the drop is skipped when pgTAP
         // was already installed (Go keys this off an OnNotice 42710 callback,
@@ -125,7 +138,6 @@ export const legacyTestDb = Effect.fn("legacy.test.db")(function* (flags: Legacy
                 message: `failed to enable pgTAP: ${cause.message}`,
               }),
           ),
-          Effect.tapError(() => connecting.fail()),
         );
         if (!alreadyExists) {
           yield* Effect.addFinalizer(() =>
@@ -138,22 +150,16 @@ export const legacyTestDb = Effect.fn("legacy.test.db")(function* (flags: Legacy
               ),
           );
         }
-        yield* connecting.clear();
 
-        const running = yield* output.task("Running pgTAP tests...");
-        const code = yield* docker
-          .run({
-            image: LEGACY_PG_PROVE_IMAGE,
-            cmd: args.cmd,
-            env: runEnv,
-            binds: args.binds,
-            workingDir: args.workingDir,
-            securityOpt: ["label:disable"],
-            network,
-          })
-          .pipe(Effect.tapError(() => running.fail()));
-        yield* running.clear();
-        return code;
+        return yield* docker.run({
+          image: LEGACY_PG_PROVE_IMAGE,
+          cmd: args.cmd,
+          env: runEnv,
+          binds: args.binds,
+          workingDir: args.workingDir,
+          securityOpt: ["label:disable"],
+          network,
+        });
       }),
     );
 

apps/cli/src/legacy/commands/test/db/db.integration.test.ts

@@ -1,3 +1,5 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { BunServices } from "@effect/platform-bun";
 import { describe, expect, it } from "@effect/vitest";
 import { Effect, Exit, Layer, Option } from "effect";
@@ -6,6 +8,7 @@ import { mockOutput } from "../../../../../tests/helpers/mocks.ts";
 import {
   mockLegacyCliConfig,
   mockLegacyTelemetryStateTracked,
+  useLegacyTempWorkdir,
 } from "../../../../../tests/helpers/legacy-mocks.ts";
 import { LegacyDebugFlag, LegacyNetworkIdFlag } from "../../../../shared/legacy/global-flags.ts";
 import { RuntimeInfo } from "../../../../shared/runtime/runtime-info.service.ts";
@@ -67,19 +70,25 @@ function mockDbConnection(opts: {
       }),
     extensionExists: () => Effect.succeed(opts.existed ?? false),
   };
+  const connectCalls: Array<{ cfg: LegacyPgConnInput; isLocal: boolean }> = [];
   const layer = Layer.succeed(LegacyDbConnection, {
-    connect: () =>
-      opts.connectFails === true
+    connect: (cfg, options) => {
+      connectCalls.push({ cfg, isLocal: options.isLocal });
+      return opts.connectFails === true
         ? Effect.fail(
             new LegacyDbConnectError({ message: "failed to connect to postgres: refused" }),
           )
-        : Effect.succeed(session),
+        : Effect.succeed(session);
+    },
   });
   return {
     layer,
     get execCalls() {
       return execCalls;
     },
+    get connectCalls() {
+      return connectCalls;
+    },
   };
 }
 
@@ -122,6 +131,7 @@ interface SetupOpts {
   runFails?: boolean;
   debug?: boolean;
   networkId?: string;
+  workdir?: string;
 }
 
 function setup(opts: SetupOpts = {}) {
@@ -135,7 +145,7 @@ function setup(opts: SetupOpts = {}) {
     resolver,
     connection.layer,
     docker.layer,
-    mockLegacyCliConfig({ workdir: "/work/project", projectId: Option.none() }),
+    mockLegacyCliConfig({ workdir: opts.workdir ?? "/work/project", projectId: Option.none() }),
     telemetry.layer,
     runtimeInfoLayer,
     Layer.succeed(LegacyDebugFlag, opts.debug ?? false),
@@ -170,6 +180,9 @@ describe("legacy test db integration", () => {
       expect(run?.env["PGPORT"]).toBe("5432");
       expect(run?.securityOpt).toEqual(["label:disable"]);
       expect(run?.cmd.slice(0, 5)).toEqual(["pg_prove", "--ext", ".pg", "--ext", ".sql"]);
+      // The setup connection must be told it is local so the driver disables TLS
+      // (Go's `ConnectLocalPostgres` sets `cc.TLSConfig = nil`).
+      expect(connection.connectCalls[0]?.isLocal).toBe(true);
     }).pipe(Effect.provide(layer));
   });
 
@@ -222,13 +235,16 @@ describe("legacy test db integration", () => {
   });
 
   it.live("db-url mode: uses host networking and the resolved host/port", () => {
-    const { layer, docker } = setup({ conn: REMOTE_CONN, isLocal: false });
+    const { layer, docker, connection } = setup({ conn: REMOTE_CONN, isLocal: false });
     return Effect.gen(function* () {
       yield* legacyTestDb(flags({ dbUrl: Option.some("postgres://x"), local: false }));
       const run = docker.lastOpts;
       expect(run?.network).toEqual({ _tag: "host" });
       expect(run?.env["PGHOST"]).toBe(REMOTE_CONN.host);
       expect(run?.env["PGPORT"]).toBe("5432");
+      // Remote connection → driver must enable TLS (Go strips non-TLS fallbacks
+      // in `ConnectByUrl`); the handler signals this via `isLocal: false`.
+      expect(connection.connectCalls[0]?.isLocal).toBe(false);
     }).pipe(Effect.provide(layer));
   });
 
@@ -322,4 +338,45 @@ describe("legacy test db integration", () => {
       expect(telemetry.flushed).toBe(true);
     }).pipe(Effect.provide(layer));
   });
+
+  it.live("writes the connection diagnostic to stderr, keeping stdout for TAP (Go parity)", () => {
+    const { layer, out } = setup();
+    return Effect.gen(function* () {
+      yield* legacyTestDb(flags());
+      // Go writes "Connecting to local database..." to os.Stderr and reserves
+      // stdout for the pg_prove TAP stream. A spinner/task on stdout would corrupt
+      // that stream (and stream-json task events would too), so the port must emit
+      // this on stderr and produce no stdout bytes of its own.
+      expect(out.stderrText).toContain("Connecting to local database...");
+      expect(out.stdoutText).toBe("");
+      // Go has no "Running pgTAP tests..." line and no spinner task messages.
+      expect(out.messages).toEqual([]);
+    }).pipe(Effect.provide(layer));
+  });
+
+  it.live("labels the connection diagnostic 'remote' for non-local connections", () => {
+    const { layer, out } = setup({ conn: REMOTE_CONN, isLocal: false });
+    return Effect.gen(function* () {
+      yield* legacyTestDb(flags({ dbUrl: Option.some("postgres://x"), local: false }));
+      expect(out.stderrText).toContain("Connecting to remote database...");
+    }).pipe(Effect.provide(layer));
+  });
+
+  const tempWorkdir = useLegacyTempWorkdir();
+  it.live("sanitizes a configured project_id when naming the local network (Go parity)", () => {
+    const workdir = tempWorkdir.current;
+    mkdirSync(join(workdir, "supabase"), { recursive: true });
+    // Go auto-fixes an invalid project_id via sanitizeProjectId (config.go:471,
+    // 803-805); the local stack network is created from the sanitized id, so
+    // `test db --local` must join `supabase_network_My_Project`, not the raw value.
+    writeFileSync(join(workdir, "supabase", "config.toml"), 'project_id = "My Project"\n');
+    const { layer, docker } = setup({ workdir });
+    return Effect.gen(function* () {
+      yield* legacyTestDb(flags());
+      expect(docker.lastOpts?.network).toEqual({
+        _tag: "named",
+        name: "supabase_network_My_Project",
+      });
+    }).pipe(Effect.provide(layer));
+  });
 });

apps/cli/src/legacy/shared/legacy-db-config.layer.ts

@@ -202,7 +202,9 @@ export const legacyDbConfigLayer = Layer.effect(
       conn: LegacyPgConnInput,
     ): Effect.Effect<void, LegacyDbConfigError, LegacyPlatformApi> => {
       const attempt = (n: number): Effect.Effect<void, LegacyDbConfigError, LegacyPlatformApi> =>
-        Effect.scoped(dbConn.connect(conn).pipe(Effect.asVoid)).pipe(
+        // The temp-role probe always targets the remote Supavisor pooler, so it
+        // connects with TLS (Go's pooler path goes through `ConnectByUrl`).
+        Effect.scoped(dbConn.connect(conn, { isLocal: false }).pipe(Effect.asVoid)).pipe(
           Effect.catch((cause) => {
             // Go's `backoff.WithMaxRetries(b, 8)` allows 8 retries after the
             // initial attempt → 9 total attempts. `n` is 1-based, so give up only

apps/cli/src/legacy/shared/legacy-db-connection.service.ts

@@ -45,9 +45,23 @@ export interface LegacyDbSession {
   readonly extensionExists: (name: string) => Effect.Effect<boolean, LegacyDbExecError>;
 }
 
+/** Per-connection options the driver layer cannot infer from `cfg` alone. */
+export interface LegacyDbConnectOptions {
+  /**
+   * Whether the target is the local stack (Go's `utils.IsLocalDatabase`). Drives
+   * TLS, mirroring Go (`apps/cli-go/internal/utils/connect.go`): local connections
+   * set `cc.TLSConfig = nil` (`ConnectLocalPostgres`) → no TLS, while remote
+   * connections go through `ConnectByUrl`, where pgx defaults to `sslmode=prefer`
+   * and every non-TLS fallback is stripped → TLS is required (without certificate
+   * verification, matching pgx's default for `prefer`/`require`).
+   */
+  readonly isLocal: boolean;
+}
+
 interface LegacyDbConnectionShape {
   readonly connect: (
     cfg: LegacyPgConnInput,
+    options: LegacyDbConnectOptions,
   ) => Effect.Effect<LegacyDbSession, LegacyDbConnectError, Scope.Scope>;
 }
 

apps/cli/src/legacy/shared/legacy-db-connection.sql-pg.layer.ts

@@ -3,6 +3,7 @@ import { Effect, Layer, Redacted, type Scope } from "effect";
 import * as Reactivity from "effect/unstable/reactivity/Reactivity";
 import { LegacyDbConnectError, LegacyDbExecError } from "./legacy-db-connection.errors.ts";
 import {
+  type LegacyDbConnectOptions,
   LegacyDbConnection,
   type LegacyDbSession,
   type LegacyPgConnInput,
@@ -53,6 +54,7 @@ function buildConnectionUrl(cfg: LegacyPgConnInput): string {
  */
 const connect = (
   cfg: LegacyPgConnInput,
+  { isLocal }: LegacyDbConnectOptions,
 ): Effect.Effect<LegacyDbSession, LegacyDbConnectError, Scope.Scope> =>
   Effect.gen(function* () {
     const hasOptions = cfg.options !== undefined && cfg.options.length > 0;
@@ -69,6 +71,13 @@ const connect = (
             password: Redacted.make(cfg.password),
             database: cfg.database,
           }),
+      // TLS parity with Go (`internal/utils/connect.go`): remote connections use
+      // TLS (pgx `sslmode=prefer` with non-TLS fallbacks stripped) but do not
+      // verify the certificate, while local connections disable TLS entirely
+      // (`ConnectLocalPostgres` sets `cc.TLSConfig = nil`). Omitting `ssl` here
+      // leaves the `pg` driver in plaintext mode — fine for local, but it would
+      // break against SSL-enforcing remote Supabase databases.
+      ...(isLocal ? {} : { ssl: { rejectUnauthorized: false } }),
       maxConnections: 1,
     }).pipe(
       Effect.provide(Reactivity.layer),