Client-side LRU cache for server-prepared statements.
Holds the server statement name, parameter OIDs, field descriptions and pre-computed result formats for each cached SQL. The Extended Query send paths look up cached entries with lookupStmtCache, evict before adding via addStmtCache, and use pendingStmtCloses to bundle Close messages with the next operation's Sync.
Re-exported through pg_connection.nim.
Procs
proc addStmtCache(conn: PgConnection; sql: string; cached: CachedStmt) {. ...raises: [KeyError], tags: [], forbids: [].}
- Add a prepared statement to the cache with auto-computed result formats. Callers are expected to evict and send a server-side Close for the evicted statement before sending Parse, so the loop below normally does not fire. It is a defensive guard: if a caller ever skips the pre-eviction step (or if stmtCacheCapacity was shrunk below the current size), we evict here instead of silently dropping the new entry and queue the evicted names in pendingStmtCloses so the next Extended Query operation can send their server-side Close.
proc clearStmtCache(conn: PgConnection) {....raises: [], tags: [], forbids: [].}
- Clear the client-side statement cache. Does not close server-side statements, including any Close messages queued in pendingStmtCloses from defensive eviction — the queue is dropped on the assumption the caller will reset the session externally (e.g. via DISCARD ALL or by closing the connection).
proc evictStmtCache(conn: PgConnection): CachedStmt {....raises: [KeyError], tags: [], forbids: [].}
- Evict the least recently used entry from the cache. Returns the evicted entry.
proc flushPendingStmtCloses(conn: PgConnection) {. ...raises: [ValueError, ProtocolError], tags: [], forbids: [].}
- Convenience overload that writes to conn.sendBuf.
proc flushPendingStmtCloses(conn: PgConnection; buf: var seq[byte]) {. ...raises: [ValueError, ProtocolError], tags: [], forbids: [].}
- Append Close messages for any prepared statement names queued by the defensive eviction path in addStmtCache to buf and clear the queue. Called by Extended Query send paths after the outgoing buffer is emptied (or freshly allocated) so the closes ride along with the next operation's Sync. The corresponding CloseComplete replies are absorbed by the receive loops (every Extended Query recv loop handles bmkCloseComplete or falls through else: discard).
proc lookupStmtCache(conn: PgConnection; sql: string): CachedStmt {....raises: [], tags: [], forbids: [].}
- Look up a cached prepared statement by SQL text, updating LRU order on hit. Returns nil on miss. Because CachedStmt is a ref, the returned value remains valid even if the cache is mutated afterwards — the entry's lifetime is extended by the reference.
proc nextStmtName(conn: PgConnection): string {....raises: [], tags: [], forbids: [].}
- Generate the next unique prepared statement name for the statement cache.
proc removeStmtCache(conn: PgConnection; sql: string) {....raises: [], tags: [], forbids: [].}
- Remove a statement from the cache by its SQL text.