DSN parsing for PostgreSQL connection strings.
Supports both libpq formats:
- keyword=value: host=localhost port=5432 dbname=test
- URI: postgresql://user:pass@host:port/db?param=value
Treat the DSN as trusted operator config, not end-user input: unknown keys become StartupMessage parameters and values such as options are forwarded verbatim. Sanitize before parseDsn if it is not under your control.
Only initConnConfig / parseDsn / validateConnConfig are re-exported through pg_connection.nim; the intermediate parsers stay here. Depends only on types.nim (does not touch PgConnection).
Internal module: not part of the public API. Import the pg_connection hub instead.
Procs
proc initConnConfig(host = DefaultHost; port = 5432; hostaddr = ""; user = ""; password = ""; database = ""; sslMode = sslPrefer; sslRootCert = ""; sslCert = ""; sslKey = ""; sslSni = true; channelBinding = cbPrefer; applicationName = ""; connectTimeout = ZeroDuration; keepAlive = true; keepAliveIdle = 0; keepAliveInterval = 0; keepAliveCount = 0; hosts: seq[HostEntry] = @[]; targetSessionAttrs = tsaAny; loadBalanceHosts = lbhDisable; requireAuth: set[AuthMethod] = {}; extraParams: seq[(string, string)] = @[]; maxMessageSize = 0; maxScramIterations = 0; sslNegotiation = sslnPostgres): ConnConfig {. ...raises: [PgConfigError], tags: [], forbids: [].}
-
Create a connection configuration with sensible defaults. For DSN-based configuration, use parseDsn instead.
Validates like DSN parsing; negative connectTimeout becomes ZeroDuration (no timeout). When hosts is non-empty, scalar host/hostaddr/port are overwritten from hosts[0] (same as DSN parsers). An empty host with no hostaddr is rejected, like an explicitly empty host in a DSN.
proc optionsTimeZone(options: string): Option[string] {....raises: [], tags: [], forbids: [].}
- The TimeZone value a -c switch in options sets, if any. The last switch wins, as on the server.
proc parseDsn(dsn: string): ConnConfig {....raises: [PgConfigError], tags: [ReadIOEffect], forbids: [].}
-
Parse a PostgreSQL connection string into a ConnConfig.
Supports two formats:
- URI: postgresql://[user[:password]@][host[:port]][/database][?param=value&...]
- keyword=value: host=localhost port=5432 dbname=test (libpq compatible)
Both postgresql:// and postgres:// schemes are accepted for URI format. A raw @ in user or password parses; a raw / or ? there must be percent-encoded, and a raw @ in the database, or in a query with no path, raises PgConfigError (h/db?user=a@b is fine).
client_encoding is always UTF8: another value, directly or via -c in options, raises PgConfigError. Likewise DateStyle always uses the ISO output style: only its field order (DMY, ...) may be set. TimeZone is UTC unless set here; see ConnConfig.extraParams.
Security: the DSN is trusted configuration — unknown keys are forwarded as StartupMessage parameters, so a typo in a security-sensitive key (e.g. sslmde) is not detected. Do not pass end-user-controlled strings without sanitizing. Parse and validation failures report lengths and offsets only, never parameter values (a malformed DSN may place the password in any field); certificate file I/O errors name the path for diagnosis. See ConnConfig for plaintext password handling.
proc validateConnConfig(config: var ConnConfig) {....raises: [PgConfigError], tags: [], forbids: [].}
-
Mirror DSN guards for initConnConfig and the connect chokepoint (DSN parsers validate inline; hand-built ConnConfig is re-checked at connect time so numeric / hostaddr faults become PgConfigError).
An empty host with no hostaddr is rejected rather than defaulted (matching the DSN parsers), so an unset template variable cannot hand the credentials to whatever listens on localhost. The scalar host/hostaddr/port are mirrored from hosts[0], which is what getHosts dials. Negative connectTimeout becomes ZeroDuration.