Procs
proc coerceBinaryParam(param: PgParam; serverOid: int32): PgParam {. ...raises: [PgTypeError], tags: [], forbids: [].}
- Return a copy of param whose binary payload matches serverOid. Text-format parameters (format == 0) and matching OIDs are returned unchanged. For binary-format parameters with a type mismatch, safe widening conversions are applied.
proc encodeBinaryArray(elemOid: int32; elements: seq[Option[seq[byte]]]): seq[ byte] {....raises: [PgError], tags: [], forbids: [].}
- Encode a 1-dimensional binary array that may contain NULL elements. NULL elements are written with length -1 and no payload. has_null is set to 1 iff any element is none.
proc encodeBinaryArray(elemOid: int32; elements: seq[seq[byte]]): seq[byte] {. ...raises: [PgError], tags: [], forbids: [].}
- Encode a 1-dimensional PostgreSQL binary array. Header: ndim(4) + has_null(4) + elem_oid(4) + dim_len(4) + lower_bound(4) = 20 bytes Each element: len(4) + data
proc encodeBinaryArrayEmpty(elemOid: int32): seq[byte] {....raises: [], tags: [], forbids: [].}
- Encode an empty 1-dimensional PostgreSQL binary array. ndim=0, has_null=0, elem_oid
proc encodeHstoreBinary(v: PgHstore): seq[byte] {....raises: [], tags: [], forbids: [].}
- Encode hstore as PostgreSQL binary format. Format: numPairs(int32) + [keyLen(int32) + keyData + valLen(int32) + valData]...
proc encodeHstoreText(v: PgHstore): string {....raises: [], tags: [], forbids: [].}
- Encode hstore as PostgreSQL text format: "key1"=>"val1", "key2"=>NULL.
proc encodeNumericBinary(v: PgNumeric): seq[byte] {....raises: [], tags: [], forbids: [].}
- Encode PgNumeric as PostgreSQL binary numeric format.
proc encodePointBinary(p: PgPoint): seq[byte] {....raises: [], tags: [], forbids: [].}
- Encode a point as 16 bytes (two float64 big-endian).
proc toPgBinaryDateParam(v: DateTime): PgParam {....raises: [], tags: [], forbids: [].}
- Encode a DateTime as a binary date parameter (OID 1082).
proc toPgBinaryParam(v: bool): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: DateTime): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: float32): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: float64): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: int): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: int16): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: int32): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: int64): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: JsonNode): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: Option[JsonNode]): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: PgBit): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: 4-byte bit count (big-endian) + packed bit data.
proc toPgBinaryParam(v: PgBox): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: 32 bytes (high point, low point).
proc toPgBinaryParam(v: PgCidr): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: family(1) + bits(1) + is_cidr(1) + addrlen(1) + addr(4|16)
proc toPgBinaryParam(v: PgCircle): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: 24 bytes (center point + radius float64).
proc toPgBinaryParam(v: PgHstore; oid: int32): PgParam {....raises: [], tags: [], forbids: [].}
- Encode hstore in binary format. Requires the dynamic hstore OID (available as conn.hstoreOid after connection).
proc toPgBinaryParam(v: PgInet): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: family(1) + bits(1) + is_cidr(1) + addrlen(1) + addr(4|16)
proc toPgBinaryParam(v: PgInterval): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: PgLine): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: 24 bytes (three float64 big-endian: A, B, C).
proc toPgBinaryParam(v: PgLseg): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: 32 bytes (two points).
proc toPgBinaryParam(v: PgMacAddr): PgParam {....raises: [ValueError], tags: [], forbids: [].}
- Binary format: 6 raw bytes
proc toPgBinaryParam(v: PgMacAddr8): PgParam {....raises: [ValueError], tags: [], forbids: [].}
- Binary format: 8 raw bytes
proc toPgBinaryParam(v: PgMoney): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: PgNumeric): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: PgPath): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: closed(1) + npts(4) + points(npts * 16).
proc toPgBinaryParam(v: PgPoint): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: 16 bytes (two float64 big-endian).
proc toPgBinaryParam(v: PgPolygon): PgParam {....raises: [], tags: [], forbids: [].}
- Binary format: npts(4) + points(npts * 16).
proc toPgBinaryParam(v: PgTime): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: PgTimeTz): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: PgTsQuery): PgParam {....raises: [], tags: [], forbids: [].}
- Send as text format — PostgreSQL handles the parsing.
proc toPgBinaryParam(v: PgTsVector): PgParam {....raises: [], tags: [], forbids: [].}
- Send as text format — PostgreSQL handles the parsing.
proc toPgBinaryParam(v: PgUuid): PgParam {....raises: [ValueError], tags: [], forbids: [].}
proc toPgBinaryParam(v: PgXml): PgParam {....raises: [], tags: [], forbids: [].}
- Binary wire format for xml is the text representation itself.
proc toPgBinaryParam(v: seq[byte]): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgBinaryParam(v: seq[PgBit]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgBinaryParam(v: seq[PgHstore]; elemOid: int32; arrayOid: int32): PgParam {. ...raises: [PgError], tags: [], forbids: [].}
- Encode hstore[] in binary format. Requires both the dynamic hstore OID and hstore[] OID (available as conn.hstoreOid and conn.hstoreArrayOid after connection). See also the PgConnection overload in pg_connection which reads these OIDs automatically.
proc toPgBinaryParam(v: string): PgParam {....raises: [], tags: [], forbids: [].}
- Convert a Nim value to a PgParam using binary format. Prefer this over toPgParam when binary format is needed for all types.
proc toPgBinaryParam[T](v: Option[T]): PgParam
proc toPgBinaryParam[T](v: seq[T]): PgParam
proc toPgBinaryTimestampTzParam(v: DateTime): PgParam {....raises: [], tags: [], forbids: [].}
- Encode a DateTime as a binary timestamptz parameter (OID 1184).
proc toPgByteaArrayParam(v: seq[seq[byte]]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgDateArrayParam(v: seq[DateTime]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgDateParam(v: DateTime): PgParam {....raises: [], tags: [], forbids: [].}
- Encode a DateTime as a date parameter (OID 1082).
proc toPgParam(v: PgHstore): PgParam {....raises: [], tags: [], forbids: [].}
- Send hstore as text format. PostgreSQL casts text to hstore implicitly.
proc toPgParam(v: PgInterval): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgParam(v: PgMacAddr8): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgParam(v: PgMoney): PgParam {....raises: [], tags: [], forbids: [].}
- Uses binary format: money's text representation is lc_monetary-dependent, so a text round-trip is not reliable. Binary sends the raw int64 amount.
proc toPgParam(v: PgTsVector): PgParam {....raises: [], tags: [], forbids: [].}
proc toPgParam(v: seq[PgHstore]): PgParam {....raises: [], tags: [], forbids: [].}
- Send hstore[] in text format using OidTextArray. Requires an explicit ::hstore[] cast in the SQL statement (e.g. SELECT $1::hstore[]), since the parameter is typed as text[]. No connection-specific OID is needed; prefer toPgBinaryParam when a PgConnection with the discovered hstore OIDs is available (faster, no cast required).
proc toPgParam(v: string): PgParam {....raises: [], tags: [], forbids: [].}
- Convert a Nim value to a PgParam for use as a query parameter. Uses text format for strings, binary for numeric types.
proc toPgParam(v`gensym107: seq[PgInterval]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgParam(v`gensym110: seq[PgUuid]): PgParam {. ...raises: [ValueError, PgError], tags: [], forbids: [].}
proc toPgParam(v`gensym119: seq[PgMacAddr]): PgParam {. ...raises: [ValueError, PgError], tags: [], forbids: [].}
proc toPgParam(v`gensym122: seq[PgMacAddr8]): PgParam {. ...raises: [ValueError, PgError], tags: [], forbids: [].}
proc toPgParam(v`gensym128: seq[PgNumeric]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgParam(v`gensym178: seq[PgPolygon]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgParam(v`gensym187: seq[PgTsVector]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgParamInline(v: bool): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: float32): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: float64): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: int): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: int16): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: int32): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: int64): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: PgMoney): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: PgUuid): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: seq[byte]): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline(v: string): PgParamInline {....raises: [], tags: [], forbids: [].}
proc toPgParamInline[T](v: Option[T]): PgParamInline
proc toPgTimestampArrayParam(v: seq[DateTime]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgTimestampTzArrayParam(v: seq[DateTime]): PgParam {....raises: [PgError], tags: [], forbids: [].}
proc toPgTimestampTzParam(v: DateTime): PgParam {....raises: [], tags: [], forbids: [].}
- Encode a DateTime as a timestamptz parameter (OID 1184).
proc writeParamFormat(buf: var seq[byte]; v: bool) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: float32) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: float64) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: int) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: int16) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: int32) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: int64) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: PgNumeric) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: seq[byte]) {....raises: [], tags: [], forbids: [].}
proc writeParamFormat(buf: var seq[byte]; v: string) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: bool) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: float32) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: float64) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: int) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: int16) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: int32) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: int64) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: PgNumeric) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: seq[byte]) {....raises: [], tags: [], forbids: [].}
proc writeParamOid(buf: var seq[byte]; v: string) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: bool) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: float32) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: float64) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: int) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: int16) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: int32) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: int64) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: PgNumeric) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: seq[byte]) {....raises: [], tags: [], forbids: [].}
proc writeParamValue(buf: var seq[byte]; v: string) {....raises: [], tags: [], forbids: [].}
Macros
macro addBindDirect(buf: untyped; portalName: string; stmtName: string; resultFormats: untyped; args: varargs[untyped]): untyped
- Compile-time macro: generates Bind message writing params directly to buffer. Zero intermediate PgParam/seq[byte] allocations.
macro addParseDirect(buf: untyped; stmtName: string; sql: string; args: varargs[untyped]): untyped
- Compile-time macro: generates Parse message with OIDs from arg types.
macro pgParams(args: varargs[typed]): untyped
-
Convert multiple values to a seq[PgParam] in one call. At least one argument is required; for parameterless queries omit the parameter argument entirely instead of calling pgParams().
await conn.query("SELECT * FROM users WHERE age > $1 AND name = $2", pgParams(25'i32, "Alice"))
Templates
template writePointAt(dst: var openArray[byte]; pos: int; p: PgPoint)
- Write a point as 16 bytes (two float64 big-endian) into dst at pos.