async_postgres/pg_client/query

Search:
Group by:

query overloads and result-shape convenience wrappers (queryRow, queryValue, queryExists, queryColumn) on top of the extended-query protocol. Also hosts the row-streaming queryEach entry point.

Procs

proc query(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
           resultFormat: ResultFormat = rfAuto; timeout: Duration = ZeroDuration): Future[
    QueryResult] {....stackTrace: false,
                   raises: [Exception, ValueError, CatchableError],
                   tags: [RootEffect, TimeEffect], forbids: [].}

Execute a query with typed parameters via the extended query protocol.

Single statement only; the plan is cached per-connection. Use simpleQuery when you need multiple ;-separated statements to run in one round trip (no parameters, text-only rows).

On timeout the connection is marked closed (protocol desync) and cannot be reused; pooled connections are discarded automatically.

proc query(conn: PgConnection; sql: string; params: seq[PgParamInline];
           resultFormat: ResultFormat = rfAuto; timeout: Duration = ZeroDuration): Future[
    QueryResult] {....stackTrace: false,
                   raises: [Exception, ValueError, CatchableError],
                   tags: [RootEffect, TimeEffect], forbids: [].}
Execute a query with heap-alloc-free inline parameters. Prefer this overload for scalar-heavy workloads where seq[PgParam] would heap-allocate per parameter. 
proc queryColumn(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
                 timeout: Duration = ZeroDuration): Future[seq[string]] {.
    ...stackTrace: false,
    raises: [Exception, ValueError, CatchableError, PgNullError, PgTypeError],
    tags: [RootEffect, TimeEffect], forbids: [].}
