Named server-side prepared statements: prepare, execute, and close.
Internal module: not part of the public API. Import the pg_client hub instead; what it re-exports is the supported surface (see tests/api_surface.golden).
Types
PreparedStatement = object
-
A server-side prepared statement returned by prepare.
Valid only within the server session that prepared it. A session reset (DISCARD ALL / DEALLOCATE, or a pooled backend being recycled) drops the statement; a later execute then raises PgQueryError with SQLSTATE 26000 (invalid_sql_statement_name) and the caller must prepare it again. There is no transparent re-prepare here — that is reserved for the auto-prepare statement cache (see the cache path's StmtCacheInvalidatingStates handling in pg_client/core).
Fields are private; use the conn / name / sql / fields / paramOids accessors for read-only access.
Procs
proc close(stmt: PreparedStatement; timeout: Duration = ZeroDuration): Future[ void] {....stackTrace: false, raises: [Exception, ValueError, PgQueryError, PgStateError, PgConnectionError, PgTypeError, PgProtocolError, CatchableError, PgTimeoutError, CancelledError, AsyncTimeoutError], tags: [RootEffect, TimeEffect], forbids: [].}
- Close a prepared statement. On timeout, the connection is retired (csClosed) unless the wire had settled (asyncdispatch always retires: the timed-out op stays on the socket).
proc closeImpl(stmt: PreparedStatement): Future[void] {....stackTrace: false, raises: [ Exception, PgStateError, PgConnectionError, PgTypeError, PgProtocolError, CancelledError, CatchableError, ValueError, PgQueryError, AsyncTimeoutError], tags: [RootEffect, TimeEffect], forbids: [].}
proc columnIndex(stmt: PreparedStatement; name: string): int {. ...raises: [PgTypeError], tags: [], forbids: [].}
- Find the index of a column by name in a prepared statement.
func conn(stmt: PreparedStatement): PgConnection {.inline, ...raises: [], tags: [], forbids: [].}
- The connection (server session) this statement was prepared on.
proc execute(stmt: PreparedStatement; params: seq[PgParam] = @[]; resultFormat: ResultFormat = rfAuto; timeout: Duration = ZeroDuration): Future[QueryResult] {. ...stackTrace: false, raises: [Exception, ValueError, CatchableError], tags: [RootEffect, TimeEffect], forbids: [].}
-
Execute a prepared statement with typed parameters.
If the server session has lost the statement (DISCARD ALL / DEALLOCATE, or a pooled backend reset), this raises PgQueryError with SQLSTATE 26000; recover by calling prepare again. The error is propagated, not retried — unlike the auto-prepare cache, an explicit PreparedStatement is never re-prepared transparently.
proc executeImpl(stmt: PreparedStatement; params: seq[PgParam] = @[]; resultFormats: seq[int16] = @[]): Future[QueryResult] {. ...stackTrace: false, raises: [Exception, ValueError, PgStateError, PgConnectionError, PgTypeError, PgMessageTooLargeError, PgProtocolError, CancelledError, CatchableError, PgQueryError, AsyncTimeoutError], tags: [RootEffect, TimeEffect], forbids: [].}
func fields(stmt: PreparedStatement): seq[FieldDescription] {.inline, ...raises: [], tags: [], forbids: [].}
- Column descriptions of the statement's result rows.
func name(stmt: PreparedStatement): string {.inline, ...raises: [], tags: [], forbids: [].}
- The server-side statement name given to prepare.
func paramOids(stmt: PreparedStatement): seq[int32] {.inline, ...raises: [], tags: [], forbids: [].}
- Parameter type OIDs reported by the server at prepare time.
proc prepare(conn: PgConnection; name: string; sql: string; timeout: Duration = ZeroDuration): Future[PreparedStatement] {. ...stackTrace: false, raises: [Exception, ValueError, CatchableError], tags: [RootEffect, TimeEffect], forbids: [].}
- Prepare a named statement, returning metadata. On timeout, the connection is retired (csClosed) unless the wire had settled (asyncdispatch always retires: the timed-out op stays on the socket).
proc prepareImpl(conn: PgConnection; name: string; sql: string): Future[ PreparedStatement] {....stackTrace: false, raises: [Exception, ValueError, PgStateError, PgConnectionError, PgTypeError, PgMessageTooLargeError, PgProtocolError, CancelledError, CatchableError, PgQueryError, AsyncTimeoutError], tags: [RootEffect, TimeEffect], forbids: [].}
func sql(stmt: PreparedStatement): string {.inline, ...raises: [], tags: [], forbids: [].}
- The SQL text this statement was prepared from.