fix(cli): warn when gen types ignores --network-id

Native generation cannot join a Docker network. Surface a docker-run
workaround and classify native IPv6 dial failures so the pooler retry
still runs.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: avallete

AGENTS.md

@@ -216,9 +216,6 @@ Inside Effect code, compose schemas through their Effect APIs:
 
 ## Code Quality
 
-Never `git commit` or `git push` until lint and `types:check` have been run and passed for the change. Targeted unit/integration tests are not a substitute — CI Check code quality runs `pnpm check:all` (`types:check`, oxlint, oxfmt, knip). Before commit or push, from each changed TypeScript workspace run `pnpm types:check`, and from the repo root run `pnpm exec oxlint` (or `pnpm check:all`). If those fail, fix them before committing.
-After every `git push` to a branch that has a PR, check GitHub CI for that PR (`gh pr checks` / `gh run list`) and report whether it is green. If it is not, diagnose and fix; do not leave a red PR as done.
-
 Run repo-wide quality checks from the repository root with `pnpm check:all` or `pnpm fix:all`; these root scripts are the only quality entrypoints and delegate orchestration to Turbo. For package-local work, run `pnpm types:check` and the applicable package test scripts from the workspace you changed. Do not consider a task complete until all relevant scripts pass.
 Do not waive or defer failing checks in a changed workspace as "pre-existing". If a required check fails, fix it before closing the task. Only treat a failure as an external blocker when it cannot be resolved within the workspace, and in that case call it out explicitly.
 If you run a root quality command such as `pnpm check:all`, you own all failing checks it reports for the duration of the task, even if the failing files look unrelated. Do not leave the repository with unresolved failing checks after running the command.

apps/cli/src/legacy/commands/gen/types/SIDE_EFFECTS.md

@@ -60,7 +60,9 @@ treated as disable. When the connection string carries no explicit
 `connect_timeout`, a positive `--query-timeout` is also used as the connect
 timeout — `0` leaves the driver's default (10s remote, 2s local). `--local`
 connects to the host-mapped database port from `supabase/config.toml`
-(`db.port`).
+(`db.port`). Remote connections that use a `supabase_admin` or `cli_login_*`
+role step down to `postgres` via the shared driver (`SET SESSION ROLE
+postgres`) before introspection.
 
 For a remote target whose DSN carries no explicit `sslmode`, a raw TCP
 `SSLRequest` probe (the shared pg-delta probe, default 10s timeout) is opened
@@ -77,8 +79,9 @@ embedded bundle.
 
 `--network-id` / `SUPABASE_NETWORK_ID` are unused: generation no longer runs
 inside a container, so a hostname reachable only on a Docker network will not
-resolve. `--local` uses the published host port instead; `--db-url` must be
-host-reachable.
+resolve. An explicit `--network-id` prints a warning with a
+`docker run --network … npx supabase gen types` workaround. `--local` uses the
+published host port instead; `--db-url` must be host-reachable.
 
 ## Subprocesses
 

apps/cli/src/legacy/commands/gen/types/types.handler.ts

@@ -26,6 +26,7 @@ import {
   legacyReadDbToml,
 } from "../../../shared/legacy-db-config.toml-read.ts";
 import type { LegacyPgConnInput } from "../../../shared/legacy-db-connection.service.ts";
+import { legacyPflagStringValue } from "../../../shared/legacy-pflag-reconcile.ts";
 import { legacyTempPaths } from "../../../shared/legacy-temp-paths.ts";
 import { LegacyLinkedProjectCache } from "../../../telemetry/legacy-linked-project-cache.service.ts";
 import { LegacyTelemetryState } from "../../../telemetry/legacy-telemetry-state.service.ts";
@@ -42,6 +43,7 @@ import {
   defaultSchemas,
   localDbContainerId,
   localDbPassword,
+  legacyGenTypesNetworkIdUnusedWarning,
   parseQueryTimeoutSeconds,
 } from "./types.shared.ts";
 
@@ -444,6 +446,11 @@ export const legacyGenTypes = Effect.fn("legacy.gen.types")(function* (flags: Le
       }
     }
 
+    const networkIdOverride = legacyPflagStringValue(occurrences, "network-id");
+    if (Option.isSome(networkIdOverride)) {
+      yield* output.warn(legacyGenTypesNetworkIdUnusedWarning(networkIdOverride.value));
+    }
+
     if (flags.local) {
       const config = yield* legacyReadDbToml(fs, path, cliSettings.workdir);
       yield* legacyApplyProjectEnv(

apps/cli/src/legacy/commands/gen/types/types.integration.test.ts

@@ -1002,6 +1002,48 @@ describe("legacy gen types", () => {
     });
   });
 
