Connection lifecycle: open, authenticate, fail over across hosts, close.
Contains:
- Authentication helpers (enforceAuthAllowed, filterSaslByRequireAuth, selectScramMechanism) that the auth loop in connectToHost consumes.
- connectToHost — the single-host bootstrap: socket → SSL → startup → auth loop → ParameterStatus/BackendKeyData → extension OID discovery.
- connect — the public entry: multi-host failover, targetSessionAttrs handling, optional connectTimeout, top-level connect tracing.
- close — idempotent teardown: stop background listen pump, send Terminate, drop transport handles.
Imports simple_query for checkSessionAttrs (failover probe). Re-exported through pg_connection.nim.
Procs
proc close(conn: PgConnection): Future[void] {....stackTrace: false, raises: [Exception, ValueError, LibraryError, SslError], tags: [RootEffect], forbids: [].}
- Close the connection. Idempotent: safe to call multiple times.
proc connect(config: ConnConfig): Future[PgConnection] {. ...raises: [Exception, ValueError, CatchableError], tags: [RootEffect, TimeEffect, WriteIOEffect], forbids: [].}
- Establish a new connection to a PostgreSQL server. Supports multi-host failover: tries each host in order. Respects targetSessionAttrs to select the appropriate server type. The connectTimeout wraps the entire multi-host connection attempt.
proc connect(dsn: string): Future[PgConnection] {. ...raises: [Exception, ValueError, CatchableError, PgError], tags: [RootEffect, TimeEffect, WriteIOEffect, ReadIOEffect], forbids: [].}
- Shorthand for connect(parseDsn(dsn)).
proc connectToHost(config: ConnConfig; hostAddr: string; hostPort: int): Future[ PgConnection] {....stackTrace: false, raises: [Exception, ValueError, CancelledError, PgConnectionError, OSError, LibraryError, SslError, CatchableError], tags: [RootEffect, WriteIOEffect, TimeEffect], forbids: [].}
- Connect to a single PostgreSQL host. Internal helper for multi-host connect.
proc enforceAuthAllowed(authMethod: AuthMethod; allowed: set[AuthMethod]; offered: string = "") {....raises: [PgConnectionError], tags: [], forbids: [].}
proc filterSaslByRequireAuth(mechs: seq[string]; allowed: set[AuthMethod]): seq[ string] {....raises: [], tags: [], forbids: [].}
- Filter a server-offered SASL mechanism list by the client's requireAuth policy. An empty allowed set performs no filtering (matching libpq semantics when require_auth is unset).
proc selectScramMechanism(sslEnabled: bool; serverCertDer: openArray[byte]; saslMechanisms: seq[string]; mode: ChannelBindingMode): tuple[ mechanism: string, cbType: string, cbData: seq[byte]] {. ...raises: [PgConnectionError], tags: [RootEffect], forbids: [].}
- Pick the SCRAM mechanism and channel-binding material for a SASL authentication attempt. Raises PgConnectionError when the server-offered mechanisms cannot satisfy mode.