Execute a query and return the first column of all rows as strings. Raises PgNullError if any value is NULL. 
proc queryEach(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
               callback: RowCallback; resultFormat: ResultFormat = rfAuto;
               timeout: Duration = ZeroDuration): Future[int64] {.
    ...stackTrace: false, raises: [Exception, ValueError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}

Execute a query with typed parameters, invoking callback once per row. Returns the number of rows processed.

The Row passed to callback is only valid for the duration of that single invocation: its backing buffer is reused for the next row as soon as the callback returns. To retain a row beyond the callback, call row.clone() to get a detached copy, or extract the column values you need into your own types before returning.

proc queryEachImpl(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
                   callback: RowCallback; resultFormats: seq[int16] = @[];
                   timeout: Duration = ZeroDuration): Future[int64] {.
    ...stackTrace: false, raises: [Exception, ValueError, PgConnectionError,
                                ProtocolError, KeyError, SslError,
                                CatchableError, PgQueryError, AsyncTimeoutError],
    tags: [RootEffect, TimeEffect], forbids: [].}
proc queryExists(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
                 timeout: Duration = ZeroDuration): Future[bool] {.
    ...stackTrace: false, raises: [Exception, ValueError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}
Execute a query and return whether any rows exist. 
proc queryImpl(conn: PgConnection; sql: string; params: seq[Option[seq[byte]]];
               paramOids: seq[int32]; paramFormats: seq[int16];
               resultFormats: seq[int16] = @[]; timeout: Duration = ZeroDuration): Future[
    QueryResult] {....stackTrace: false, raises: [Exception, ValueError,
    PgConnectionError, ProtocolError, KeyError, SslError, PgQueryError,
    AsyncTimeoutError, CatchableError], tags: [RootEffect, TimeEffect],
                   forbids: [].}
proc queryImpl(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
               resultFormats: seq[int16] = @[]; timeout: Duration = ZeroDuration): Future[
    QueryResult] {....stackTrace: false, raises: [Exception, ValueError,
    PgConnectionError, ProtocolError, KeyError, SslError, PgQueryError,
    AsyncTimeoutError, CatchableError], tags: [RootEffect, TimeEffect],
                   forbids: [].}
proc queryInlineImpl(conn: PgConnection; sql: string; data: seq[byte];
                     ranges: seq[tuple[off: int32, len: int32]];
                     paramOids: seq[int32]; paramFormats: seq[int16];
                     resultFormats: seq[int16] = @[];
                     timeout: Duration = ZeroDuration): Future[QueryResult] {.
    ...stackTrace: false, raises: [Exception, ValueError, PgConnectionError,
                                ProtocolError, KeyError, SslError, PgQueryError,
                                AsyncTimeoutError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}
proc queryRow(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
              resultFormat: ResultFormat = rfAuto;
              timeout: Duration = ZeroDuration): Future[Row] {.
    ...stackTrace: false,
    raises: [Exception, ValueError, CatchableError, PgNoRowsError],
    tags: [RootEffect, TimeEffect], forbids: [].}
Execute a query and return the first row. Raises PgNoRowsError if no rows are returned. 
proc queryRowOpt(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
                 resultFormat: ResultFormat = rfAuto;
                 timeout: Duration = ZeroDuration): Future[Option[Row]] {.
    ...stackTrace: false, raises: [Exception, ValueError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}
Execute a query and return the first row, or none if no rows. 
proc queryValue(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
                timeout: Duration = ZeroDuration): Future[string] {.
    ...stackTrace: false, raises: [Exception, ValueError, CatchableError,
                                PgNoRowsError, PgNullError, PgTypeError],
    tags: [RootEffect, TimeEffect], forbids: [].}
Execute a query and return the first column of the first row as a string. Raises PgNoRowsError if no rows are returned, or PgNullError if the value is NULL. 
proc queryValue[T](conn: PgConnection; _: typedesc[T]; sql: string;
                   params: seq[PgParam] = @[]; timeout: Duration = ZeroDuration): Future[
    T] {....stackTrace: false.}
Execute a query and return the first column of the first row as T. Raises PgNoRowsError if no rows are returned, or PgNullError if the value is NULL. Supported types: int32, int64, float64, bool, string. 
proc queryValueOpt(conn: PgConnection; sql: string; params: seq[PgParam] = @[];
                   timeout: Duration = ZeroDuration): Future[Option[string]] {.
    ...stackTrace: false,
    raises: [Exception, ValueError, CatchableError, PgTypeError],
    tags: [RootEffect, TimeEffect], forbids: [].}
Execute a query and return the first column of the first row as a string. Returns none if no rows are returned or the value is NULL. 
proc queryValueOpt[T](conn: PgConnection; _: typedesc[T]; sql: string;
                      params: seq[PgParam] = @[];
                      timeout: Duration = ZeroDuration): Future[Option[T]] {.
    ...stackTrace: false.}
Execute a query and return the first column of the first row as T. Returns none if no rows are returned or the value is NULL. Supported types: int32, int64, float64, bool, string. 
proc queryValueOrDefault(conn: PgConnection; sql: string;
                         params: seq[PgParam] = @[]; default: string = "";
                         timeout: Duration = ZeroDuration): Future[string] {.
    ...stackTrace: false,
    raises: [Exception, ValueError, CatchableError, PgTypeError],
    tags: [RootEffect, TimeEffect], forbids: [].}
Execute a query and return the first column of the first row as a string. Returns default if no rows or the value is NULL. 
proc queryValueOrDefault[T](conn: PgConnection; _: typedesc[T]; sql: string;
                            params: seq[PgParam] = @[]; default: T;
                            timeout: Duration = ZeroDuration): Future[T] {.
    ...stackTrace: false.}
Execute a query and return the first column of the first row as T. Returns default if no rows or the value is NULL. Supported types: int32, int64, float64, bool, string. 
proc queryValueOrDefault[T](conn: PgConnection; sql: string;
                            params: seq[PgParam] = @[]; default: T;
                            timeout: Duration = ZeroDuration): Future[T] {.
    ...stackTrace: false.}
Execute a query and return the first column of the first row as T, inferring T from default. Returns default if no rows or the value is NULL. Supported types: int32, int64, float64, bool, string.

Made with Nim. Generated: 2026-05-29 11:06:38 UTC