Connection lifecycle: auth, single/multi-host connect, and close.
Internal module: not part of the public API. Import the pg_connection hub instead; what it re-exports is the supported surface (see tests/api_surface.golden).
Procs
proc close(conn: PgConnection): Future[void] {. ...raises: [Exception, LibraryError, SslError, ValueError], tags: [RootEffect, TimeEffect], forbids: [].}
- Idempotent close; asyncdispatch may orphan blocking pump until it unwinds. Waiter → PgStateError.
proc closeImpl(conn: PgConnection; byUser: bool): Future[void] {. ...stackTrace: false, raises: [Exception, LibraryError, SslError, ValueError], tags: [RootEffect, TimeEffect], forbids: [].}
- Close with ownership flag: byUser=false keeps PgConnectionError for pool evictions.
proc connect(config: ConnConfig): Future[PgConnection] {....raises: [Exception, ValueError, PgConfigError, PgConnectionError, CatchableError], tags: [RootEffect, WriteIOEffect, TimeEffect], forbids: [].}
- Connect with multi-host failover, targetSessionAttrs, per-host connectTimeout. Per-host failures fold into one PgConnectionError; a PgConfigError escapes the fold.
proc connect(dsn: string): Future[PgConnection] {....raises: [Exception, ValueError, PgConfigError, PgConnectionError, CatchableError], tags: [RootEffect, WriteIOEffect, TimeEffect, ReadIOEffect], forbids: [].}
- Shorthand for connect(parseDsn(dsn)).
proc connectToHost(config: ConnConfig; entry: HostEntry): Future[PgConnection] {. ...stackTrace: false, raises: [Exception, ValueError, PgConfigError, CancelledError, PgConnectionError, OSError, LibraryError, SslError, CatchableError], tags: [RootEffect, WriteIOEffect, TimeEffect], forbids: [].}
- Connect to single host (dial hostaddr else host; verify via host).
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 orderedHosts(config: ConnConfig): seq[HostEntry] {. ...raises: [PgConnectionError], tags: [], forbids: [].}
- Hosts per loadBalanceHosts (lbhRandom shuffles via urandom; no global state).
proc selectScramMechanism(sslEnabled: bool; serverCertDer: openArray[byte]; saslMechanisms: seq[string]; mode: ChannelBindingMode): tuple[ mechanism: string, cbType: string, cbData: seq[byte], cbSupportedButUnused: bool] {....raises: [PgConnectionError], tags: [RootEffect], forbids: [].}
- Pick SCRAM mechanism/binding (raises if mode unsatisfied; cbSupportedButUnused → y,, else n,,).