Server-side portal-based cursors: openCursor, fetchNext, close, and the scoped withCursor template.
Types
Cursor = ref object conn*: PgConnection fields*: seq[FieldDescription] exhausted*: bool
- A server-side portal for incremental row fetching via declareCursor/fetch.
Procs
proc close(cursor: Cursor): Future[void] {....stackTrace: false, raises: [ Exception, ValueError, PgConnectionError, ProtocolError, SslError, PgQueryError, CatchableError, PgTimeoutError, AsyncTimeoutError], tags: [RootEffect, TimeEffect], forbids: [].}
- Close the cursor and return the connection to ready state. On timeout, the connection is marked csClosed (protocol out of sync).
proc columnIndex(cursor: Cursor; name: string): int {....raises: [PgTypeError], tags: [], forbids: [].}
- Find the index of a column by name in a cursor.
proc fetchNext(cursor: Cursor): Future[seq[Row]] {....stackTrace: false, raises: [ Exception, ValueError, PgQueryError, ProtocolError, SslError, CatchableError, PgConnectionError, PgTimeoutError, AsyncTimeoutError], tags: [RootEffect, TimeEffect], forbids: [].}
- Fetch the next chunk of rows from the cursor. Returns an empty seq when the cursor is exhausted. On timeout, the connection is marked csClosed (protocol out of sync).
proc openCursor(conn: PgConnection; sql: string; params: seq[PgParam] = @[]; resultFormat: ResultFormat = rfAuto; chunkSize: int32 = 100; timeout: Duration = ZeroDuration): Future[Cursor] {. ...stackTrace: false, raises: [Exception, ValueError, PgQueryError, PgConnectionError, ProtocolError, SslError, CatchableError, PgTimeoutError, AsyncTimeoutError], tags: [RootEffect, TimeEffect], forbids: [].}
- Open a server-side cursor for streaming rows in chunks. On timeout, the connection is marked csClosed (protocol out of sync).
Templates
template withCursor(conn: PgConnection; sql: string; chunks: int32; cursorName, body: untyped; cursorTimeout: Duration = ZeroDuration)
- Open a cursor, execute body, then close the cursor automatically. The cursor is available as cursorName inside the body.