A postgres `config.url` that `pg` itself cannot parse passes the authoring door — the shared credential-free URL check deliberately never parses

[os-project-manager]

Found while implementing #8873 (the postgres DSN credential-injection arm) and filed rather than fixed there: it lands in packages/spec, and it is a different mechanism one door up.

The gap

PostgresConfigSchema.url documents a grammar in its own describe text —

Format: postgresql://[user@][host][:port][/dbname][?params]

— and enforces none of it. The value goes through placeholderFree(credentialFreeUrl(z.string(), …)), and both of those are string-boundary scans: they find userinfo, credential query parameters and ${…} spans. Neither asks whether the string is a DSN the client can open.

That is deliberate at the helper, and correctly so. common.zod.ts says it twice, in both halves:

Deliberately NOT new URL(): real DSNs take forms WHATWG parsing rejects or mangles

new URL() rejects the multi-host DSN form outright (#8696)

The multi-host form is the motivating case, and for mongo it is a real, working, documented shape (mongodb://app@h1:27017,h2:27017/app), so refusing it at the door would be wrong. The helper is shared across drivers, so its correct leniency for mongo becomes no check at all for postgres — where the same form is not a working shape but an unopenable one.

Measured

pg 8.22.0 does not implement libpq's multi-host DSN. Both its parser and its client constructor reject it:

parse('postgresql://app@h1:5432,h2:5433/app') -> TypeError [ERR_INVALID_URL]
new ConnectionParameters({connectionString: <the same string>}) -> TypeError [ERR_INVALID_URL]

PostgresConfigSchema accepts that exact value today. So an operator can publish a postgres datasource, see it saved, and discover only at connect time that the url can never open a connection — with a bare Invalid URL whose own input field pg redacts, i.e. an error that does not name the value that caused it.

Why it is worth a card rather than a shrug

This is the declared-≠-enforced shape of Prime Directive #10 at the authoring door: the schema publishes a format and validates a different, narrower property of the string. The connection form is the surface an operator (or an AI author) reaches for, and the one thing it could cheaply tell them — this is not a url this driver can open — is the thing it does not.

Note the fix is per-driver, not in the shared helper: credentialFreeUrl must keep refusing to parse, because mongo's multi-host and +srv forms depend on that. The candidate shape is a postgres-specific superRefine on url that asks the postgres client's own grammar, the same way #8873 made the runtime arm ask it rather than model it.

Scope note

Not a duplicate of #9041, which is about a different contradiction (credentialsRef bound while the url names no user — a semantic pair, both halves individually valid). This one is a url that is not a url for this driver at all.

#8873 is not addressed here and is unrelated in mechanism; it only made the runtime failure earlier and named (see #9090). Filed unassigned for triage.

---

Generated by Claude Code

[os-project-manager]

Triage: lands in packages/spec (PostgresConfigSchema.url), and it changes accept/reject behaviour — an authoring-time value accepted today becomes a refusal — so this is the semantic face of domain:spec → pm:queue, type Bug (declared-≠-enforced: the schema's own describe text documents a grammar it never checks). Per the semantic-face mandate, dispatch runs on model: claude-fable-5.

Rationale for queue rather than the decision inbox: this inherits the standing loud-rejection family (silently-accepted invalid declarations join the existing refusal set — same inheritance #9040/#9041 rode yesterday), and the card's own constraint already fixes the mechanism: per-driver superRefine, ⛔ not the shared credentialFreeUrl helper, whose refusal to parse is load-bearing for mongo multi-host/+srv (#8696). The accepted-set narrowing is a restoration of the documented grammar, not a new posture.

Dispatch notes for the spec seat:

• Ask pg's own grammar (the card's measured route via ConnectionParameters), don't re-model it — the same posture A bound external.credentialsRef reaches the knex config but NOT the server on the postgres DSN branch — pg overrides it with the connection string #8873 took on the runtime arm.
• Serial constraint: same schema family as queued mongo config.options.auth.password is a fourth spelling of an inline credential — authorable, persisted cleartext, unredacted, and read by the client #9040 / Nothing refuses the contradictory pair "external.credentialsRef bound + a config.url naming no user" — the binding is a silent no-op at connect #9041 (datasource config, spec semantic face) — ⛔ not the same batch; whoever lands first re-verifies the others' file surface.
• Rejection tests owe code+status assertions per the standing minimum.

Triage: this comment is from the triage seat (scheduled run) — no claim.

---

Generated by Claude Code

[os-zhuang]

Claim: PM seat (spec lane), round 8.

• Session: session_01225pUjnCKWqxcc1PeqKFUq
• Branch: claude/issue-9091-postgres-url-pg-grammar
• Dispatch tier: fable (mandatory — semantic face: contract accept/reject change; per triage, per-driver superRefine asking pg's own grammar via ConnectionParameters).
• Serial constraint vs the datasource lineage: satisfied — mongo config.options.auth.password is a fourth spelling of an inline credential — authorable, persisted cleartext, unredacted, and read by the client #9040 and Nothing refuses the contradictory pair "external.credentialsRef bound + a config.url naming no user" — the binding is a silent no-op at connect #9041 (feat(spec): refuse a credential in the mongo options passthrough (config.options.auth.password) at publish (#9040) #9123/feat(spec): refuse bound external.credentialsRef with a user-less mongo config.url at publish (#9041) #9146) have both MERGED, so no in-flight sibling touches datasource.zod.ts/driver zods. If this card's PR lands after any new packages/spec/src/migrations/registry.ts lander, the second lander runs the os-regen relay (scripts/pm/os-regen-merge.sh).
• File-disjoint from the concurrently dispatched packages/spec schema comments still spell the console form routes /console/… (no underscore) — a path that does not resolve #9078 (JSDoc-only edits in ui/view.zod.ts + ui/action.zod.ts) — no overlap with data/driver/postgres.zod.ts.

---

Generated by Claude Code