+  it.live("warns that --network-id is unused and still generates", () => {
+    const dbUrl = "postgresql://postgres:postgres@db:5432/postgres";
+    const { layer, generator, out } = setup({
+      args: ["gen", "types", "--db-url", dbUrl, "--network-id", "mycompose_default"],
+    });
+
+    return Effect.gen(function* () {
+      yield* legacyGenTypes(defaultFlags({ dbUrl: Option.some(dbUrl) })).pipe(
+        Effect.provide(layer),
+      );
+
+      expect(generator.calls).toHaveLength(1);
+      expect(out.messages).toContainEqual(
+        expect.objectContaining({
+          type: "warn",
+          message: expect.stringContaining("docker run --rm --network mycompose_default"),
+        }),
+      );
+      expect(out.messages).toContainEqual(
+        expect.objectContaining({
+          type: "warn",
+          message: expect.stringContaining("npx --yes supabase gen types"),
+        }),
+      );
+    });
+  });
+
+  it.live("does not warn about --network-id when the flag is omitted", () => {
+    const dbUrl = "postgresql://postgres:postgres@127.0.0.1:5432/postgres";
+    const { layer, out } = setup({
+      args: ["gen", "types", "--db-url", dbUrl],
+    });
+
+    return Effect.gen(function* () {
+      yield* legacyGenTypes(defaultFlags({ dbUrl: Option.some(dbUrl) })).pipe(
+        Effect.provide(layer),
+      );
+
+      expect(out.messages.filter((message) => message.type === "warn")).toEqual([]);
+    });
+  });
+
   for (const scenario of nonTypescriptProjectRefScenarios) {
     it.live(`generates ${scenario.lang} types from a project ref through the DB resolver`, () => {
       const { layer, out, api, linkedProjectCache, dbConfig, generator } = setup({

apps/cli/src/legacy/commands/gen/types/types.shared.ts

@@ -87,3 +87,16 @@ export function applyProbedSslMode(
     ...(sslrootcert !== undefined && sslrootcert.length > 0 ? { sslrootcert } : {}),
   };
 }
+
+/**
+ * `--network-id` cannot attach the in-process generator to a Docker network.
+ * Point at a host-reachable DSN, or run the CLI inside that network.
+ */
+export function legacyGenTypesNetworkIdUnusedWarning(networkId: string): string {
+  const network = networkId.length > 0 ? networkId : "<network-id>";
+  return (
+    "--network-id is unused: gen types no longer runs inside a container and cannot join a Docker network.\n" +
+    "To reach a hostname that exists only on that network:\n" +
+    `  docker run --rm --network ${network} node:lts npx --yes supabase gen types --db-url <url>`
+  );
+}

apps/cli/src/legacy/commands/gen/types/types.unit.test.ts

@@ -7,6 +7,7 @@ import {
   applyProbedSslMode,
   applyQueryTimeouts,
   defaultSchemas,
+  legacyGenTypesNetworkIdUnusedWarning,
   localDbPassword,
   parseQueryTimeoutSeconds,
 } from "./types.shared.ts";
@@ -162,6 +163,19 @@ describe("schema and password helpers", () => {
   });
 });
 
+describe("legacyGenTypesNetworkIdUnusedWarning", () => {
+  it("names the unused flag and the docker run + npx workaround", () => {
+    const warning = legacyGenTypesNetworkIdUnusedWarning("mycompose_default");
+    expect(warning).toContain("--network-id is unused");
+    expect(warning).toContain("docker run --rm --network mycompose_default");
+    expect(warning).toContain("npx --yes supabase gen types --db-url <url>");
+  });
+
+  it("uses a placeholder when the flag value is empty", () => {
+    expect(legacyGenTypesNetworkIdUnusedWarning("")).toContain("--network <network-id>");
+  });
+});
+
 describe("oxfmt binding pin", () => {
   it("stays on the oxfmt version postgrest-typegen resolves", () => {
     const cliPackageJson = fileURLToPath(new URL("../../../../../package.json", import.meta.url));

apps/cli/src/legacy/shared/legacy-connect-errors.ts

@@ -31,10 +31,13 @@ export function legacyIpv6Suggestion(): string {
 // `ipv6LiteralPattern`: an IPv6 address in brackets
 // (Go dial form) or parens (libpq form). Run against the original-case message.
 const IPV6_LITERAL_PATTERN = /(?:\[[0-9a-fA-F:]+\]|\([0-9a-fA-F:]+\))/;
-// Node's dial-failure shape (`connect ENETUNREACH 2600:…:5432`). The port may be
-// followed by whitespace, end-of-string, or a closing paren — the connect-failure
-// message renders the driver cause parenthesized (pgconn `dial error (…)` form).
-const NODE_ENETUNREACH_PATTERN = /\benetunreach\s+([0-9a-fA-F:]+):\d+(?:[\s)]|$)/i;
+// Node's dial-failure shape (`connect EHOSTUNREACH 2600:…:5432`). The port may
+// be followed by whitespace, end-of-string, or a closing paren — the
+// connect-failure message renders the driver cause parenthesized (pgconn
+// `dial error (…)` form). ENETUNREACH / EHOSTUNREACH / EADDRNOTAVAIL are the
+// IPv6-unreachable errnos; LegacyDbConnectError keeps only this rendered text.
+const NODE_IPV6_DIAL_PATTERN =
+  /\b(?:enetunreach|ehostunreach|eaddrnotavail)\s+([0-9a-fA-F:]+):\d+(?:[\s)]|$)/i;
 
 /**
  * Port of `isIPv6ConnectivityError`. Lower-cases the
@@ -48,8 +51,8 @@ export function legacyIsIPv6ConnectivityError(message: string): boolean {
   if (lower.includes("address family for hostname not supported")) return true;
   if (lower.includes("no address associated with hostname")) return true;
   if (lower.includes("network is unreachable")) return true;
-  const nodeEnetunreachMatch = NODE_ENETUNREACH_PATTERN.exec(message);
-  if (nodeEnetunreachMatch?.[1] !== undefined) return isIPv6(nodeEnetunreachMatch[1]);
+  const nodeIpv6DialMatch = NODE_IPV6_DIAL_PATTERN.exec(message);
+  if (nodeIpv6DialMatch?.[1] !== undefined) return isIPv6(nodeIpv6DialMatch[1]);
   if (lower.includes("no route to host") || lower.includes("cannot assign requested address")) {
     return IPV6_LITERAL_PATTERN.test(message);
   }

apps/cli/src/legacy/shared/legacy-connect-errors.unit.test.ts

@@ -85,6 +85,21 @@ describe("legacyIsIPv6ConnectivityError", () => {
     ).toBe(true);
   });
 
+  it("classifies Node EHOSTUNREACH and EADDRNOTAVAIL stderr for IPv6 literals", () => {
+    expect(legacyIsIPv6ConnectivityError("connect EHOSTUNREACH 2600:1f18::1:5432")).toBe(true);
+    expect(legacyIsIPv6ConnectivityError("connect EADDRNOTAVAIL 2a05:d014::1:5432")).toBe(true);
+    expect(legacyIsIPv6ConnectivityError("connect EHOSTUNREACH 10.0.0.1:5432")).toBe(false);
+    expect(legacyIsIPv6ConnectivityError("connect EADDRNOTAVAIL 10.0.0.1:5432")).toBe(false);
+  });
+
+  it("classifies Node EHOSTUNREACH inside the parenthesized connect-failure rendering", () => {
+    expect(
+      legacyIsIPv6ConnectivityError(
+        "failed to connect to `host=db.x.supabase.co user=postgres database=postgres`: dial error (connect EHOSTUNREACH 2600:1f18::1:5432)",
+      ),
+    ).toBe(true);
+  });
+
   it("does not classify unrelated errors", () => {
     expect(legacyIsIPv6ConnectivityError("permission denied for schema public")).toBe(false);
     expect(legacyIsIPv6ConnectivityError("")).toBe(false);
@@ -601,6 +616,23 @@ describe("legacyIsIPv6ConnectivityErrorCause", () => {
     ).toBe(true);
   });
 
+  it("classifies the native rendered EHOSTUNREACH connect error without structured fields", () => {
+    expect(
+      legacyIsIPv6ConnectivityErrorCause(
+        new Error(
+          "failed to connect to postgres: failed to connect to `host=db.x.supabase.co user=postgres database=postgres`: dial error (connect EHOSTUNREACH 2600:1f18::1:5432)",
+        ),
+      ),
+    ).toBe(true);
+    expect(
+      legacyIsIPv6ConnectivityErrorCause(
+        new Error(
+          "failed to connect to postgres: failed to connect to `host=db.x.supabase.co user=postgres database=postgres`: dial error (connect EADDRNOTAVAIL 2a05:d014::1:5432)",
+        ),
+      ),
+    ).toBe(true);
+  });
+
   it("classifies the native rendered ENOTFOUND connect error", () => {
     expect(
       legacyIsIPv6ConnectivityErrorCause(