feat(cli): generate types natively against the selected stack (CLI-2366)

[Coly010]

Summary

gen types no longer spawns a postgres-meta container. Introspection and code generation run
in-process through @supabase/postgrest-typegen
over a direct PostgreSQL connection.

This is what --local on the managed stack needs: the stack exposes no pg-meta capability, and it
supports a native runtime with no container engine at all, so the old path required a Docker daemon
to generate types for a database that isn't in Docker. #6540 already resolved the stack's real
endpoint here; this removes the container that resolution still fed.

Generation goes through the shared DbConnection seam that db query uses, so there is no second
driver path — TLS mode, DoH resolution, pooler fallback and connect-error classification are the
ones already in place.

TLS. The SSL probe is gone. Linked, project-ref and preview-branch targets are known Supabase
hosts and pin the bundled CA with sslmode=require, preserving the stricter posture gen types
already had. --db-url honours the DSN's own sslmode/sslrootcert and otherwise pins only for
known Supabase hosts; --local stays plaintext. PgConnInput gains an optional inline-CA field so
pinning needs no temp file.

--query-timeout now maps to a server-enforced statement_timeout rather than a container env
var, so a stalled introspection is aborted by the server rather than only client-side.

Behaviour changes

--network-id is rejected on this command. In-process generation cannot join a Docker network.
Both argv positions are covered, including the persistent form before the command path.

A --db-url pointing at a plain-TCP server now needs ?sslmode=disable. The shared connection
layer intentionally does not downgrade from prefer to plaintext, and gen types no longer probes.
This matches every other --db-url command; a connect-error suggestion names the fix.

Generated output, measured against postgres-meta v0.99.0 on the same schema:

Language	Result
Go	byte-identical
Swift	byte-identical
TypeScript	a NOT NULL jsonb column is NonNullable<Json> rather than Json
Python	jsonb columns are JsonValue rather than Json[Any]; NotRequired/TypeAlias import from typing_extensions

Both differences are upstream corrections: the old TypeScript type admitted null for a NOT NULL
column, and pydantic's Json[Any] expects an unparsed JSON string rather than a decoded row
value. --linked/--project-id TypeScript is generated server-side by the Management API and is
unaffected, so it can differ from local output on these jsonb cases until the hosted service adopts
the same engine. Recorded in the command's SIDE_EFFECTS.md.

Credit

Supersedes #6404 by @avallete, which first proved this out and worked through the
bun build --compile problems with oxfmt — the optional-plugin externals and the statically
embedded napi binding here are that PR's design. Restarted from develop because #6525 moved every
path it touched.

Linked issue

Resolves CLI-2366. Also covers
CLI-2279 (no GitHub issue).

