Procs
proc encodeBinaryComposite(fields: seq[tuple[oid: int32, data: Option[seq[byte]]]]): seq[ byte] {....raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
- Encode a PostgreSQL binary composite value. Format: numFields(4) + [oid(4) + len(4) + data]...
proc encodeCompositeText(fields: seq[Option[string]]): string {....raises: [], tags: [], forbids: [].}
- Encode fields as PostgreSQL composite text format: (val1,val2,...)
proc encodeEnumTextArray(labels: seq[Option[string]]): string {. ...raises: [PgTypeError], tags: [], forbids: [].}
- Encode enum labels as a PostgreSQL text-format array literal. none labels become unquoted NULL.
proc getComposite[T: object](row: Row; col: int): T
- Read a PostgreSQL composite column as a Nim object. Handles binary format. A DateTime field reads a timestamp, timestamptz or date attribute, the last as midnight UTC.
proc getCompositeOpt[T: object](row: Row; col: int): Option[T]
- NULL-safe version of getComposite.
proc getDomainOpt[T: distinct](row: Row; col: int): Option[T]
- NULL-safe version of getDomain.
proc getEnumArray[T: enum](row: Row; col: int): seq[T]
- Read a PostgreSQL enum[] column as seq[T]. Raises PgTypeError on NULL column or NULL element.
proc getEnumArrayElemOpt[T: enum](row: Row; col: int): seq[Option[T]]
- Element-level NULL-safe: each element is Option[T].
proc getEnumArrayOpt[T: enum](row: Row; col: int): Option[seq[T]]
- NULL-safe column-level variant. Element NULL still raises.
proc getEnumOpt[T: enum](row: Row; col: int): Option[T]
- Read a PostgreSQL enum column as Option[T]. Returns none if NULL. NULL-safe version of getEnum.
proc parseCompositeText(s: string): seq[Option[string]] {....raises: [PgTypeError], tags: [], forbids: [].}
-
Parse PostgreSQL composite text format: (val1,val2,...) Returns fields as Option[string] (none for NULL).
Expects canonical record_out output. Inside a double-quoted field both doubled bytes ("" / \\) and backslash escapes (as accepted by the server's record_in) are decoded; a quoted field must be followed by ',' or the end. Unquoted fields reject " / \\ / ( / ) with PgTypeError: record_out always quotes such bytes, so accepting them would decode non-canonical input silently.
Macros
macro pgComposite(T: typedesc; oid: int32 = 0'i32): untyped
- Generate toPgParam for a Nim object as a PostgreSQL composite type. Each field is sent as text inside the composite text format. Fields map by position, in both directions: the object's field order must match the composite's attribute order. Neither wire format carries names, so a swap of same-typed fields is not detected. When OID is 0 (default), PostgreSQL infers the type from context. The generated overload lives in the calling module, where the sql macro and pgParams resolve it alongside the built-in ones. queryDirect / execDirect take their parameters as separate arguments and cannot encode these types.
macro pgDomain(T: typedesc; Base: typedesc; oid: int32 = 0'i32): untyped
- Generate toPgParam for a Nim distinct type as a PostgreSQL domain type. Encoding delegates to the base type's toPgParam. A distinct Base (a domain over another domain) must be one T is declared from: type T = distinct Base. When OID is 0 (default), the base type's OID is used. The generated overload lives in the calling module, where the sql macro and pgParams resolve it alongside the built-in ones. queryDirect / execDirect take their parameters as separate arguments and cannot encode these types.
macro pgEnum(T: untyped): untyped
- Generate toPgParam overloads for a Nim enum type and its array forms. OIDs are 0 (unspecified) so PostgreSQL infers the type from context (use $1::mytype / $1::mytype[] in the SQL). The generated overloads live in the calling module, where the sql macro and pgParams resolve them alongside the built-in ones. queryDirect / execDirect take their parameters as separate arguments and cannot encode these types.
macro pgEnum(T: untyped; oid: untyped): untyped
- Generate toPgParam overloads for a Nim enum type with an explicit scalar OID. The array OID is unspecified (0); add a $1::mytype[] cast in the SQL, or use the 3-argument form to set the array OID too.
macro pgEnum(T: untyped; oid: untyped; arrayOid: untyped): untyped
- Generate toPgParam overloads with explicit scalar and array OIDs.