Named server-side prepared statements: prepare, execute, and close.
Types
PreparedStatement = object conn*: PgConnection name*: string sql*: string fields*: seq[FieldDescription] paramOids*: seq[int32]
-
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).
Procs
proc close(stmt: PreparedStatement; timeout: Duration = ZeroDuration): Future[ void] {....stackTrace: false, raises: [Exception, ValueError, CatchableError, PgConnectionError, PgStateError, PgProtocolError, SslError, PgQueryError, PgTimeoutError, AsyncTimeoutError], tags: [RootEffect, TimeEffect], forbids: [].}
- Close a prepared statement. On timeout, the connection is marked csClosed (protocol out of sync).
proc closeImpl(stmt: PreparedStatement): Future[void] {....stackTrace: false, raises: [ Exception, PgConnectionError, PgStateError, ValueError, PgProtocolError, SslError, PgQueryError, AsyncTimeoutError, CatchableError], 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.
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, PgConnectionError, PgStateError, PgTypeError, PgProtocolError, SslError, PgQueryError, AsyncTimeoutError, CatchableError], tags: [RootEffect, TimeEffect], forbids: [].}
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 marked csClosed (protocol out of sync).
proc prepareImpl(conn: PgConnection; name: string; sql: string): Future[ PreparedStatement] {....stackTrace: false, raises: [Exception, ValueError, PgConnectionError, PgStateError, PgProtocolError, SslError, PgQueryError, AsyncTimeoutError, CatchableError], tags: [RootEffect, TimeEffect], forbids: [].}