• The linked issue is open and carries the open-for-contribution label (or I'm a Supabase maintainer).

Checklist

• The PR title follows Conventional Commits (e.g. fix(cli): …).
• Tests added or updated for the change.
• From the repository root, pnpm check:all passes; relevant package tests pass for every touched workspace, and pnpm types:check passes for each touched TypeScript workspace (or workspace declaring it).

🤖 Generated with Claude Code

[github-actions]

🤖 AI Review

Verified all 14 reported findings and merged them into 11 distinct entries. Nine are confirmed and two are refuted by documented existing behavior or repository conventions. The most significant confirmed issue is the immediate connection failure caused by timeouts that round to zero.

Findings

Severity	Location	Category	Sources	Claim
🟠 MAJOR	apps/cli/src/commands/gen/types/types.handler.ts:296	timeout-handling	claude+codex	Accepted timeout values below 500ms round to zero, causing the connection probe to time out immediately and disabling PostgreSQL's statement timeout.
🟡 MINOR	apps/cli/src/commands/gen/types/types.oxfmt.ts:71	platform-support	claude+codex	Source runs and build:binary builds on musl Linux select the incompatible glibc oxfmt binding.
🟡 MINOR	apps/cli/src/commands/gen/types/SIDE_EFFECTS.md:17	documentation	claude	The side-effect contract omits configuration, dotenv, libpq environment, and conditional service-file inputs now used by the --db-url path, including when schemas are explicit.
🟡 MINOR	apps/cli/src/commands/gen/types/types.handler.ts:499	compatibility	claude	The command now hard-fails whenever the persistent --network-id flag is present, breaking callers that previously used or globally supplied that supported flag.
🟡 MINOR	apps/cli/src/commands/gen/types/types.generator.layer.ts:44	cancellation	claude	Each introspection query is run in a separate Promise-backed root fiber, so interrupting generation does not interrupt the in-flight session query before the enclosing scope closes its pool.
🟡 MINOR	apps/cli/src/command-internal/connect-errors.ts:375	error-message	codex	The TLS failure suggestion tells users to append syntax that is invalid for URLs with existing query parameters and for keyword-style connection strings.
⚪ NIT	apps/cli/tsconfig.types.json:6	documentation	claude+codex	The type-check overlay points readers to a nonexistent generator integration test.
⚪ NIT	apps/cli/src/commands/gen/types/types.integration.test.ts:850	comments	codex	The newly added test section banners violate the repository's trusted comment convention.
⚪ NIT	apps/cli/src/command-internal/db-connection.sql-pg.layer.ts:684	documentation	claude	The CA-loading comment describes only sslrootcert file loading and omits the new higher-precedence inline CA branch and its different gate.

Findings outside the diff

• ⚪ NIT apps/cli/src/command-internal/db-connection.sql-pg.layer.ts:684 — The CA-loading comment describes only sslrootcert file loading and omits the new higher-precedence inline CA branch and its different gate.

Refuted findings (kept for transparency, not posted as review comments)

• apps/cli/src/commands/gen/types/types.handler.ts:295 (timeout-handling): The default query-timeout unintentionally overrides timeout settings supplied through the DSN, service configuration, or environment.
  Refuted: This is the command's established timeout contract, not an accidental override. trusted/apps/cli/src/commands/gen/types/SIDE_EFFECTS.md:150 documents a default 15-second maximum, and the previous implementation unconditionally passed that value as both PG_CONN_TIMEOUT_SECS and PG_QUERY_TIMEOUT_SECS at trusted/apps/cli/src/commands/gen/types/types.handler.ts:456-457. The new documentation likewise explicitly states that the default applies as both connection and statement timeouts at apps/cli/src/commands/gen/types/SIDE_EFFECTS.md:171-176.
• apps/cli/src/commands/gen/types/types.handler.ts:96 (correctness): isPoolerHost is accidentally broader than the repository's intended pooler-domain validation because it accepts any subdomain under the configured registrable domain.
  Refuted: The repository defines poolerHost specifically as the required eTLD+1 ownership boundary at apps/cli/src/command-internal/profile.ts:18-23, and the existing pooler connection validator deliberately performs the same getDomain comparison at apps/cli/src/command-internal/db-config.parse.ts:405-413. Matching subdomains is therefore the documented convention.

Stats

Claude findings: 9 · Codex findings: 5 · Confirmed: 9 · Refuted: 2 · Uncertain: 0

---

Models: claude-opus-5 + gpt-5.6-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

[jgoux]

Two verified regressions remain after independent review and cross-review.

[avallete]

issue (blocking): Three regressions remain on 5b15cdd91

In-process --local generation dogfoods clean against the stack-engine matrix: compose, docker eager, docker lazy, and native all exit 0; native still works with Docker off PATH (no pg-meta container); --network-id rejects; --query-timeout 400ms succeeds; staging --linked TypeScript (Management API) and Go (direct connect) succeed.

The remaining blockers are inline: @jgoux's two [P2]s (pooler classification dropping driver cause/code/address, and pnpm cli-release missing the oxfmt externals) plus one more — --db-url classified as local silently ignores explicit sslmode.

[Coly010]

All three blockers from @avallete's review are now addressed, plus the earlier AI-review round.

Finding	Status	Commit
@jgoux — pooler classification dropped the driver cause/code/address	fixed	cee59507c
@jgoux — pnpm cli-release missing the oxfmt externals	fixed	cee59507c
@avallete — --db-url classified local silently ignored explicit sslmode	fixed	967878c85

Two of these were real regressions introduced by routing generation through DbConnection, and both were invisible to my own tests — the pooler tests only passed because they fabricated errors that happened to classify true. They now build failures through the real toConnectError, and the TLS coverage asserts whether an SSLRequest actually reaches the wire rather than inspecting config shape.

@avallete — thank you for the dogfooding matrix; that is far better evidence than anything I could produce locally, particularly native-with-Docker-off-PATH, which is the case this change exists for.

One item from the AI round remains open by choice rather than oversight: both bots wanted --network-id to warn-and-ignore instead of failing. I kept the hard error, reasoning on that thread — for a network-only database, ignoring the flag fails the connection anyway but with a worse message, and preserving the capability would mean keeping the whole container path alive for one flag. Happy to revisit if either of you disagrees.

Also unchanged and worth a second opinion before merge: the jsonb output deltas in the description. Go and Swift stay byte-identical; TypeScript and Python shift on jsonb columns because the library corrected two upstream bugs. --linked TypeScript is served by hosted postgres-meta and so will disagree with local output until that service adopts the same engine.

Stale + Julien re-reviewed

[avallete]

issue (blocking): tlsExplicitlyRequested is a regression on local --db-url

The follow-up in 967878c85 correctly stopped ignoring sslmode=require / verify-full on a loopback TLS tunnel. The predicate it added is too broad: any populated sslmode lifts the local plaintext exemption, including libpq prefer and a PGSSLMODE fill-in the DSN never set. That makes a previously working local --db-url fail TLS against plaintext Postgres, and it is on the shared DbConnection seam so db query / dump / pull are in the blast radius too.

Inline: how to reproduce and the smallest fix.

[avallete]

issue (blocking): this is a regression of local --db-url (and every other DbConnection command), not just a too-eager helper.

967878c85 was meant to honor an explicit TLS demand on a target classified local — a TLS tunnel on 127.0.0.1 with sslmode=require / verify-full / sslrootcert. That part is right: before this commit, sslConfigsFor returned [false] whenever isLocal was true, so the DSN’s TLS settings never reached the wire.

The predicate as written treats any defined sslmode as that demand:

cfg.sslmode !== undefined || sslrootcert || sslrootcertInline

That is not the same as “the DSN asked for TLS”. Two realistic inputs now lift the exemption and then hit TLS-only dialing (sslConfigsFor maps prefer / unset to TLS with no plaintext fallback, isLocal && !explicitTls at the acquisition site):

1. ?sslmode=prefer on a loopback DSN. libpq prefer means try TLS, then plaintext. This CLI has never implemented that fallback — prefer is TLS-only — but local classification previously forced plaintext before that mapping ran. After this commit, prefer is “explicit TLS” and the local Postgres that does not speak SSL fails with a handshake error instead of connecting.
2. PGSSLMODE (or a service-file sslmode) with no sslmode in the DSN. parseConnectionString copies those into cfg.sslmode when the URL omits it (db-config.parse.ts, URL and keyword parsers). A developer with PGSSLMODE=prefer (or require) in the environment, then gen types --db-url postgresql://postgres:postgres@127.0.0.1:54322/postgres, now fails against the local stack. The same path is used by db query --db-url and anything else that goes through acquirePgPoolConnection.

That is a behavior change from 5b15cdd91 / pre-exemption-fix: a classified-local DSN with no TLS keys in the URL connected in plaintext. It is also wider than the bug that was filed — a missing sslmode=require on a TLS loopback tunnel. sslmode=disable happens to still work only because sslConfigsFor special-cases it after the exemption is already gone.

Dogfood on this SHA confirmed the intended tunnel case: compose and native loopback with a bare DSN and with sslmode=disable still connect; sslmode=require against plaintext Postgres now fail-closes (SSLRequest on the wire). The hole is the prefer / env-filled sslmode case, which this helper cannot distinguish from require.

Smallest fix: treat TLS as explicitly requested only for require / verify-ca / verify-full, or when sslrootcert / an inline CA is set. Leave prefer / allow / unset / env-filled prefer on a local target as plaintext. That keeps the TLS-tunnel fix and restores the local --db-url that used to work.

[Coly010]

You are right, and this landed before I saw the review — follow-up in #6664.

Your diagnosis is exact, and the PGSSLMODE half is the part I got wrong twice: I noted the ambient-env risk while designing the predicate, convinced myself it was acceptable because libpq would also honour it, and missed that prefer is the common ambient value and that this CLI maps prefer to TLS-only with no fallback. Treating "has an sslmode" as "demands TLS" conflated a fallback description with a demand.

#6664 narrows it to require / verify-ca / verify-full, or a supplied sslrootcert / inline CA — your smallest fix.

Reproduced the regression against a plaintext Postgres on the local-classified port, before and after, same database:

Connection	merged develop	#6664
bare loopback DSN	connects	connects
PGSSLMODE=prefer	fails	connects
PGSSLMODE=allow	fails	connects
?sslmode=prefer	fails	connects
?sslmode=disable	connects	connects
?sslmode=require	fails closed	fails closed
PGSSLMODE=verify-full	fails closed	fails closed

The tunnel case from the previous round is unchanged — an explicit demand still puts an SSLRequest on the wire against a loopback target, and a root cert still opens the CA gate.

On test coverage: the unit tests I shipped last round actively asserted the broad behaviour (including sslmode=disable counting as a demand), so they encoded the bug rather than catching it. Those assertions are corrected, and there is now a test that runs the real DSN parser with a PGSSLMODE env fill-in into the predicate, so the env-sourced case is covered end to end instead of reasoned about.

[Coly010]

Merged before @avallete's second review landed — the regression it identifies is real and is fixed in #6664.

tlsExplicitlyRequested treated any populated sslmode as a TLS demand. prefer/allow describe a fallback this CLI does not implement, and sslmode is also filled from PGSSLMODE and libpq service files, so an ambient PGSSLMODE=prefer broke local --db-url across db query, dump and pull as well as gen types. #6664 narrows the predicate to require/verify-ca/verify-full or a supplied root cert, with a before/after matrix against a plaintext local Postgres.