neon 3.1.0 → 3.2.0

package/dist/_chunks/psql-DWH-kc69.js

@@ -0,0 +1,2169 @@
+import { createCondStack } from "../psql/command/cmd_cond.js";
+import { setStartupVars, syncConnectionVars } from "../psql/core/syncVars.js";
+import { PgConnection } from "../psql/wire/connection.js";
+import { helpVariables, slashUsage, usage } from "../psql/core/help.js";
+import { defaultRegistry } from "../psql/command/dispatch.js";
+import { runMainLoop } from "../psql/core/mainloop.js";
+import { applyEnvOverrides, defaultSettings } from "../psql/core/settings.js";
+import { loadPgPass, lookupPgPass } from "../psql/io/pgpass.js";
+import { createVarStore } from "../psql/core/variables.js";
+import { loadPgServices } from "../psql/io/pgservice.js";
+import { executeInputString, loadPsqlrc } from "../psql/io/psqlrc.js";
+import { existsSync, promises } from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+//#region src/psql/core/startup.ts
+/**
+* psql startup-args parser + applier.
+*
+* TypeScript port of `parse_psql_options()` / the top of `main()` in
+* `src/bin/psql/startup.c`. Two responsibilities:
+*
+*   1. `parseStartupArgs(argv)` — hand-written getopt_long-equivalent that
+*      walks the argv array once, decoding short (`-c`) and long (`--command`)
+*      options, and accumulates an ordered list of `-c`/`-f` actions plus a
+*      bag of settings flags. Positional arguments follow the upstream
+*      `[DBNAME [USERNAME]]` rule.
+*
+*      We hand-roll the parser instead of pulling in `yargs` (or similar)
+*      because upstream psql has subtle precedence rules — actions are
+*      ordered, `-v NAME` without `=` deletes the variable, `-X` interacts
+*      with `.psqlrc` discovery, etc. The parser stays under ~250 LOC and is
+*      fully covered by unit tests.
+*
+*   2. `applyStartupArgs(args, settings, baseConnect)` — mutates `settings`
+*      (and its var store) in-place to reflect parsed flags, then returns
+*      the connect options the caller should use plus the ordered list of
+*      pre-REPL actions to execute (currently just `-c` / `-f`).
+*
+* Out-of-scope for WP-26 but the table mentions them so they're listed below:
+*   - `-1` / `--single-transaction` — we accept and record on the args but
+*     do not wire its semantics in the caller. Tracked for a follow-up.
+*   - `-C` — accepted as a no-op (since-PG17 connection-check skip).
+*   - `-l` / `--list` — recorded; the caller may use it later to short-circuit
+*     the REPL with a `\l` and exit. Not wired here.
+*   - `-L logfile`, `-o output` — recorded on args. Routing into the printer
+*     is owned by other WPs (logfile streaming and output redirection).
+*   - `--help[=topic]` — returns a ParseError with `kind: 'help'` and the
+*     help text already rendered as `message`. Caller writes and exits 0.
+*   - `-V` / `--version` — returns `kind: 'version'` with the version string.
+*     Caller writes and exits 0.
+*
+* Help/version text is rendered through `./help.ts` so the formatting stays
+* in lock-step with `\?` output (WP-18). The version string mirrors upstream
+* `psql (PostgreSQL) PG_VERSION` and is currently hard-coded — the embedded
+* psql doesn't have a build-system PG_VERSION constant. A follow-up could
+* surface the real PG version from a const, but for now we expose the
+* embedded build's version label.
+*/
+/** Short options that consume the next argv slot (or attached value). */
+const SHORT_WITH_ARG = /* @__PURE__ */ new Set([
+	"c",
+	"d",
+	"f",
+	"F",
+	"h",
+	"L",
+	"o",
+	"p",
+	"P",
+	"R",
+	"T",
+	"U",
+	"v"
+]);
+/** Short flags (no argument). */
+const SHORT_NO_ARG = /* @__PURE__ */ new Set([
+	"a",
+	"A",
+	"b",
+	"C",
+	"e",
+	"E",
+	"H",
+	"l",
+	"n",
+	"q",
+	"s",
+	"S",
+	"t",
+	"V",
+	"w",
+	"W",
+	"x",
+	"X",
+	"z",
+	"0",
+	"1",
+	"?"
+]);
+/** Long option → canonical short equivalent (or sentinel string). */
+const LONG_MAP = {
+	"echo-all": "a",
+	"no-align": "A",
+	command: "c",
+	dbname: "d",
+	"echo-queries": "e",
+	"echo-errors": "b",
+	"echo-hidden": "E",
+	file: "f",
+	"field-separator": "F",
+	"field-separator-zero": "z",
+	host: "h",
+	html: "H",
+	list: "l",
+	"log-file": "L",
+	"no-readline": "n",
+	"single-transaction": "1",
+	output: "o",
+	port: "p",
+	pset: "P",
+	quiet: "q",
+	"record-separator": "R",
+	"record-separator-zero": "0",
+	"single-step": "s",
+	"single-line": "S",
+	"tuples-only": "t",
+	"table-attr": "T",
+	username: "U",
+	set: "v",
+	variable: "v",
+	version: "V",
+	"no-password": "w",
+	password: "W",
+	expanded: "x",
+	"no-psqlrc": "X",
+	"no-pager": "__no_pager__",
+	"on-error-stop": "__on_error_stop__",
+	help: "__help__",
+	csv: "__csv__"
+};
+/** Long options that REQUIRE an attached value (or one in the next argv). */
+const LONG_WITH_ARG = /* @__PURE__ */ new Set([
+	"command",
+	"dbname",
+	"file",
+	"field-separator",
+	"host",
+	"log-file",
+	"output",
+	"port",
+	"pset",
+	"record-separator",
+	"table-attr",
+	"username",
+	"set",
+	"variable"
+]);
+/** Long options whose value is optional (only attached with `=`). */
+const LONG_OPTIONAL_ARG = /* @__PURE__ */ new Set(["help", "echo-hidden"]);
+const blankArgs = () => ({
+	actions: [],
+	variables: [],
+	noPsqlrc: false,
+	noReadline: false,
+	echoAll: false,
+	echoHidden: "off",
+	echoErrors: false,
+	echoQueries: false,
+	quiet: false,
+	singleline: false,
+	singlestep: false,
+	noAlign: false,
+	noPager: false,
+	htmlMode: false,
+	tuplesOnly: false,
+	expanded: false,
+	csvOutput: false,
+	onErrorStop: false,
+	fieldSepZero: false,
+	recordSepZero: false,
+	pset: [],
+	list: false,
+	singleTransaction: false,
+	help: false,
+	version: false,
+	positional: []
+});
+const renderToString = (fn) => {
+	const chunks = [];
+	fn({ write(chunk) {
+		chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+		return true;
+	} });
+	return chunks.join("");
+};
+const renderHelp = (topic) => {
+	if (topic === void 0 || topic === "options") return renderToString((out) => {
+		usage(out);
+	});
+	if (topic === "commands") return renderToString((out) => {
+		slashUsage(out, false);
+	});
+	if (topic === "variables") return renderToString((out) => {
+		helpVariables(out);
+	});
+	return "";
+};
+/**
+* Version label for the embedded TypeScript psql. This is the "client"
+* identifier — the analogue of upstream psql's compiled-in `PG_VERSION`.
+* The embedded psql is not a real PostgreSQL build, so we track our own
+* implementation version here. It seeds the `VERSION_NAME` psql var (and,
+* via {@link setStartupVars}, the numeric `VERSION_NUM`); keep it as a
+* `MAJOR.MINOR.PATCH` string so the numeric mapping stays meaningful. Bump
+* alongside meaningful behaviour changes to the embedded psql.
+*/
+const CLIENT_VERSION = "1.0.0";
+const VERSION_STRING = `psql (PostgreSQL) embedded-ts (neon ${CLIENT_VERSION})`;
+const pushAction = (acts, a) => {
+	acts.push(a);
+};
+const pushVariable = (vars, raw) => {
+	const eq = raw.indexOf("=");
+	if (eq < 0) {
+		vars.push({
+			name: raw,
+			value: ""
+		});
+		return;
+	}
+	vars.push({
+		name: raw.slice(0, eq),
+		value: raw.slice(eq + 1)
+	});
+};
+/**
+* `-d VALUE` resolution. libpq accepts three shapes for the value:
+*
+*   1. Bare database name (no `=`, no `postgres[ql]://` prefix) — set
+*      `args.database` directly. This is by far the common case.
+*   2. Connection URI (`postgresql://…` / `postgres://…`) — parse it and
+*      lift the fields it specifies onto `args` (host, port, user, etc.).
+*   3. Conninfo key=value pairs separated by whitespace — same, but parsed
+*      via `parseConninfo`.
+*
+* The test corpus for upstream `001_basic.pl` uses shape (3) to open a
+* walsender connection: `-d "dbname=postgres replication=database"`. We
+* fold any conninfo-only fields (currently only `replication`) onto a
+* dedicated `args.replication` slot that `applyStartupArgs` threads into
+* `ConnectOptions.replication`.
+*/
+const applyDashD = (args, value) => {
+	if (!looksLikeConnectionString(value)) {
+		args.database = value;
+		return;
+	}
+	const parsed = value.startsWith("postgresql://") || value.startsWith("postgres://") ? parseConnectionUriPartial(value) : parseConninfo(value);
+	args.dashD = {
+		...args.dashD ?? {},
+		...parsed
+	};
+	if (parsed.host !== void 0 && args.host === void 0) args.host = parsed.host;
+	if (parsed.port !== void 0 && args.port === void 0) args.port = parsed.port;
+	if (parsed.user !== void 0 && args.user === void 0) args.user = parsed.user;
+	if (parsed.password !== void 0 && args.password === void 0) args.password = parsed.password;
+	if (parsed.database !== void 0 && args.database === void 0) args.database = parsed.database;
+	if (parsed.replication !== void 0) args.replication = parsed.replication;
+};
+const parseStartupArgs = (argv) => {
+	const args = blankArgs();
+	const actions = [];
+	const variables = [];
+	const pset = [];
+	let i = 0;
+	const n = argv.length;
+	const needValue = (flagDisplay) => {
+		if (i + 1 >= n) return {
+			kind: "missing-arg",
+			message: `option requires an argument -- ${flagDisplay}`
+		};
+		i += 1;
+		return argv[i];
+	};
+	const applyShort = (letter, attachedValue, flagDisplay) => {
+		const takesArg = SHORT_WITH_ARG.has(letter);
+		let value;
+		if (takesArg) if (attachedValue !== void 0) value = attachedValue;
+		else {
+			const v = needValue(flagDisplay);
+			if (typeof v !== "string") return v;
+			value = v;
+		}
+		else if (attachedValue !== void 0) return {
+			kind: "invalid-option",
+			message: `option does not take an argument -- ${letter}`
+		};
+		switch (letter) {
+			case "a":
+				args.echoAll = true;
+				return null;
+			case "A":
+				args.noAlign = true;
+				return null;
+			case "b":
+				args.echoErrors = true;
+				return null;
+			case "C": return null;
+			case "c":
+				pushAction(actions, {
+					kind: "command",
+					sql: value
+				});
+				return null;
+			case "d":
+				applyDashD(args, value);
+				return null;
+			case "e":
+				args.echoQueries = true;
+				return null;
+			case "E":
+				args.echoHidden = "on";
+				return null;
+			case "f":
+				pushAction(actions, {
+					kind: "file",
+					path: value
+				});
+				return null;
+			case "F":
+				args.fieldSep = value;
+				args.fieldSepZero = false;
+				return null;
+			case "h":
+				args.host = value;
+				return null;
+			case "H":
+				args.htmlMode = true;
+				return null;
+			case "l":
+				args.list = true;
+				return null;
+			case "L":
+				args.log = value;
+				return null;
+			case "n":
+				args.noReadline = true;
+				return null;
+			case "o":
+				args.output = value;
+				return null;
+			case "p": {
+				const p = Number.parseInt(value, 10);
+				if (!Number.isFinite(p) || p <= 0 || p > 65535) return {
+					kind: "invalid-value",
+					message: `invalid port number: "${value}"`
+				};
+				args.port = p;
+				return null;
+			}
+			case "P":
+				pset.push(value);
+				return null;
+			case "q":
+				args.quiet = true;
+				return null;
+			case "R":
+				args.recordSep = value;
+				args.recordSepZero = false;
+				return null;
+			case "s":
+				args.singlestep = true;
+				return null;
+			case "S":
+				args.singleline = true;
+				return null;
+			case "t":
+				args.tuplesOnly = true;
+				return null;
+			case "T":
+				pset.push(`tableattr=${value}`);
+				return null;
+			case "U":
+				args.user = value;
+				return null;
+			case "v":
+				pushVariable(variables, value);
+				return null;
+			case "V": return {
+				kind: "version",
+				message: VERSION_STRING
+			};
+			case "w":
+				args.promptPassword = false;
+				return null;
+			case "W":
+				args.promptPassword = true;
+				return null;
+			case "x":
+				args.expanded = true;
+				return null;
+			case "X":
+				args.noPsqlrc = true;
+				return null;
+			case "z":
+				args.fieldSepZero = true;
+				return null;
+			case "0":
+				args.recordSepZero = true;
+				return null;
+			case "1":
+				args.singleTransaction = true;
+				return null;
+			case "?": return {
+				kind: "help",
+				message: renderHelp(void 0)
+			};
+			default: return {
+				kind: "invalid-option",
+				message: `invalid option -- ${letter}`
+			};
+		}
+	};
+	while (i < n) {
+		const tok = argv[i];
+		if (tok === "--") {
+			i += 1;
+			while (i < n) {
+				args.positional.push(argv[i]);
+				i += 1;
+			}
+			break;
+		}
+		if (tok.startsWith("--")) {
+			const eq = tok.indexOf("=");
+			const name = eq < 0 ? tok.slice(2) : tok.slice(2, eq);
+			const attached = eq < 0 ? void 0 : tok.slice(eq + 1);
+			if (name === "csv") {
+				if (attached !== void 0) return {
+					kind: "invalid-option",
+					message: `option does not take an argument: --${name}`
+				};
+				args.csvOutput = true;
+				i += 1;
+				continue;
+			}
+			if (name === "no-pager") {
+				if (attached !== void 0) return {
+					kind: "invalid-option",
+					message: `option does not take an argument: --${name}`
+				};
+				args.noPager = true;
+				i += 1;
+				continue;
+			}
+			if (name === "on-error-stop") {
+				if (attached !== void 0) return {
+					kind: "invalid-option",
+					message: `option does not take an argument: --${name}`
+				};
+				args.onErrorStop = true;
+				variables.push({
+					name: "ON_ERROR_STOP",
+					value: "on"
+				});
+				i += 1;
+				continue;
+			}
+			if (name === "help") {
+				const topic = attached;
+				if (topic !== void 0 && topic !== "options" && topic !== "commands" && topic !== "variables") return {
+					kind: "invalid-option",
+					message: `unrecognized help topic: ${topic}`
+				};
+				return {
+					kind: "help",
+					message: renderHelp(topic)
+				};
+			}
+			if (name === "echo-hidden") {
+				if (attached === void 0) args.echoHidden = "on";
+				else if (attached === "noexec") args.echoHidden = "noexec";
+				else if (attached === "" || attached === "on") args.echoHidden = "on";
+				else return {
+					kind: "invalid-value",
+					message: `invalid value for --echo-hidden: "${attached}"`
+				};
+				i += 1;
+				continue;
+			}
+			const short = LONG_MAP[name];
+			if (short === void 0) return {
+				kind: "invalid-option",
+				message: `unrecognized option: --${name}`
+			};
+			const requiresArg = LONG_WITH_ARG.has(name);
+			const optionalArg = LONG_OPTIONAL_ARG.has(name);
+			let value = attached;
+			if (requiresArg && value === void 0) {
+				if (i + 1 >= n) return {
+					kind: "missing-arg",
+					message: `option requires an argument: --${name}`
+				};
+				i += 1;
+				value = argv[i];
+			} else if (!requiresArg && !optionalArg && value !== void 0) return {
+				kind: "invalid-option",
+				message: `option does not take an argument: --${name}`
+			};
+			const err = applyShort(short, value, `--${name}`);
+			if (err) return err;
+			i += 1;
+			continue;
+		}
+		if (tok.startsWith("-") && tok.length > 1) {
+			let k = 1;
+			while (k < tok.length) {
+				const letter = tok[k];
+				if (!SHORT_WITH_ARG.has(letter) && !SHORT_NO_ARG.has(letter)) return {
+					kind: "invalid-option",
+					message: `invalid option -- ${letter}`
+				};
+				if (SHORT_WITH_ARG.has(letter)) {
+					const remainder = tok.slice(k + 1);
+					const err = applyShort(letter, remainder.length > 0 ? remainder : void 0, letter);
+					if (err) return err;
+					k = tok.length;
+					break;
+				}
+				const err = applyShort(letter, void 0, letter);
+				if (err) return err;
+				k += 1;
+			}
+			i += 1;
+			continue;
+		}
+		args.positional.push(tok);
+		i += 1;
+	}
+	return {
+		...args,
+		actions,
+		variables,
+		pset
+	};
+};
+const applyStartupArgs = (args, settings, baseConnectOpts, resolution) => {
+	setStartupVars(settings.vars, CLIENT_VERSION);
+	for (const v of args.variables) if (v.value === "") settings.vars.unset(v.name);
+	else settings.vars.set(v.name, v.value);
+	if (args.echoAll) settings.vars.set("ECHO", "all");
+	if (args.echoErrors) settings.vars.set("ECHO", "errors");
+	if (args.echoQueries) settings.vars.set("ECHO", "queries");
+	if (args.echoHidden !== "off") {
+		settings.echoHidden = args.echoHidden;
+		settings.vars.set("ECHO_HIDDEN", args.echoHidden === "noexec" ? "noexec" : "on");
+	}
+	if (args.quiet) {
+		settings.quiet = true;
+		settings.vars.set("QUIET", "on");
+	}
+	if (args.singleline) {
+		settings.singleline = true;
+		settings.vars.set("SINGLELINE", "on");
+	}
+	if (args.singlestep) {
+		settings.singlestep = true;
+		settings.vars.set("SINGLESTEP", "on");
+	}
+	if (args.onErrorStop) {
+		settings.onErrorStop = true;
+		settings.vars.set("ON_ERROR_STOP", "on");
+	}
+	if (args.noAlign) settings.popt.topt.format = "unaligned";
+	if (args.htmlMode) settings.popt.topt.format = "html";
+	if (args.csvOutput) settings.popt.topt.format = "csv";
+	if (args.tuplesOnly) settings.popt.topt.tuplesOnly = true;
+	if (args.expanded) settings.popt.topt.expanded = "on";
+	if (args.fieldSepZero) settings.popt.topt.fieldSep = "\0";
+	else if (args.fieldSep !== void 0) settings.popt.topt.fieldSep = args.fieldSep;
+	if (args.recordSepZero) settings.popt.topt.recordSep = "\0";
+	else if (args.recordSep !== void 0) settings.popt.topt.recordSep = args.recordSep;
+	if (args.noPager) settings.popt.topt.pager = "off";
+	for (const directive of args.pset) {
+		const eq = directive.indexOf("=");
+		if (eq >= 0) {
+			const key = directive.slice(0, eq);
+			const val = directive.slice(eq + 1);
+			if (key === "tableattr" || key === "T") settings.popt.topt.tableAttr = val.length > 0 ? val : null;
+			else if (key === "pager") {
+				if (val === "on" || val === "off" || val === "always") settings.popt.topt.pager = val;
+			}
+		}
+	}
+	let dbname = args.database;
+	let username = args.user;
+	if (args.positional[0] && !dbname) dbname = args.positional[0];
+	if (args.positional[1] && !username) username = args.positional[1];
+	const argvLayer = { ...args.dashD ?? {} };
+	if (args.host !== void 0) argvLayer.host = args.host;
+	if (args.port !== void 0) argvLayer.port = args.port;
+	if (username !== void 0) argvLayer.user = username;
+	if (dbname !== void 0) argvLayer.database = dbname;
+	if (args.password !== void 0) argvLayer.password = args.password;
+	if (args.replication !== void 0) argvLayer.replication = args.replication;
+	let connect;
+	if (resolution === void 0) connect = {
+		...baseConnectOpts ?? {
+			host: "localhost",
+			port: 5432,
+			user: "",
+			database: "",
+			ssl: "prefer"
+		},
+		...argvLayer
+	};
+	else connect = resolveLayeredConnect(argvLayer, resolution, baseConnectOpts);
+	return {
+		connect,
+		preActions: args.actions
+	};
+};
+/**
+* Run the layered connection-parameter merge.
+*
+*   argv > URI partial > PG* env > .pgpass (password only) > service > libpq defaults
+*
+* `baseConnectOpts` (the legacy `ConnectOptions` argument) is treated as a
+* pre-baked URI partial when the resolution path is used WITHOUT an explicit
+* `uriPartial`. This keeps the door open for callers that still want to
+* pass a fully-defaulted URI shape from `parseConnectionUri`.
+*/
+const resolveLayeredConnect = (argvLayer, resolution, legacyBase) => {
+	const env = resolution.env ?? {};
+	const uriPartial = resolution.uriPartial ?? (legacyBase !== void 0 ? legacyBase : {});
+	const serviceName = resolution.serviceName ?? env.PGSERVICE;
+	let serviceEntry;
+	if (serviceName !== void 0 && serviceName !== "") {
+		serviceEntry = resolution.services?.get(serviceName);
+		if (serviceEntry === void 0) throw new Error(`definition of service "${serviceName}" not found`);
+	}
+	const serviceLayer = serviceEntry !== void 0 ? serviceEntryToConnectOptions(serviceEntry) : {};
+	const envLayer = envConnectionDefaults(env);
+	const defaults = libpqConnectionDefaults(env);
+	const layers = [
+		argvLayer,
+		uriPartial,
+		envLayer,
+		serviceLayer
+	];
+	let merged = mergeConnectOptions(layers, defaults);
+	if (merged.password === void 0) {
+		const pgpassPwd = lookupPgPass(resolution.pgpassEntries ?? [], {
+			host: merged.host,
+			port: merged.port,
+			database: merged.database !== "" ? merged.database : merged.user,
+			user: merged.user
+		});
+		if (pgpassPwd !== void 0) {
+			const pgpassLayer = { password: pgpassPwd };
+			merged = mergeConnectOptions([...layers, pgpassLayer], defaults);
+		}
+	}
+	return merged;
+};
+const formatParseError = (err) => err.message;
+//#endregion
+//#region src/psql/index.ts
+/**
+* Embedded TypeScript psql entrypoint.
+*
+* Argv shape mirrors the legacy native-psql call site:
+*   argv[0] = connection URI (postgresql://user:pw@host:port/db?sslmode=...)
+*             OR an empty string `''` when the caller provides the
+*             connection target via libpq flags (-h/-p/-U/-d) and/or PG*
+*             env. The downstream layered resolver picks those up just like
+*             upstream psql does.
+*   argv[1..] = forwarded psql args (parsed by `parseStartupArgs`).
+*/
+const runPsql = async (argv, stdio = {}) => {
+	const stdin = stdio.stdin ?? process.stdin;
+	const stdout = stdio.stdout ?? process.stdout;
+	const stderr = stdio.stderr ?? process.stderr;
+	const connectionUri = argv[0] ?? "";
+	let uriPartial = {};
+	let uriService;
+	if (connectionUri !== "" && looksLikeConnectionString(connectionUri)) try {
+		if (connectionUri.startsWith("postgres://") || connectionUri.startsWith("postgresql://")) {
+			uriPartial = parseConnectionUriPartial(connectionUri);
+			uriService = parseConnectionUriService(connectionUri);
+		} else {
+			const parsed = parseConninfo(connectionUri);
+			if (typeof parsed._service === "string" && parsed._service.length > 0) uriService = parsed._service;
+			delete parsed._service;
+			uriPartial = parsed;
+		}
+	} catch (err) {
+		stderr.write(`psql: error: ${err.message}\n`);
+		return 2;
+	}
+	const parsed = parseStartupArgs(argv.slice(1));
+	if ("kind" in parsed) {
+		if (parsed.kind === "help" || parsed.kind === "version") {
+			stdout.write(parsed.message);
+			if (!parsed.message.endsWith("\n")) stdout.write("\n");
+			return 0;
+		}
+		stderr.write(`psql: error: ${parsed.message}\n`);
+		return 1;
+	}
+	const vars = createVarStore();
+	const settings = defaultSettings(vars);
+	applyEnvOverrides(settings, process.env);
+	settings.notty = !stdin.isTTY;
+	const pgpassEntries = await loadPgPass(void 0, {
+		env: process.env,
+		stderr
+	});
+	let services;
+	try {
+		services = await loadPgServices();
+	} catch (err) {
+		stderr.write(`psql: error: ${err.message}\n`);
+		return 2;
+	}
+	let resolved;
+	try {
+		resolved = applyStartupArgs(parsed, settings, void 0, {
+			env: process.env,
+			uriPartial,
+			serviceName: uriService,
+			pgpassEntries,
+			services
+		});
+	} catch (err) {
+		stderr.write(`psql: error: ${err.message}\n`);
+		return 2;
+	}
+	const { connect: connectOpts, preActions } = resolved;
+	let connection;
+	try {
+		connection = await PgConnection.connect(connectOpts);
+	} catch (err) {
+		const e = err;
+		stderr.write(`psql: error: connection to server failed: ${e.message ?? String(err)}\n`);
+		return 2;
+	}
+	settings.db = connection;
+	syncConnectionVars(settings.vars, connection);
+	const ctx = {
+		settings,
+		registry: defaultRegistry(),
+		cond: createCondStack(),
+		stdin,
+		stdout,
+		stderr
+	};
+	try {
+		if (!settings.quiet && !settings.notty && preActions.length === 0) writeStartupBanner(connection, stdout);
+		await loadPsqlrc(ctx, {
+			skip: parsed.noPsqlrc,
+			env: process.env
+		});
+		if (preActions.length > 0) return await runPreActions(ctx, preActions, parsed.singleTransaction);
+		return await runMainLoop(ctx);
+	} finally {
+		try {
+			await connection.close();
+		} catch {}
+	}
+};
+/**
+* Execute the ordered list of `-c` / `-f` actions and return the upstream
+* psql exit code.
+*
+* Upstream `process_psqlrc_and_targets()` (in `startup.c`) plus the
+* dispatcher in `MainLoop()` cooperate to give each switch one of three
+* outcomes:
+*
+*   - `-c "SQL or \backslash"`:
+*       * a client-side failure (e.g. bad `\copy`) marks the SWITCH itself
+*         as failed → the overall exit code is non-zero, even when
+*         ON_ERROR_STOP is off and the transaction commits.
+*       * a server-side failure follows the same rule.
+*
+*   - `-f file`:
+*       * `process_file()` returns a success status by default, so a
+*         failing statement inside the file does NOT bubble up to the
+*         outer exit code (without ON_ERROR_STOP). Only an I/O failure
+*         opening the file flips the switch status.
+*
+*   - `--single-transaction`:
+*       * before the FIRST action, issue `BEGIN`. After the LAST action,
+*         issue `COMMIT` (success) or `ROLLBACK` (when ON_ERROR_STOP fired
+*         and we stopped early).
+*       * Without ON_ERROR_STOP, the transaction commits even when some
+*         individual statements failed — the failing statements only
+*         influence the exit code (see the `-c` / `-f` distinction above).
+*/
+const runPreActions = async (ctx, preActions, singleTransaction) => {
+	const { settings, stderr } = ctx;
+	let status = 0;
+	let beganTransaction = false;
+	let earlyStopOnError = false;
+	let connectionLost = false;
+	if (singleTransaction && settings.db) try {
+		await settings.db.execSimple("BEGIN");
+		beganTransaction = true;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		stderr.write(`psql: error: could not begin transaction: ${msg}\n`);
+		return 1;
+	}
+	for (const action of preActions) {
+		if (connectionLost) break;
+		if (action.kind === "command") {
+			let outcome;
+			try {
+				outcome = await executeInputString(action.sql, ctx, { print: true });
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				stderr.write(`psql: ERROR:  ${msg}\n`);
+				status = 1;
+				if (settings.onErrorStop) {
+					earlyStopOnError = true;
+					break;
+				}
+				continue;
+			}
+			if (outcome.connectionLost) {
+				connectionLost = true;
+				status = 2;
+				break;
+			}
+			if (outcome.hadError || outcome.stoppedOnError) status = 1;
+			if (outcome.stoppedOnError) {
+				earlyStopOnError = true;
+				break;
+			}
+		} else {
+			let contents;
+			try {
+				contents = await promises.readFile(action.path, "utf8");
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				stderr.write(`psql: error: ${msg}\n`);
+				status = 1;
+				if (settings.onErrorStop) {
+					earlyStopOnError = true;
+					break;
+				}
+				continue;
+			}
+			let outcome;
+			try {
+				outcome = await executeInputString(contents, ctx, { print: true });
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				stderr.write(`psql: ERROR:  ${msg}\n`);
+				status = 3;
+				if (settings.onErrorStop) {
+					earlyStopOnError = true;
+					break;
+				}
+				continue;
+			}
+			if (outcome.connectionLost) {
+				connectionLost = true;
+				status = 2;
+				break;
+			}
+			if (outcome.stoppedOnError) {
+				status = 3;
+				earlyStopOnError = true;
+				break;
+			}
+		}
+	}
+	if (beganTransaction && settings.db && !connectionLost) {
+		const closing = earlyStopOnError ? "ROLLBACK" : "COMMIT";
+		try {
+			await settings.db.execSimple(closing);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			stderr.write(`psql: error: ${closing} failed: ${msg}\n`);
+			if (status === 0) status = 1;
+		}
+	}
+	return status;
+};
+const writeStartupBanner = (connection, out) => {
+	const serverVersion = connection.parameterStatus("server_version") ?? "unknown";
+	out.write(`psql-ts (neon, server ${serverVersion})\n`);
+	const tls = connection.getTlsInfo();
+	if (tls) {
+		const parts = [
+			`protocol: ${tls.protocol}`,
+			`cipher: ${tls.cipher}`,
+			`compression: ${tls.compression}`
+		];
+		if (tls.alpn) parts.push(`ALPN: ${tls.alpn}`);
+		out.write(`SSL connection (${parts.join(", ")})\n`);
+	}
+	out.write("Type \"help\" for help.\n\n");
+};
+const KNOWN_QUERY_KEYS = /* @__PURE__ */ new Set([
+	"host",
+	"hostaddr",
+	"port",
+	"dbname",
+	"user",
+	"password",
+	"passfile",
+	"channel_binding",
+	"require_auth",
+	"connect_timeout",
+	"client_encoding",
+	"options",
+	"application_name",
+	"fallback_application_name",
+	"keepalives",
+	"keepalives_idle",
+	"keepalives_interval",
+	"keepalives_count",
+	"sslmode",
+	"sslnegotiation",
+	"sslcompression",
+	"sslcert",
+	"sslkey",
+	"sslcertmode",
+	"sslrootcert",
+	"sslcrl",
+	"sslcrldir",
+	"sslkeylogfile",
+	"sslsni",
+	"requirepeer",
+	"ssl_min_protocol_version",
+	"ssl_max_protocol_version",
+	"krbsrvname",
+	"gsslib",
+	"gssencmode",
+	"service",
+	"target_session_attrs",
+	"load_balance_hosts",
+	"replication"
+]);
+/**
+* Tokenize a postgres connection URI into raw components.
+*
+* Hand-rolled rather than using `new URL()` because libpq accepts shapes
+* the WHATWG URL parser rejects, e.g. `postgresql://user@` (userinfo with
+* no host), `postgres://:12345/` (port-only), `postgres://uri-user@/db`
+* (userinfo with empty host). The upstream conformance suite in
+* `src/interfaces/libpq/t/001_uri.pl` exercises these forms.
+*/
+const tokenizeConnectionUri = (uri) => {
+	let rest;
+	if (uri.startsWith("postgresql://")) rest = uri.slice(13);
+	else if (uri.startsWith("postgres://")) rest = uri.slice(11);
+	else throw new Error(`unsupported scheme in URI: ${uri}`);
+	let query = "";
+	const qIdx = rest.indexOf("?");
+	if (qIdx >= 0) {
+		query = rest.slice(qIdx + 1);
+		rest = rest.slice(0, qIdx);
+	}
+	let database;
+	const pIdx = rest.indexOf("/");
+	if (pIdx >= 0) {
+		const pathRaw = rest.slice(pIdx + 1);
+		database = pathRaw === "" ? void 0 : decodePercent(pathRaw);
+		rest = rest.slice(0, pIdx);
+	}
+	let userinfo;
+	const atIdx = rest.lastIndexOf("@");
+	if (atIdx >= 0) {
+		userinfo = rest.slice(0, atIdx);
+		rest = rest.slice(atIdx + 1);
+	}
+	let user;
+	let password;
+	if (userinfo !== void 0) {
+		const colon = userinfo.indexOf(":");
+		if (colon >= 0) {
+			user = decodePercent(userinfo.slice(0, colon));
+			password = decodePercent(userinfo.slice(colon + 1));
+		} else user = decodePercent(userinfo);
+	}
+	const tuples = splitAuthorityTuples(rest, uri);
+	let host;
+	let port;
+	const hosts = [];
+	for (const tuple of tuples) {
+		const parsed = parseAuthorityTuple(tuple, uri);
+		if (parsed.host !== void 0) hosts.push({
+			host: parsed.host,
+			port: parsed.port
+		});
+	}
+	if (hosts.length > 0) {
+		host = hosts[0].host;
+		port = hosts[0].port;
+	}
+	const queryMap = parseQuery(query);
+	return {
+		user,
+		password,
+		host,
+		port,
+		...hosts.length > 1 ? { hosts } : {},
+		database,
+		query: queryMap
+	};
+};
+/**
+* Split a multi-host authority string into one tuple per top-level comma.
+* IPv6 bracket regions are atomic — commas inside `[…]` don't split.
+*
+* Examples:
+*   `h1:5432,h2,h3:5434`         -> ['h1:5432','h2','h3:5434']
+*   `[::1]:5432,[2001:db8::1]`   -> ['[::1]:5432','[2001:db8::1]']
+*   `h1`                          -> ['h1']
+*   ``                            -> ['']    (single empty tuple — caller may
+*                                              treat as no-host)
+*/
+const splitAuthorityTuples = (rest, uri) => {
+	if (rest === "") return [""];
+	const tuples = [];
+	let start = 0;
+	let i = 0;
+	while (i < rest.length) {
+		const ch = rest[i];
+		if (ch === "[") {
+			const closeIdx = rest.indexOf("]", i);
+			if (closeIdx < 0) throw new Error(`missing matching "]" in IPv6 host address: ${uri}`);
+			i = closeIdx + 1;
+			continue;
+		}
+		if (ch === ",") {
+			tuples.push(rest.slice(start, i));
+			i += 1;
+			start = i;
+			continue;
+		}
+		i += 1;
+	}
+	tuples.push(rest.slice(start));
+	return tuples;
+};
+const parseAuthorityTuple = (tuple, uri) => {
+	if (tuple === "") return {};
+	if (tuple.startsWith("[")) {
+		const closeIdx = tuple.indexOf("]");
+		if (closeIdx < 0) throw new Error(`missing matching "]" in IPv6 host address: ${uri}`);
+		const host = tuple.slice(1, closeIdx);
+		if (host === "") throw new Error(`IPv6 host address may not be empty: ${uri}`);
+		const after = tuple.slice(closeIdx + 1);
+		if (after === "") return { host };
+		if (after.startsWith(":")) return {
+			host,
+			port: after.slice(1)
+		};
+		throw new Error(`unexpected characters after IPv6 host address in URI: ${uri}`);
+	}
+	const colon = tuple.indexOf(":");
+	if (colon >= 0) return {
+		host: decodePercent(tuple.slice(0, colon)),
+		port: tuple.slice(colon + 1)
+	};
+	return { host: decodePercent(tuple) };
+};
+const parseQuery = (raw) => {
+	const out = /* @__PURE__ */ new Map();
+	if (raw === "") return out;
+	for (const segment of raw.split("&")) {
+		if (segment === "") continue;
+		const eq = segment.indexOf("=");
+		if (eq < 0) throw new Error(`missing "=" after "${segment.trim()}" in connection info string`);
+		const keyRaw = segment.slice(0, eq);
+		const valueRaw = segment.slice(eq + 1);
+		if (valueRaw.includes("=")) throw new Error(`extra "=" in query parameter "${decodePercent(keyRaw).trim()}"`);
+		const key = decodePercent(keyRaw).trim();
+		const value = decodePercent(valueRaw).trim();
+		if (key === "") continue;
+		if (!KNOWN_QUERY_KEYS.has(key)) throw new Error(`invalid URI query parameter: "${key}"`);
+		out.set(key, value);
+	}
+	return out;
+};
+/**
+* Percent-decode a URI component. libpq strictly validates percent-encoding:
+*   - `%XX` must be two hex digits
+*   - bare `%` or `%X` is invalid
+*   - `%00` is forbidden (NUL bytes can't appear in connection params)
+*
+* `decodeURIComponent` throws URIError on malformed escapes — we surface that
+* as a clear Error. It accepts `%00` (returns `\0`); we explicitly reject.
+*/
+const decodePercent = (s) => {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(s);
+	} catch {
+		throw new Error(`invalid percent-encoded token in URI: ${s}`);
+	}
+	if (decoded.includes("\0")) throw new Error(`forbidden NUL byte (%00) in URI: ${s}`);
+	return decoded;
+};
+const parseConnectionUri = (uri) => {
+	const raw = tokenizeConnectionUri(uri);
+	const queryUser = raw.query.get("user");
+	const queryPassword = raw.query.get("password");
+	const queryPort = raw.query.get("port");
+	const queryDbname = raw.query.get("dbname");
+	const queryHost = raw.query.get("host");
+	const hostsTuples = computeHostsTuples({
+		rawHost: raw.host,
+		rawPort: raw.port,
+		rawAuthorityHosts: raw.hosts,
+		queryHost,
+		queryPort
+	});
+	const host = hostsTuples.length > 0 && hostsTuples[0].host !== "" ? hostsTuples[0].host : "localhost";
+	const port = hostsTuples.length > 0 ? hostsTuples[0].port : 5432;
+	const user = queryUser !== void 0 && queryUser !== "" ? queryUser : raw.user !== void 0 && raw.user !== "" ? raw.user : process.env.USER ?? "";
+	const password = queryPassword ?? raw.password;
+	const database = queryDbname ?? raw.database ?? user;
+	let ssl = normalizeSslMode(raw.query.get("sslmode") ?? null);
+	const channelBinding = normalizeChannelBinding(raw.query.get("channel_binding") ?? null);
+	validateGssEncMode(raw.query.get("gssencmode") ?? null);
+	const options = raw.query.get("options");
+	const applicationName = raw.query.get("application_name") ?? "psql";
+	const replication = normalizeReplication(raw.query.get("replication") ?? null);
+	const targetSessionAttrs = normalizeTargetSessionAttrs(raw.query.get("target_session_attrs") ?? null);
+	const loadBalanceHosts = normalizeLoadBalanceHosts(raw.query.get("load_balance_hosts") ?? null);
+	const sslcert = nonEmpty(raw.query.get("sslcert"));
+	const sslkey = nonEmpty(raw.query.get("sslkey"));
+	const sslcertmode = normalizeSslCertMode(raw.query.get("sslcertmode") ?? null);
+	const sslnegotiation = normalizeSslNegotiation(raw.query.get("sslnegotiation") ?? null);
+	const sslrootcert = nonEmpty(raw.query.get("sslrootcert"));
+	const sslcrl = nonEmpty(raw.query.get("sslcrl"));
+	const sslcrldir = nonEmpty(raw.query.get("sslcrldir"));
+	const sslkeylogfile = nonEmpty(raw.query.get("sslkeylogfile"));
+	const sslsni = parseLibpqBool(nonEmpty(raw.query.get("sslsni")));
+	const keepalives = parseLibpqBool(nonEmpty(raw.query.get("keepalives")));
+	const keepalivesIdle = parseKeepalivesIdle(nonEmpty(raw.query.get("keepalives_idle")));
+	const requirepeer = nonEmpty(raw.query.get("requirepeer"));
+	if (sslrootcert === "system" && ssl !== "verify-full") ssl = "verify-full";
+	const hostaddr = nonEmpty(raw.query.get("hostaddr"));
+	const sslMinProtocolVersion = normalizeTlsProtocolVersion(nonEmpty(raw.query.get("ssl_min_protocol_version")), "ssl_min_protocol_version");
+	const sslMaxProtocolVersion = normalizeTlsProtocolVersion(nonEmpty(raw.query.get("ssl_max_protocol_version")), "ssl_max_protocol_version");
+	assertTlsProtocolRange(sslMinProtocolVersion, sslMaxProtocolVersion);
+	assertTlsMaxProtocolSupported(sslMaxProtocolVersion);
+	assertSslNegotiationModeCompatible(ssl, sslnegotiation);
+	return {
+		host,
+		port,
+		user,
+		password,
+		database,
+		ssl,
+		channelBinding,
+		applicationName,
+		options,
+		...sslnegotiation !== void 0 ? { sslnegotiation } : {},
+		...hostaddr !== void 0 ? { hostaddr } : {},
+		...replication !== void 0 ? { replication } : {},
+		...hostsTuples.length > 1 ? { hosts: hostsTuples.map((t) => ({
+			host: t.host,
+			port: t.port
+		})) } : {},
+		...targetSessionAttrs !== void 0 ? { targetSessionAttrs } : {},
+		...loadBalanceHosts !== void 0 ? { loadBalanceHosts } : {},
+		...sslcert !== void 0 ? { sslcert } : {},
+		...sslkey !== void 0 ? { sslkey } : {},
+		...sslcertmode !== void 0 ? { sslcertmode } : {},
+		...sslrootcert !== void 0 ? { sslrootcert } : {},
+		...sslcrl !== void 0 ? { sslcrl } : {},
+		...sslcrldir !== void 0 ? { sslcrldir } : {},
+		...sslkeylogfile !== void 0 ? { sslkeylogfile } : {},
+		...sslsni !== void 0 ? { sslsni } : {},
+		...keepalives !== void 0 ? { keepalives } : {},
+		...keepalivesIdle !== void 0 ? { keepalivesIdle } : {},
+		...requirepeer !== void 0 ? { requirepeer } : {},
+		...sslMinProtocolVersion !== void 0 ? { sslMinProtocolVersion } : {},
+		...sslMaxProtocolVersion !== void 0 ? { sslMaxProtocolVersion } : {}
+	};
+};
+/**
+* Parse a libpq 0/1 boolean connection parameter (`sslsni`, `keepalives`).
+* libpq's `parse_bool_with_len` accepts `1`/`0`, `true`/`false`, `yes`/`no`,
+* `on`/`off` (case-insensitive). Returns `undefined` for unset / empty /
+* unrecognised so the caller falls back to libpq's default (enabled).
+*/
+const parseLibpqBool = (raw) => {
+	if (raw === void 0 || raw === "") return void 0;
+	switch (raw.toLowerCase()) {
+		case "1":
+		case "true":
+		case "yes":
+		case "on": return true;
+		case "0":
+		case "false":
+		case "no":
+		case "off": return false;
+		default: return;
+	}
+};
+/**
+* Parse `keepalives_idle` (seconds, non-negative integer). Returns the value
+* in seconds, or `undefined` if unset / malformed (the wire layer converts to
+* milliseconds for `socket.setKeepAlive`'s `initialDelay`).
+*/
+const parseKeepalivesIdle = (raw) => {
+	if (raw === void 0 || raw === "") return void 0;
+	const n = Number.parseInt(raw, 10);
+	return Number.isFinite(n) && n >= 0 ? n : void 0;
+};
+const nonEmpty = (v) => v === void 0 || v === "" ? void 0 : v;
+/**
+* Resolve the final {host, port}[] list for a URI:
+*
+*  1. Start from the authority. `?host=`/`?port=` query overrides take
+*     precedence (libpq semantics).
+*  2. If `host=h1,h2,…` is supplied, parse the comma-list. Ports come from
+*     `port=p1,p2,…`; must match the host count or be a single value
+*     (broadcast to all hosts).
+*  3. If only the authority had multi-host tuples (`postgresql://h1,h2/db`),
+*     use those.
+*  4. Otherwise fall back to single-host.
+*
+* Validates every port is in 1..65535 and surfaces a clear error otherwise.
+*/
+const computeHostsTuples = (input) => {
+	const { rawHost, rawPort, rawAuthorityHosts, queryHost, queryPort } = input;
+	if (queryHost !== void 0 && queryHost !== "") {
+		const hosts = queryHost.split(",").map((h) => h.trim());
+		const portList = queryPort !== void 0 && queryPort !== "" ? queryPort.split(",").map((p) => p.trim()) : null;
+		if (portList !== null && portList.length !== 1 && portList.length !== hosts.length) throw new Error(`could not match ${String(portList.length)} port numbers to ${String(hosts.length)} hosts`);
+		return hosts.map((h, idx) => {
+			let portStr;
+			if (portList !== null) portStr = portList.length === 1 ? portList[0] : portList[idx];
+			else portStr = rawPort;
+			return {
+				host: h,
+				port: parsePort(portStr)
+			};
+		});
+	}
+	if (rawAuthorityHosts !== void 0 && rawAuthorityHosts.length > 0) {
+		const portList = queryPort !== void 0 && queryPort !== "" ? queryPort.split(",").map((p) => p.trim()) : null;
+		if (portList !== null && portList.length !== 1 && portList.length !== rawAuthorityHosts.length) throw new Error(`could not match ${String(portList.length)} port numbers to ${String(rawAuthorityHosts.length)} hosts`);
+		return rawAuthorityHosts.map((t, idx) => ({
+			host: t.host,
+			port: parsePort(portList !== null ? portList.length === 1 ? portList[0] : portList[idx] : t.port)
+		}));
+	}
+	return [{
+		host: rawHost !== void 0 && rawHost !== "" ? rawHost : "",
+		port: parsePort(queryPort ?? rawPort)
+	}];
+};
+const parsePort = (raw) => {
+	if (raw === void 0 || raw === "") return 5432;
+	if (/^\d/.test(raw) && !/^\d+$/.test(raw)) throw new Error(`invalid integer value "${raw}" for connection option "port"`);
+	const p = Number.parseInt(raw, 10);
+	if (!Number.isFinite(p) || p <= 0 || p > 65535) throw new Error(`invalid port: ${raw}`);
+	return p;
+};
+/**
+* Parse a libpq-style conninfo string into a `Partial<ConnectOptions>`.
+*
+* The grammar is roughly `key = value` pairs separated by whitespace, where
+* values may be quoted with single quotes (libpq's `\'` is honored as an
+* embedded single-quote, but we don't model the full backslash-escape
+* universe — there's no test corpus that exercises it). Unknown keys are
+* rejected so a typo like `replicate=database` produces a clear error
+* rather than silently dropping the parameter.
+*
+* Recognised keys mirror the URI-side `KNOWN_QUERY_KEYS` allowlist plus
+* the authority-style keys (`host`, `port`, `user`, `dbname`, `password`).
+* `replication` is normalised through `normalizeReplication` for libpq
+* value-set compatibility.
+*
+* Out of scope: percent-decoding (conninfo strings are NOT percent-encoded),
+* `service` resolution from `pg_service.conf`, `passfile` resolution.
+*/
+const parseConninfo = (input) => {
+	const out = {};
+	let i = 0;
+	const n = input.length;
+	while (i < n) {
+		while (i < n && /\s/.test(input[i])) i += 1;
+		if (i >= n) break;
+		const keyStart = i;
+		while (i < n && input[i] !== "=" && !/\s/.test(input[i])) i += 1;
+		const key = input.slice(keyStart, i).toLowerCase();
+		if (key === "") break;
+		while (i < n && /\s/.test(input[i])) i += 1;
+		if (i >= n || input[i] !== "=") throw new Error(`missing "=" after "${key}" in conninfo string`);
+		i += 1;
+		while (i < n && /\s/.test(input[i])) i += 1;
+		let value;
+		if (i < n && input[i] === "'") {
+			i += 1;
+			const parts = [];
+			while (i < n && input[i] !== "'") if (input[i] === "\\" && i + 1 < n) {
+				parts.push(input[i + 1]);
+				i += 2;
+			} else {
+				parts.push(input[i]);
+				i += 1;
+			}
+			if (i >= n) throw new Error(`unterminated single quote in conninfo string for key "${key}"`);
+			i += 1;
+			value = parts.join("");
+		} else {
+			const valStart = i;
+			while (i < n && !/\s/.test(input[i])) i += 1;
+			value = input.slice(valStart, i);
+		}
+		applyConninfoPair(out, key, value);
+	}
+	const hostList = out._hostList;
+	const portList = out._portList;
+	if (hostList !== void 0 && hostList.length > 0) {
+		if (portList !== void 0 && portList.length !== 1 && portList.length !== hostList.length) throw new Error(`could not match ${String(portList.length)} port numbers to ${String(hostList.length)} hosts`);
+		if (hostList.length > 1) out.hosts = hostList.map((h, idx) => ({
+			host: h,
+			port: portList === void 0 ? out.port ?? 5432 : portList.length === 1 ? parsePort(portList[0]) : parsePort(portList[idx])
+		}));
+	}
+	delete out._hostList;
+	delete out._portList;
+	assertTlsProtocolRange(out.sslMinProtocolVersion, out.sslMaxProtocolVersion);
+	assertTlsMaxProtocolSupported(out.sslMaxProtocolVersion);
+	return out;
+};
+const applyConninfoPair = (out, key, value) => {
+	switch (key) {
+		case "host":
+			if (value.includes(",")) {
+				out._hostList = value.split(",").map((h) => h.trim());
+				out.host = out._hostList[0];
+			} else {
+				out.host = value;
+				out._hostList = void 0;
+			}
+			return;
+		case "port":
+			if (value.includes(",")) {
+				out._portList = value.split(",").map((p) => p.trim());
+				out.port = parsePort(out._portList[0]);
+			} else {
+				out.port = parsePort(value);
+				out._portList = void 0;
+			}
+			return;
+		case "user":
+			out.user = value;
+			return;
+		case "password":
+			out.password = value;
+			return;
+		case "dbname":
+			out.database = value;
+			return;
+		case "application_name":
+			out.applicationName = value;
+			return;
+		case "sslmode":
+			out.ssl = normalizeSslMode(value);
+			return;
+		case "channel_binding": {
+			const cb = normalizeChannelBinding(value);
+			if (cb !== void 0) out.channelBinding = cb;
+			return;
+		}
+		case "require_auth": {
+			const ra = normalizeRequireAuth(value);
+			if (ra !== void 0) out.requireAuth = ra;
+			return;
+		}
+		case "connect_timeout": {
+			const t = Number.parseInt(value, 10);
+			if (Number.isFinite(t) && t >= 0) out.connectTimeoutMs = t * 1e3;
+			return;
+		}
+		case "client_encoding":
+			out.clientEncoding = value;
+			return;
+		case "options":
+			out.options = value;
+			return;
+		case "replication": {
+			const rep = normalizeReplication(value);
+			if (rep !== void 0) out.replication = rep;
+			return;
+		}
+		case "target_session_attrs": {
+			const tsa = normalizeTargetSessionAttrs(value);
+			if (tsa !== void 0) out.targetSessionAttrs = tsa;
+			return;
+		}
+		case "load_balance_hosts": {
+			const lbh = normalizeLoadBalanceHosts(value);
+			if (lbh !== void 0) out.loadBalanceHosts = lbh;
+			return;
+		}
+		case "gssencmode":
+			validateGssEncMode(value);
+			return;
+		case "sslcert":
+			if (value !== "") out.sslcert = value;
+			return;
+		case "sslkey":
+			if (value !== "") out.sslkey = value;
+			return;
+		case "sslcertmode": {
+			const cm = normalizeSslCertMode(value);
+			if (cm !== void 0) out.sslcertmode = cm;
+			return;
+		}
+		case "sslnegotiation": {
+			const sn = normalizeSslNegotiation(value);
+			if (sn !== void 0) out.sslnegotiation = sn;
+			return;
+		}
+		case "sslrootcert":
+			if (value !== "") out.sslrootcert = value;
+			return;
+		case "sslcrl":
+			if (value !== "") out.sslcrl = value;
+			return;
+		case "sslcrldir":
+			if (value !== "") out.sslcrldir = value;
+			return;
+		case "sslkeylogfile":
+			if (value !== "") out.sslkeylogfile = value;
+			return;
+		case "hostaddr":
+			if (value !== "") out.hostaddr = value;
+			return;
+		case "ssl_min_protocol_version": {
+			const v = normalizeTlsProtocolVersion(value === "" ? void 0 : value, "ssl_min_protocol_version");
+			if (v !== void 0) out.sslMinProtocolVersion = v;
+			return;
+		}
+		case "ssl_max_protocol_version": {
+			const v = normalizeTlsProtocolVersion(value === "" ? void 0 : value, "ssl_max_protocol_version");
+			if (v !== void 0) out.sslMaxProtocolVersion = v;
+			return;
+		}
+		case "sslsni": {
+			const b = parseLibpqBool(value);
+			if (b !== void 0) out.sslsni = b;
+			return;
+		}
+		case "keepalives": {
+			const b = parseLibpqBool(value);
+			if (b !== void 0) out.keepalives = b;
+			return;
+		}
+		case "keepalives_idle": {
+			const n = parseKeepalivesIdle(value);
+			if (n !== void 0) out.keepalivesIdle = n;
+			return;
+		}
+		case "requirepeer":
+			if (value !== "") out.requirepeer = value;
+			return;
+		case "passfile":
+		case "sslcompression":
+		case "krbsrvname":
+		case "gsslib":
+		case "fallback_application_name":
+		case "keepalives_interval":
+		case "keepalives_count": return;
+		case "service":
+			out._service = value;
+			return;
+		default: throw new Error(`invalid conninfo key: "${key}"`);
+	}
+};
+/**
+* Heuristic: does the `-d` value look like a connection URI or a conninfo
+* string (vs. a bare database name)? Mirrors libpq's
+* `recognized_connection_string()` test.
+*/
+const looksLikeConnectionString = (s) => {
+	if (s.startsWith("postgresql://") || s.startsWith("postgres://")) return true;
+	const eq = s.indexOf("=");
+	if (eq < 0) return false;
+	const head = s.slice(0, eq);
+	return !/\s/.test(head);
+};
+const normalizeSslMode = (raw) => {
+	if (raw === null) return "prefer";
+	const value = raw.toLowerCase();
+	switch (value) {
+		case "disable":
+		case "allow":
+		case "prefer":
+		case "require":
+		case "verify-ca":
+		case "verify-full": return value;
+		default: throw new Error(`invalid sslmode value: "${raw}"`);
+	}
+};
+/**
+* libpq's accepted TLS protocol-version names, in ascending order. The
+* index doubles as the comparison key for the `min > max` check. Matching
+* is case-insensitive on input (libpq lowercases before comparing) but we
+* keep the canonical mixed-case spelling Node's `tls` module expects for
+* `minVersion` / `maxVersion`.
+*/
+const TLS_PROTOCOL_VERSIONS = [
+	"TLSv1",
+	"TLSv1.1",
+	"TLSv1.2",
+	"TLSv1.3"
+];
+/**
+* Validate and canonicalise a `ssl_{min,max}_protocol_version` value. Returns
+* the canonical spelling (`TLSv1.2` etc.) or `undefined` for empty / unset.
+* Throws libpq's `invalid <key> value: "<raw>"` wording on a malformed value.
+*/
+const normalizeTlsProtocolVersion = (raw, key) => {
+	if (raw === void 0 || raw === "") return void 0;
+	const match = TLS_PROTOCOL_VERSIONS.find((v) => v.toLowerCase() === raw.toLowerCase());
+	if (match === void 0) throw new Error(`invalid ${key} value: "${raw}"`);
+	return match;
+};
+/**
+* Reject a `ssl_max_protocol_version` ceiling below TLSv1.2. TLS 1.0/1.1 are
+* disabled in Node's bundled OpenSSL, so capping the ceiling there leaves no
+* negotiable protocol and the handshake otherwise fails with an opaque
+* `ERR_SSL_NO_PROTOCOLS_AVAILABLE` — surface an actionable message at parse
+* time instead. Only the MAX is gated: a low *min*
+* (`ssl_min_protocol_version=TLSv1.1`) is harmless because Node still
+* negotiates the highest mutually-supported version (1.2/1.3), exactly as
+* libpq does on a modern OpenSSL. Called AFTER {@link assertTlsProtocolRange}
+* so an inverted range (min > max) reports the range error first, matching
+* libpq's ordering.
+*/
+const assertTlsMaxProtocolSupported = (max) => {
+	if (max === "TLSv1" || max === "TLSv1.1") throw new Error(`ssl_max_protocol_version "${max}" is not supported by this runtime's TLS library — TLS 1.0/1.1 are disabled in Node's OpenSSL; the minimum negotiable version is TLSv1.2`);
+};
+/**
+* Reject a `ssl_min_protocol_version` that is higher than
+* `ssl_max_protocol_version`, matching libpq's
+* `ssl_min_protocol_version must be <= ssl_max_protocol_version` diagnostic.
+* Both arguments must already be canonicalised by
+* {@link normalizeTlsProtocolVersion}.
+*/
+const assertTlsProtocolRange = (min, max) => {
+	if (min === void 0 || max === void 0) return;
+	if (TLS_PROTOCOL_VERSIONS.indexOf(min) > TLS_PROTOCOL_VERSIONS.indexOf(max)) throw new Error(`ssl_min_protocol_version must be <= ssl_max_protocol_version`);
+};
+const normalizeChannelBinding = (raw) => {
+	if (raw === null || raw === "") return void 0;
+	const value = raw.toLowerCase();
+	switch (value) {
+		case "disable":
+		case "prefer":
+		case "require": return value;
+		default: throw new Error(`invalid channel_binding value: "${raw}"`);
+	}
+};
+/**
+* Validate libpq's `gssencmode` (GSSAPI transport encryption).
+*
+* This client has NO GSSAPI support: GSS-API `gss_wrap`/`gss_unwrap` would
+* require a native Kerberos addon (e.g. the `kerberos` npm), which the
+* embedded psql deliberately avoids (pure-TS, zero native bindings — the
+* same reason the line editor is hand-rolled). `node-postgres` doesn't
+* support it either. So:
+*   - `disable` / `prefer` — accepted and ignored: neither needs GSS
+*     (`prefer` means "try GSS, else fall back", and falling back to the
+*     non-GSS path is exactly what we always do).
+*   - `require` — rejected with a clear diagnostic; we cannot satisfy it.
+*   - anything else — `invalid gssencmode value`.
+* We recognise the parameter (rather than rejecting it as an unknown key)
+* so the many tools that always append `gssencmode=...` to a URI keep
+* working against Neon.
+*/
+const validateGssEncMode = (raw) => {
+	if (raw === null || raw === "") return;
+	const value = raw.toLowerCase();
+	if (value === "disable" || value === "prefer") return;
+	if (value === "require") throw new Error("gssencmode=require is not supported: this client has no GSSAPI support");
+	throw new Error(`invalid gssencmode value: "${raw}"`);
+};
+/**
+* Parse libpq's `sslcertmode` value (`disable` / `allow` / `require`).
+* Empty / unset returns `undefined` so the wire-layer default (`allow`)
+* applies. A malformed value throws libpq's
+* `invalid sslcertmode value: "<raw>"` diagnostic.
+*/
+const normalizeSslCertMode = (raw) => {
+	if (raw === null || raw === "") return void 0;
+	const value = raw.toLowerCase();
+	switch (value) {
+		case "disable":
+		case "allow":
+		case "require": return value;
+		default: throw new Error(`invalid sslcertmode value: "${raw}"`);
+	}
+};
+/**
+* Parse libpq's `sslnegotiation` value (`postgres` / `direct`). Empty / unset
+* returns `undefined` so the wire-layer default (`postgres`, the classic
+* SSLRequest flow) applies. A malformed value throws libpq's
+* `invalid sslnegotiation value: "<raw>"` diagnostic.
+*/
+const normalizeSslNegotiation = (raw) => {
+	if (raw === null || raw === "") return void 0;
+	const value = raw.toLowerCase();
+	switch (value) {
+		case "postgres":
+		case "direct": return value;
+		default: throw new Error(`invalid sslnegotiation value: "${raw}"`);
+	}
+};
+/**
+* libpq constraint: `sslnegotiation=direct` may only be used with an encrypted
+* sslmode (`require` / `verify-ca` / `verify-full`). Direct SSL starts the TLS
+* handshake immediately with no plaintext fallback, so a "weak" mode that could
+* end up unencrypted (`disable` / `allow` / `prefer`) is rejected with libpq's
+* exact `pqConnectOptions2` wording. No-op unless `sslnegotiation` is `direct`.
+*/
+const assertSslNegotiationModeCompatible = (ssl, sslnegotiation) => {
+	if (sslnegotiation !== "direct") return;
+	if (ssl === "require" || ssl === "verify-ca" || ssl === "verify-full") return;
+	throw new Error(`weak sslmode "${ssl}" may not be used with sslnegotiation=direct`);
+};
+const VALID_REQUIRE_AUTH_METHODS = /* @__PURE__ */ new Set([
+	"password",
+	"md5",
+	"gss",
+	"sspi",
+	"scram-sha-256",
+	"creds",
+	"none"
+]);
+/**
+* Parse libpq's `require_auth` value: a comma-separated list of method
+* names where each entry may be prefixed with `!` to negate. Mixing
+* positive and negative entries is forbidden (libpq matches this).
+*
+* Returns `undefined` for empty input so the wire-layer default applies.
+* Throws on invalid syntax with libpq-parity wording, surfaced via the
+* outer `psql: error: ...` channel.
+*/
+const normalizeRequireAuth = (raw) => {
+	if (raw === null || raw === "") return void 0;
+	const tokens = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+	if (tokens.length === 0) return void 0;
+	const methods = /* @__PURE__ */ new Set();
+	let polarity = null;
+	for (const token of tokens) {
+		const isNeg = token.startsWith("!");
+		const name = (isNeg ? token.slice(1) : token).toLowerCase();
+		if (!VALID_REQUIRE_AUTH_METHODS.has(name)) throw new Error(`invalid require_auth method: "${token}"`);
+		if (polarity === null) polarity = isNeg;
+		else if (polarity !== isNeg) throw new Error("require_auth methods cannot mix positive and negative entries");
+		methods.add(name);
+	}
+	return {
+		methods,
+		negated: polarity ?? false
+	};
+};
+/**
+* Accept the libpq-spec set for `target_session_attrs`. Aliases `read-write`/
+* `primary` and `read-only`/`standby` are kept distinct because the wire
+* layer treats the canonical four values identically — we only normalise
+* unknown / empty inputs to `undefined` so the wire-layer default ('any')
+* applies. Throws on unrecognised values, matching libpq behaviour.
+*/
+const normalizeTargetSessionAttrs = (raw) => {
+	if (raw === null || raw === "") return void 0;
+	const value = raw.toLowerCase();
+	switch (value) {
+		case "any":
+		case "read-write":
+		case "read-only":
+		case "primary":
+		case "standby":
+		case "prefer-standby": return value;
+		default: throw new Error(`invalid value for "target_session_attrs": "${raw}"`);
+	}
+};
+/**
+* Accept the libpq-spec set for `load_balance_hosts`:
+*   - `disable` (default) — preserve list order
+*   - `random`            — shuffle before iteration
+*
+* Unknown values throw; empty / unset returns `undefined` so the wire layer
+* default ('disable') applies.
+*/
+const normalizeLoadBalanceHosts = (raw) => {
+	if (raw === null || raw === "") return void 0;
+	const value = raw.toLowerCase();
+	if (value === "disable" || value === "random") return value;
+	throw new Error(`invalid value for "load_balance_hosts": "${raw}"`);
+};
+/**
+* libpq accepts a wide set of "truthy" values for `replication`:
+*   - `true` / `on` / `yes` / `1`     → physical replication (mapped to `true`)
+*   - `false` / `off` / `no` / `0`    → not a walsender (no replication mode)
+*   - `database`                       → logical replication on that DB
+*
+* Returns `undefined` when no value was supplied or when it explicitly
+* disables replication; throws for unrecognised input (matching libpq's
+* `"invalid <…> value"` semantics so users see a clear error rather than
+* silently sending an unexpected startup-message parameter).
+*/
+const normalizeReplication = (raw) => {
+	if (raw === null || raw === "") return void 0;
+	const value = raw.toLowerCase();
+	if (value === "database") return "database";
+	if (value === "true" || value === "on" || value === "yes" || value === "1") return "true";
+	if (value === "false" || value === "off" || value === "no" || value === "0") return;
+	throw new Error(`invalid value for "replication": "${raw}"`);
+};
+/**
+* Service name extracted from a connection URI's `?service=` query
+* parameter, if any. Surfaced alongside `parseConnectionUriPartial` so the
+* caller can route the lookup into `applyStartupArgs` without re-parsing
+* the URI.
+*/
+const parseConnectionUriService = (uri) => {
+	const value = tokenizeConnectionUri(uri).query.get("service");
+	return value === void 0 || value === "" ? void 0 : value;
+};
+/**
+* Parse a URI into a `Partial<ConnectOptions>` containing only the fields
+* the URI explicitly supplied. Returned shape:
+*
+*   - missing fields are absent (no `undefined` placeholders)
+*   - `host`/`port` are populated only when the URI authority or `?host=`
+*     specified them
+*   - `user`/`password`/`database`/`ssl`/`channelBinding`/... follow the
+*     same rule — present iff explicitly set
+*
+* This is the building block for the layered merge in `applyStartupArgs`.
+* The full-defaults variant `parseConnectionUri` remains the right choice
+* for callers that want a complete `ConnectOptions` (e.g. the existing
+* `-d URI` path); it's kept untouched for back-compat.
+*/
+const parseConnectionUriPartial = (uri) => {
+	const raw = tokenizeConnectionUri(uri);
+	const queryUser = raw.query.get("user");
+	const queryPassword = raw.query.get("password");
+	const queryPort = raw.query.get("port");
+	const queryDbname = raw.query.get("dbname");
+	const queryHost = raw.query.get("host");
+	const hostsTuples = computeHostsTuples({
+		rawHost: raw.host,
+		rawPort: raw.port,
+		rawAuthorityHosts: raw.hosts,
+		queryHost,
+		queryPort
+	});
+	const portInUri = raw.port !== void 0 && raw.port !== "" || queryPort !== void 0 && queryPort !== "" || (raw.hosts?.some((t) => t.port !== void 0 && t.port !== "") ?? false);
+	const out = {};
+	if (hostsTuples.length > 0) {
+		if (hostsTuples[0].host !== "") out.host = hostsTuples[0].host;
+		if (portInUri && hostsTuples[0].port !== 0) out.port = hostsTuples[0].port;
+		if (hostsTuples.length > 1) out.hosts = hostsTuples.map((t) => ({
+			host: t.host,
+			port: t.port
+		}));
+	}
+	const userExplicit = queryUser !== void 0 && queryUser !== "" ? queryUser : raw.user !== void 0 && raw.user !== "" ? raw.user : void 0;
+	if (userExplicit !== void 0) out.user = userExplicit;
+	const password = queryPassword ?? raw.password;
+	if (password !== void 0) out.password = password;
+	const database = queryDbname ?? raw.database;
+	if (database !== void 0) out.database = database;
+	const sslRaw = raw.query.get("sslmode");
+	if (sslRaw !== void 0 && sslRaw !== "") out.ssl = normalizeSslMode(sslRaw);
+	const cb = normalizeChannelBinding(raw.query.get("channel_binding") ?? null);
+	if (cb !== void 0) out.channelBinding = cb;
+	const ra = normalizeRequireAuth(raw.query.get("require_auth") ?? null);
+	if (ra !== void 0) out.requireAuth = ra;
+	const options = raw.query.get("options");
+	if (options !== void 0 && options !== "") out.options = options;
+	const appName = raw.query.get("application_name");
+	if (appName !== void 0 && appName !== "") out.applicationName = appName;
+	const replication = normalizeReplication(raw.query.get("replication") ?? null);
+	if (replication !== void 0) out.replication = replication;
+	const targetSessionAttrs = normalizeTargetSessionAttrs(raw.query.get("target_session_attrs") ?? null);
+	if (targetSessionAttrs !== void 0) out.targetSessionAttrs = targetSessionAttrs;
+	const loadBalanceHosts = normalizeLoadBalanceHosts(raw.query.get("load_balance_hosts") ?? null);
+	if (loadBalanceHosts !== void 0) out.loadBalanceHosts = loadBalanceHosts;
+	const sslcert = nonEmpty(raw.query.get("sslcert"));
+	if (sslcert !== void 0) out.sslcert = sslcert;
+	const sslkey = nonEmpty(raw.query.get("sslkey"));
+	if (sslkey !== void 0) out.sslkey = sslkey;
+	const sslcertmode = normalizeSslCertMode(raw.query.get("sslcertmode") ?? null);
+	if (sslcertmode !== void 0) out.sslcertmode = sslcertmode;
+	const sslnegotiation = normalizeSslNegotiation(raw.query.get("sslnegotiation") ?? null);
+	if (sslnegotiation !== void 0) out.sslnegotiation = sslnegotiation;
+	const sslrootcert = nonEmpty(raw.query.get("sslrootcert"));
+	if (sslrootcert !== void 0) out.sslrootcert = sslrootcert;
+	const sslcrl = nonEmpty(raw.query.get("sslcrl"));
+	if (sslcrl !== void 0) out.sslcrl = sslcrl;
+	const sslcrldir = nonEmpty(raw.query.get("sslcrldir"));
+	if (sslcrldir !== void 0) out.sslcrldir = sslcrldir;
+	const sslkeylogfile = nonEmpty(raw.query.get("sslkeylogfile"));
+	if (sslkeylogfile !== void 0) out.sslkeylogfile = sslkeylogfile;
+	const sslsni = parseLibpqBool(nonEmpty(raw.query.get("sslsni")));
+	if (sslsni !== void 0) out.sslsni = sslsni;
+	const keepalives = parseLibpqBool(nonEmpty(raw.query.get("keepalives")));
+	if (keepalives !== void 0) out.keepalives = keepalives;
+	const keepalivesIdle = parseKeepalivesIdle(nonEmpty(raw.query.get("keepalives_idle")));
+	if (keepalivesIdle !== void 0) out.keepalivesIdle = keepalivesIdle;
+	const requirepeer = nonEmpty(raw.query.get("requirepeer"));
+	if (requirepeer !== void 0) out.requirepeer = requirepeer;
+	const hostaddr = nonEmpty(raw.query.get("hostaddr"));
+	if (hostaddr !== void 0) out.hostaddr = hostaddr;
+	const sslMin = normalizeTlsProtocolVersion(nonEmpty(raw.query.get("ssl_min_protocol_version")), "ssl_min_protocol_version");
+	if (sslMin !== void 0) out.sslMinProtocolVersion = sslMin;
+	const sslMax = normalizeTlsProtocolVersion(nonEmpty(raw.query.get("ssl_max_protocol_version")), "ssl_max_protocol_version");
+	if (sslMax !== void 0) out.sslMaxProtocolVersion = sslMax;
+	assertTlsProtocolRange(out.sslMinProtocolVersion, out.sslMaxProtocolVersion);
+	assertTlsMaxProtocolSupported(out.sslMaxProtocolVersion);
+	const connectTimeoutSec = raw.query.get("connect_timeout");
+	if (connectTimeoutSec !== void 0 && connectTimeoutSec !== "") {
+		const t = Number.parseInt(connectTimeoutSec, 10);
+		if (Number.isFinite(t) && t >= 0) out.connectTimeoutMs = t * 1e3;
+	}
+	const clientEncoding = raw.query.get("client_encoding");
+	if (clientEncoding !== void 0 && clientEncoding !== "") out.clientEncoding = clientEncoding;
+	return out;
+};
+const PG_ENV_FIELD_MAP = {
+	PGHOST: "host",
+	PGHOSTADDR: "hostaddr",
+	PGPORT: "port",
+	PGUSER: "user",
+	PGDATABASE: "database",
+	PGPASSWORD: "password",
+	PGAPPNAME: "applicationName",
+	PGOPTIONS: "options",
+	PGCLIENTENCODING: "clientEncoding",
+	PGSSLMODE: "ssl",
+	PGSSLROOTCERT: "sslrootcert",
+	PGSSLCERT: "sslcert",
+	PGSSLKEY: "sslkey",
+	PGSSLCERTMODE: "sslcertmode",
+	PGSSLNEGOTIATION: "sslnegotiation",
+	PGSSLCRL: "sslcrl",
+	PGSSLCRLDIR: "sslcrldir",
+	PGSSLKEYLOGFILE: "sslkeylogfile",
+	PGCHANNELBINDING: "channelBinding"
+};
+/**
+* Resolve the PG* env vars into a `Partial<ConnectOptions>`. Only set keys
+* end up in the result; unset / empty env vars are skipped so the caller
+* can layer this between URI overrides and pgpass / service / libpq
+* defaults without clobbering anything.
+*
+* Validation: any malformed value (e.g. `PGPORT=abc`) is silently dropped.
+* libpq behaves the same — the connection then fails later with a clearer
+* "could not parse" message, but the env-var lookup itself does not throw.
+*
+* Notes:
+*   - `PGHOSTADDR` maps to {@link ConnectOptions.hostaddr}: the wire layer
+*     dials this fixed IP while `PGHOST` still drives TLS SNI / cert
+*     verification.
+*   - `PGCONNECT_TIMEOUT` is in seconds; we convert to milliseconds.
+*   - `PGCHANNELBINDING` accepts disable/prefer/require.
+*   - `PGSERVICE` is consumed by the caller (it drives the
+*     pg_service.conf lookup) and is NOT a direct ConnectOptions field.
+*   - `PGSERVICEFILE`, `PGSYSCONFDIR`, `PGPASSFILE` are likewise consumed
+*     by the loaders, not surfaced here.
+*/
+const envConnectionDefaults = (env) => {
+	const out = {};
+	const get = (k) => {
+		const v = env[k];
+		return v !== void 0 && v !== "" ? v : void 0;
+	};
+	for (const [envName, field] of Object.entries(PG_ENV_FIELD_MAP)) {
+		const value = get(envName);
+		if (value === void 0) continue;
+		applyEnvValue(out, field, value);
+	}
+	const timeoutRaw = get("PGCONNECT_TIMEOUT");
+	if (timeoutRaw !== void 0) {
+		const t = Number.parseInt(timeoutRaw, 10);
+		if (Number.isFinite(t) && t >= 0) out.connectTimeoutMs = t * 1e3;
+	}
+	validateGssEncMode(get("PGGSSENCMODE") ?? null);
+	return out;
+};
+const applyEnvValue = (out, field, value) => {
+	switch (field) {
+		case "host":
+			out.host = value;
+			return;
+		case "port": {
+			const p = Number.parseInt(value, 10);
+			if (Number.isFinite(p) && p > 0 && p <= 65535) out.port = p;
+			return;
+		}
+		case "user":
+			out.user = value;
+			return;
+		case "database":
+			out.database = value;
+			return;
+		case "password":
+			out.password = value;
+			return;
+		case "applicationName":
+			out.applicationName = value;
+			return;
+		case "options":
+			out.options = value;
+			return;
+		case "clientEncoding":
+			out.clientEncoding = value;
+			return;
+		case "ssl":
+			out.ssl = normalizeSslMode(value);
+			return;
+		case "sslrootcert":
+			out.sslrootcert = value;
+			return;
+		case "sslcert":
+			out.sslcert = value;
+			return;
+		case "sslkey":
+			out.sslkey = value;
+			return;
+		case "sslcertmode": {
+			const cm = normalizeSslCertMode(value);
+			if (cm !== void 0) out.sslcertmode = cm;
+			return;
+		}
+		case "sslnegotiation": {
+			const sn = normalizeSslNegotiation(value);
+			if (sn !== void 0) out.sslnegotiation = sn;
+			return;
+		}
+		case "sslcrl":
+			out.sslcrl = value;
+			return;
+		case "sslcrldir":
+			out.sslcrldir = value;
+			return;
+		case "sslkeylogfile":
+			out.sslkeylogfile = value;
+			return;
+		case "hostaddr":
+			out.hostaddr = value;
+			return;
+		case "channelBinding": {
+			const cb = normalizeChannelBinding(value);
+			if (cb !== void 0) out.channelBinding = cb;
+			return;
+		}
+		default: return;
+	}
+};
+/**
+* libpq compiled-in defaults. The lowest-priority layer in the merge chain.
+*
+*   - host: 'localhost'
+*   - port: 5432
+*   - user: $USER ?? '' (the wire layer surfaces a clear error if the user
+*     is still empty at connect time)
+*   - database: deferred — libpq defaults dbname to the user; we wire that
+*     in `mergeConnectOptions` after layering so a `PGUSER` env can flow
+*     into `database` when the user didn't specify one.
+*   - ssl: 'prefer'
+*   - applicationName: 'psql' — matches upstream so `pg_stat_activity` shows
+*     the value users expect.
+*   - sslcert / sslkey: libpq auto-loads the default client cert/key at
+*     `~/.postgresql/postgresql.crt` / `.key` when neither is configured AND
+*     the file exists. We seed these as the lowest-priority defaults via
+*     {@link defaultClientCertDefaults}; any explicit URI / env / conninfo
+*     value overrides them. A non-existent default file is simply not set
+*     (no error), matching libpq — only an explicit path that's missing
+*     surfaces an error (at TLS-load time, in the wire layer).
+*/
+const libpqConnectionDefaults = (env) => ({
+	host: "localhost",
+	port: 5432,
+	user: env.USER ?? "",
+	database: "",
+	ssl: "prefer",
+	applicationName: "psql",
+	...defaultClientCertDefaults(env)
+});
+/**
+* libpq default client-certificate discovery. When the user has NOT set
+* `sslcert` / `sslkey` (explicit paths and `PGSSLCERT` / `PGSSLKEY` are
+* higher-priority layers), libpq falls back to `~/.postgresql/postgresql.crt`
+* and `~/.postgresql/postgresql.key` — but only if those files actually
+* exist. We mirror that here so a present default cert satisfies e.g.
+* `sslcertmode=require`.
+*
+* The home directory is taken from `env.HOME` (falling back to
+* `os.homedir()`), the same convention as the pgpass / pgservice loaders;
+* passing a synthetic `HOME` keeps this hermetic in tests.
+*
+* Exported for unit testing.
+*/
+const defaultClientCertDefaults = (env) => {
+	const home = env.HOME ?? os.homedir();
+	if (home === void 0 || home === "") return {};
+	const out = {};
+	const certPath = path.join(home, ".postgresql", "postgresql.crt");
+	if (existsSync(certPath)) out.sslcert = certPath;
+	const keyPath = path.join(home, ".postgresql", "postgresql.key");
+	if (existsSync(keyPath)) out.sslkey = keyPath;
+	return out;
+};
+/**
+* Translate a `pg_service.conf` entry into a `Partial<ConnectOptions>`.
+* Unknown keys are silently dropped — the service file format admits
+* arbitrary keys but only the libpq-spec subset maps to ConnectOptions.
+*
+* Numeric / enum validation mirrors `parseConninfo` so an out-of-range
+* port or bogus sslmode in the service file fails the same way (silently
+* dropped here, since libpq itself only warns on invalid service values).
+*/
+const serviceEntryToConnectOptions = (entry) => {
+	const out = {};
+	for (const [k, v] of Object.entries(entry)) switch (k.toLowerCase()) {
+		case "host":
+			if (v !== "") out.host = v;
+			break;
+		case "port": {
+			const p = Number.parseInt(v, 10);
+			if (Number.isFinite(p) && p > 0 && p <= 65535) out.port = p;
+			break;
+		}
+		case "user":
+			if (v !== "") out.user = v;
+			break;
+		case "dbname":
+			if (v !== "") out.database = v;
+			break;
+		case "password":
+			out.password = v;
+			break;
+		case "application_name":
+			if (v !== "") out.applicationName = v;
+			break;
+		case "sslmode":
+			if (v !== "") out.ssl = normalizeSslMode(v);
+			break;
+		case "channel_binding": {
+			const cb = normalizeChannelBinding(v);
+			if (cb !== void 0) out.channelBinding = cb;
+			break;
+		}
+		case "require_auth": {
+			const ra = normalizeRequireAuth(v);
+			if (ra !== void 0) out.requireAuth = ra;
+			break;
+		}
+		case "options":
+			if (v !== "") out.options = v;
+			break;
+		case "client_encoding":
+			if (v !== "") out.clientEncoding = v;
+			break;
+		case "sslcert":
+			if (v !== "") out.sslcert = v;
+			break;
+		case "sslkey":
+			if (v !== "") out.sslkey = v;
+			break;
+		case "sslcertmode": {
+			const cm = normalizeSslCertMode(v);
+			if (cm !== void 0) out.sslcertmode = cm;
+			break;
+		}
+		case "sslnegotiation": {
+			const sn = normalizeSslNegotiation(v);
+			if (sn !== void 0) out.sslnegotiation = sn;
+			break;
+		}
+		case "sslrootcert":
+			if (v !== "") out.sslrootcert = v;
+			break;
+		case "sslcrl":
+			if (v !== "") out.sslcrl = v;
+			break;
+		case "sslcrldir":
+			if (v !== "") out.sslcrldir = v;
+			break;
+		case "sslkeylogfile":
+			if (v !== "") out.sslkeylogfile = v;
+			break;
+		case "sslsni": {
+			const b = parseLibpqBool(v);
+			if (b !== void 0) out.sslsni = b;
+			break;
+		}
+		case "keepalives": {
+			const b = parseLibpqBool(v);
+			if (b !== void 0) out.keepalives = b;
+			break;
+		}
+		case "keepalives_idle": {
+			const n = parseKeepalivesIdle(v);
+			if (n !== void 0) out.keepalivesIdle = n;
+			break;
+		}
+		case "requirepeer":
+			if (v !== "") out.requirepeer = v;
+			break;
+		case "hostaddr":
+			if (v !== "") out.hostaddr = v;
+			break;
+		case "ssl_min_protocol_version": {
+			const pv = normalizeTlsProtocolVersion(v === "" ? void 0 : v, "ssl_min_protocol_version");
+			if (pv !== void 0) out.sslMinProtocolVersion = pv;
+			break;
+		}
+		case "ssl_max_protocol_version": {
+			const pv = normalizeTlsProtocolVersion(v === "" ? void 0 : v, "ssl_max_protocol_version");
+			if (pv !== void 0) out.sslMaxProtocolVersion = pv;
+			break;
+		}
+		case "connect_timeout": {
+			const t = Number.parseInt(v, 10);
+			if (Number.isFinite(t) && t >= 0) out.connectTimeoutMs = t * 1e3;
+			break;
+		}
+	}
+	assertTlsProtocolRange(out.sslMinProtocolVersion, out.sslMaxProtocolVersion);
+	assertTlsMaxProtocolSupported(out.sslMaxProtocolVersion);
+	return out;
+};
+/**
+* Merge layered partial ConnectOptions into a complete ConnectOptions.
+*
+* Layers are listed in PRIORITY order (highest first). For each output
+* field, the first layer that supplies a value wins. The implementation
+* walks the layers in reverse so the spread-into semantics match.
+*
+* `database` has a libpq-specific fallback: if every layer omits it, the
+* default is the resolved `user` (so `psql -U alice` connects to a
+* database named `alice`). We apply this AFTER all layers have run.
+*/
+const mergeConnectOptions = (layers, defaults) => {
+	let out = { ...defaults };
+	for (let i = layers.length - 1; i >= 0; i--) {
+		const layer = layers[i];
+		out = {
+			...out,
+			...layer
+		};
+	}
+	if (out.database === "") out.database = out.user;
+	if (out.sslrootcert === "system" && out.ssl !== "verify-full") out.ssl = "verify-full";
+	assertSslNegotiationModeCompatible(out.ssl, out.sslnegotiation);
+	return out;
+};
+//#endregion
+export { mergeConnectOptions as a, parseConnectionUriService as c, serviceEntryToConnectOptions as d, CLIENT_VERSION as f, parseStartupArgs as h, looksLikeConnectionString as i, parseConninfo as l, formatParseError as m, envConnectionDefaults as n, parseConnectionUri as o, applyStartupArgs as p, libpqConnectionDefaults as r, parseConnectionUriPartial as s, defaultClientCertDefaults as t, runPsql as u };