async_postgres/pg_protocol

Search:
Group by:

Types

BackendMessage = object
  case kind*: BackendMessageKind
  of bmkAuthenticationOk, bmkAuthenticationCleartextPassword:
    nil
  of bmkAuthenticationMD5Password:
    md5Salt*: array[4, byte]
  of bmkAuthenticationSASL:
    saslMechanisms*: seq[string]
  of bmkAuthenticationSASLContinue:
    saslData*: seq[byte]
  of bmkAuthenticationSASLFinal:
    saslFinalData*: seq[byte]
  of bmkBackendKeyData:
    backendPid*: int32
    backendSecretKey*: int32
  of bmkBindComplete, bmkCloseComplete, bmkNoData, bmkEmptyQueryResponse,
     bmkParseComplete, bmkPortalSuspended, bmkCopyDone:
    nil
  of bmkCommandComplete:
    commandTag*: string
  of bmkCopyInResponse, bmkCopyOutResponse, bmkCopyBothResponse:
    copyFormat*: CopyFormat
    copyColumnFormats*: seq[int16]
  of bmkCopyData:
    copyData*: seq[byte]
  of bmkDataRow:
    columns*: seq[Option[seq[byte]]]
  of bmkErrorResponse:
    errorFields*: seq[ErrorField]
  of bmkNegotiateProtocolVersion:
    newestMinorVersion*: int32
    unrecognizedOptions*: seq[string]
  of bmkNoticeResponse:
    noticeFields*: seq[ErrorField]
  of bmkNotificationResponse:
    notifPid*: int32
    notifChannel*: string
    notifPayload*: string
  of bmkParameterDescription:
    paramTypeOids*: seq[int32]
  of bmkParameterStatus:
    paramName*: string
    paramValue*: string
  of bmkReadyForQuery:
    txStatus*: TransactionStatus
  of bmkRowDescription:
    fields*: seq[FieldDescription]
Parsed message from the PostgreSQL backend. Variant type keyed by kind. 
BackendMessageKind = enum
  bmkAuthenticationOk, bmkAuthenticationCleartextPassword,
  bmkAuthenticationMD5Password, bmkAuthenticationSASL,
  bmkAuthenticationSASLContinue, bmkAuthenticationSASLFinal, bmkBackendKeyData,
  bmkBindComplete, bmkCloseComplete, bmkCommandComplete, bmkCopyInResponse,
  bmkCopyOutResponse, bmkCopyBothResponse, bmkCopyData, bmkCopyDone, bmkDataRow,
  bmkEmptyQueryResponse, bmkErrorResponse, bmkNegotiateProtocolVersion,
  bmkNoData, bmkNoticeResponse, bmkNotificationResponse,
  bmkParameterDescription, bmkParameterStatus, bmkParseComplete,
  bmkPortalSuspended, bmkReadyForQuery, bmkRowDescription
Message types received from server to client. 
CopyFormat = enum
  cfText = 0, cfBinary = 1
Wire format for COPY operations. 
DescribeKind = enum
  dkPortal = 80, dkStatement = 83
Target of a Describe or Close message. 
FieldDescription = object
  name*: string
  tableOid*: int32
  columnAttrNum*: int16
  typeOid*: int32
  typeSize*: int16
  typeMod*: int32
  formatCode*: int16
Column metadata from a RowDescription message. 
FrontendMessageKind = enum
  fmkStartup, fmkSSLRequest, fmkPassword, fmkSASLInitialResponse,
  fmkSASLResponse, fmkQuery, fmkParse, fmkBind, fmkDescribe, fmkExecute,
  fmkClose, fmkSync, fmkFlush, fmkTerminate, fmkCopyData, fmkCopyDone,
  fmkCopyFail
Message types sent from client to server. 
ParseResult = object
  state*: ParseState
  message*: BackendMessage
Result of parsing bytes from the receive buffer. 
ParseState = enum
  psComplete, psIncomplete, psDataRow ## DataRow parsed in-place into RowData; no BackendMessage constructed
Row = object
Lightweight view into a single row within a RowData buffer. 
RowData = ref object
  buf*: seq[byte]            ## All column data concatenated
  cellIndex*: seq[int32]     ## [off, len, off, len, ...] per cell; len=-1 = NULL
  numCols*: int16
  colFormats*: seq[int16]    ## Per-column format codes (0=text, 1=binary)
  colTypeOids*: seq[int32]   ## Per-column type OIDs for binary→text conversion
  fields*: seq[FieldDescription] ## Column metadata for name-based access
  colMap*: Table[string, int] ## Cached name→index mapping (lazily built)
Flat buffer holding all row data for a query result. 
TransactionStatus = enum
  tsInFailedTransaction = 69, tsIdle = 73, tsInTransaction = 84
Server transaction state reported in ReadyForQuery.

Consts

BinarySafeOids = [16'i32, 17, 20, 21, 23, 25, 114, 142, 143, 600, 601, 602, 603,
                  604, 628, 629, 650, 651, 700, 701, 718, 719, 774, 775, 790,
                  791, 829, 869, 1000, 1001, 1005, 1007, 1009, 1015, 1016, 1017,
                  1018, 1019, 1020, 1021, 1022, 1027, 1040, 1041, 1043, 1082,
                  1083, 1114, 1115, 1182, 1183, 1184, 1185, 1186, 1187, 1231,
                  1266, 1270, 1560, 1561, 1562, 1563, 1700, 2950, 2951, 3614,
                  3615, 3643, 3645, 3802, 3807, 3904, 3905, 3906, 3907, 3908,
                  3909, 3910, 3911, 3912, 3913, 3926, 3927, 4451, 4532, 4533,
                  4534, 4535, 4536, 6150, 6151, 6152, 6153, 6155, 6157]
bindLengthOverhead = 12
Beyond names+payload: length field + 2 terminators + 3 counts 
copyDoneMsg = [99'u, 0'u8, 0'u8, 0'u8, 4'u8]
Pre-built CopyDone message bytes. 
DefaultMaxBackendMessageLen = 1073741824
Default upper bound on a single backend message (header + body), 1 GiB. Prevents a malicious or broken server from causing unbounded recv-buffer growth (and OOM) by advertising an int32-max length. PostgreSQL itself bounds individual values by MaxAllocSize (~1 GiB - 1), so legitimate traffic stays well below this cap. 
flushMsg = [72'u, 0'u8, 0'u8, 0'u8, 4'u8]
Pre-built Flush message bytes. 
MaxErrorOrNoticeFields = 128
Upper bound on fields in a single ErrorResponse/NoticeResponse. Only about 20 field codes exist in the protocol; 128 leaves ample room for future codes while capping worst-case allocation. 
maxInt16Count = 32767
Maximum element count encodable in a wire Int16 count field (32767). Parameter-type, format-code, and parameter-value counts in Parse/Bind messages are all Int16, so they cannot represent more elements than this. 
maxInt32Len = 2147483647
Maximum byte length encodable in a wire Int32 length field (2147483647). Parameter values, SASL data, binary COPY fields, and every message length are Int32. PostgreSQL further caps a single value at MaxAllocSize (~1 GiB - 1), so legitimate payloads stay well below this. 
MaxNegotiateProtocolOptions = 1024
Upper bound on the _pq_.* option count in NegotiateProtocolVersion. The server only echoes back options the client sent, so real counts are tiny. Bounding by message length alone still buys a 16-byte string header per wire byte: 1 GiB in, 16 GiB preallocated, OutOfMemDefect. 
MaxSaslMechanisms = 64
Upper bound on advertised SASL mechanisms in AuthenticationSASL. Only SCRAM-SHA-256 and SCRAM-SHA-256-PLUS are standardised; 64 leaves room for future mechanisms while bounding pre-auth allocation. 
MaxServerParams = 256
Upper bound on distinct ParameterStatus keys kept in serverParams. A real server sends about 50 GUCs; 256 leaves room for custom settings while capping hostile distinct-key flooding across many small messages (each already under DefaultMaxBackendMessageLen). 
MaxServerParamsBytes = 1048576
Upper bound on the total name+value byte size of serverParams (1 MiB). Legitimate GUC values are tiny; this caps amplification when many medium-sized keys arrive under the per-message length limit. 
parseLengthOverhead = 8
Beyond stmtName.len+sql.len+4*n: length field + 2 terminators + count
pgCopyBinaryHeader: array[19, byte] = [80'u, 71'u, 67'u, 79'u, 80'u, 89'u, 10'u,
                                       0xFF'u8, 13'u, 10'u, 0x00'u8, 0x00'u8,
                                       0x00'u8, 0x00'u8, 0x00'u8, 0x00'u8,
                                       0x00'u8, 0x00'u8, 0x00'u8]
pgCopyBinaryTrailer: array[2, byte] = [0xFF'u8, 0xFF'u8]
PGCOPY binary format trailer (int16(-1) sentinel). 
startupDatabaseKey = "database"
startupFixedBytes = 9'i64
Outside the key/value pairs: Int32 length + Int32 version + terminator. 
startupUserKey = "user"
syncMsg = [83'u, 0'u8, 0'u8, 0'u8, 4'u8]
Pre-built Sync message bytes.

Procs

proc addBind(buf: var seq[byte]; portalName: string; stmtName: string;
             paramFormats: openArray[int16];
             paramValues: openArray[Option[seq[byte]]];
             resultFormats: openArray[int16] = []) {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Append a Bind message to the buffer (extended query protocol). 
proc addBindPayload(payload: var int64; vlen: int) {....raises: [PgTypeError],
    tags: [], forbids: [].}
Fold one parameter value's length into the Bind payload total, bounding both the element and the running sum (int64, so it cannot wrap). 
proc addBindRaw(buf: var seq[byte]; portalName: string; stmtName: string;
                paramFormats: openArray[int16]; paramData: openArray[byte];
                paramRanges: openArray[tuple[off: int32, len: int32]];
                resultFormats: openArray[int16] = []) {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Append Bind from raw buffer and ranges. len==-1 is NULL; else paramData[off..<off+len]. Raises PgTypeError for invalid ranges. 
proc addClose(buf: var seq[byte]; kind: DescribeKind; name: string) {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Append a Close message to the buffer (portal or statement). 
proc addCopyBinaryHeader(buf: var seq[byte]) {....raises: [], tags: [], forbids: [].}
Append the PostgreSQL binary COPY header (signature + flags + extension area). 
proc addCopyBinaryTrailer(buf: var seq[byte]) {....raises: [], tags: [],
    forbids: [].}
Append the binary COPY trailer (int16 = -1). 
proc addCopyDone(buf: var seq[byte]) {....raises: [PgProtocolError], tags: [],
                                       forbids: [].}
Append a CopyDone message to the buffer. 
proc addCopyFieldBool(buf: var seq[byte]; val: bool) {....raises: [], tags: [],
    forbids: [].}
Append a boolean field in binary COPY format. 
proc addCopyFieldFloat32(buf: var seq[byte]; val: float32) {....raises: [],
    tags: [], forbids: [].}
Append a float32 field in binary COPY format. 
proc addCopyFieldFloat64(buf: var seq[byte]; val: float64) {....raises: [],
    tags: [], forbids: [].}
Append a float64 field in binary COPY format. 
proc addCopyFieldInt16(buf: var seq[byte]; val: int16) {....raises: [], tags: [],
    forbids: [].}
Append an int16 field in binary COPY format. 
proc addCopyFieldInt32(buf: var seq[byte]; val: int32) {....raises: [], tags: [],
    forbids: [].}
Append an int32 field in binary COPY format. 
proc addCopyFieldInt64(buf: var seq[byte]; val: int64) {....raises: [], tags: [],
    forbids: [].}
Append an int64 field in binary COPY format. 
proc addCopyFieldNull(buf: var seq[byte]) {....raises: [], tags: [], forbids: [].}
Append a NULL field in binary COPY format. 
proc addCopyFieldString(buf: var seq[byte]; val: string) {.
    ...raises: [PgTypeError], tags: [], forbids: [].}
Append a string field in binary COPY format. 
proc addCopyFieldText(buf: var seq[byte]; val: openArray[byte]) {.
    ...raises: [PgTypeError], tags: [], forbids: [].}
Append a raw byte field in binary COPY format. 
proc addCopyTupleStart(buf: var seq[byte]; numCols: int16) {....raises: [],
    tags: [], forbids: [].}
Start a new tuple in binary COPY format with the given column count. 
proc addCount16(buf: var seq[byte]; n: int; what: string) {.
    ...raises: [PgTypeError], tags: [], forbids: [].}
Append Int16 count field. Rejects overflow with PgTypeError — catchable under except PgError, unlike RangeDefect from int16(n). 
proc addCString(buf: var seq[byte]; s: string; what = "protocol string") {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Append NUL-terminated C string. Raises PgTypeError on embedded NUL. 
proc addDescribe(buf: var seq[byte]; kind: DescribeKind; name: string) {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Append a Describe message to the buffer (portal or statement). 
proc addExecute(buf: var seq[byte]; portalName: string; maxRows: int32 = 0) {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Append an Execute message to the buffer. maxRows of 0 means unlimited. 
proc addFlush(buf: var seq[byte]) {....raises: [PgProtocolError], tags: [],
                                    forbids: [].}
Append a Flush message to the buffer. 
proc addInt16(buf: var seq[byte]; val: int16) {....raises: [], tags: [],
    forbids: [].}
Append a 16-bit integer in big-endian format to the buffer. 
proc addInt32(buf: var seq[byte]; val: int32) {....raises: [], tags: [],
    forbids: [].}
Append a 32-bit integer in big-endian format to the buffer. 
proc addInt64(buf: var seq[byte]; val: int64) {....raises: [], tags: [],
    forbids: [].}
Append a 64-bit integer in big-endian format to the buffer. 
proc addLen32(buf: var seq[byte]; n: int; what: string) {....raises: [PgTypeError],
    tags: [], forbids: [].}
Append Int32 length field. Rejects overflow with PgTypeError, matching checkPgBinLen so a hand-built PgParam fails like a toPgParam one. 
proc addParse(buf: var seq[byte]; stmtName: string; sql: string;
              paramTypeOids: openArray[int32] = []) {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Append a Parse message to the buffer (extended query protocol). 
proc addSync(buf: var seq[byte]) {....raises: [PgProtocolError], tags: [],
                                   forbids: [].}
Append a Sync message to the buffer. 
proc buildResultFormats(fields: openArray[FieldDescription]): seq[int16] {.
    ...raises: [], tags: [], forbids: [].}
Build per-column binary format codes: 1 for known safe types, 0 for others. 
func calcBindMessageLength(portalLen, stmtLen, pfLen, nParams: int;
                           payload: int64; rfLen: int): int64 {....raises: [],
    tags: [], forbids: [].}
Length value of a Bind message. payload is the sum of parameter value bytes. 
func calcParseMessageLength(stmtNameLen, sqlLen, nParams: int): int64 {.
    ...raises: [], tags: [], forbids: [].}
Length value (wire Int32) of a Parse message, shared by pre-flight and encoder so the two cannot drift. 
proc calcStartupBudget(userLen: int; databaseLen: int): int64 {....raises: [],
    tags: [], forbids: [].}
StartupMessage size with only the fixed user/database pairs. encodeStartup seeds its budget from this so the two cannot drift. 
proc checkCopyDataLen(dataLen: int) {.inline, ...raises: [PgTypeError], tags: [],
                                      forbids: [].}
Guard CopyData Int32 length (payload+4). Exported for testing only. 
func checkNoNul(s: string; what: string) {....raises: [PgTypeError], tags: [],
    forbids: [].}
Reject embedded NUL in protocol string: it would split fields or allow startup-parameter injection. Raises PgTypeError. 
proc checkStartupBudget(budget: int64) {....raises: [PgMessageTooLargeError],
    tags: [], forbids: [].}
Reject a StartupMessage too large for its Int32 length field. Split out so tests can reach the raise without a 2 GiB allocation. 
proc clone(row: Row): Row {....raises: [PgProtocolError], tags: [], forbids: [].}
Return a deep copy of row with an independent RowData backing buffer containing only this single row. Use this to retain rows from a queryEach callback beyond the callback's lifetime — the original buffer is reused for subsequent rows and would otherwise be overwritten. 
func data(row: Row): RowData {....raises: [], tags: [], forbids: [].}
The underlying RowData buffer. 
proc decodeCString(buf: openArray[byte]; offset: int): (string, int) {.
    ...raises: [PgProtocolError], tags: [], forbids: [].}
Decode a null-terminated string at the given offset. Returns (string, bytes consumed). 
proc decodeInt16(buf: openArray[byte]; offset: int): int16 {.inline, ...raises: [],
    tags: [], forbids: [].}
Decode a 16-bit integer from big-endian bytes at the given offset. 
proc decodeInt32(buf: openArray[byte]; offset: int): int32 {.inline, ...raises: [],
    tags: [], forbids: [].}
Decode a 32-bit integer from big-endian bytes at the given offset. 
proc decodeInt64(buf: openArray[byte]; offset: int): int64 {.inline, ...raises: [],
    tags: [], forbids: [].}
Decode a 64-bit integer from big-endian bytes at the given offset. 
proc encodeBind(portalName: string; stmtName: string;
                paramFormats: openArray[int16];
                paramValues: openArray[Option[seq[byte]]];
                resultFormats: openArray[int16] = []): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a standalone Bind message. 
proc encodeCancelRequest(pid: int32; secretKey: int32): seq[byte] {....raises: [],
    tags: [], forbids: [].}
Encode a CancelRequest message to abort a running query. 
proc encodeClose(kind: DescribeKind; name: string): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a standalone Close message. 
proc encodeCopyData(buf: var seq[byte]; data: openArray[byte]) {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode CopyData message. Raises PgTypeError for oversized payload. 
proc encodeCopyDone(): seq[byte] {....raises: [], tags: [], forbids: [].}
Encode a standalone CopyDone message. 
proc encodeCopyFail(errorMsg: string): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a CopyFail message to abort a COPY operation with an error. 
proc encodeDescribe(kind: DescribeKind; name: string): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a standalone Describe message. 
proc encodeExecute(portalName: string; maxRows: int32 = 0): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a standalone Execute message. 
proc encodeFlush(): seq[byte] {....raises: [], tags: [], forbids: [].}
Encode a standalone Flush message. 
proc encodeInt16(val: int16): array[2, byte] {.inline, ...raises: [], tags: [],
    forbids: [].}
Encode a 16-bit integer as big-endian bytes. 
proc encodeInt32(val: int32): array[4, byte] {.inline, ...raises: [], tags: [],
    forbids: [].}
Encode a 32-bit integer as big-endian bytes. 
proc encodeParse(stmtName: string; sql: string;
                 paramTypeOids: openArray[int32] = []): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a standalone Parse message. 
proc encodePassword(password: string): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a PasswordMessage for cleartext or MD5 authentication. Pre-allocates the buffer so internal add calls do not realloc and leave residual copies of the password in freed heap memory. 
proc encodeQuery(sql: string): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a simple Query message. 
proc encodeSASLInitialResponse(mechanism: string; data: seq[byte]): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a SASLInitialResponse message with the chosen mechanism and client-first data. 
proc encodeSASLResponse(data: seq[byte]): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}
Encode a SASLResponse message with client-final data. 
proc encodeSSLRequest(): seq[byte] {....raises: [], tags: [], forbids: [].}
Encode an SSLRequest message (magic number 80877103). 
proc encodeStandbyStatusUpdate(receiveLsn, flushLsn, applyLsn, sendTime: int64;
                               reply: byte): seq[byte] {....raises: [], tags: [],
    forbids: [].}
Encode a Standby Status Update as a CopyData message. The inner format is: byte 'r' + receiveLsn(8) + flushLsn(8) + applyLsn(8) + sendTime(8) + reply(1) = 34 bytes payload. 
proc encodeStartup(user: string; database: string;
                   extraParams: openArray[(string, string)] = []): seq[byte] {.
    ...raises: [PgTypeError, PgProtocolError], tags: [], forbids: [].}

Encode StartupMessage (v3.0). Raises PgTypeError for NUL, for an empty key, and for Int32 overflow.

The explicit raises on the encode* group machine-checks the contract: PgTypeError for caller input, PgProtocolError for an encoder bug.

proc encodeSync(): seq[byte] {....raises: [], tags: [], forbids: [].}
Encode a standalone Sync message. 
proc encodeTerminate(): seq[byte] {....raises: [], tags: [], forbids: [].}
Encode a Terminate message to close the connection. 
proc formatError(fields: seq[ErrorField]): string {....raises: [], tags: [],
    forbids: [].}
Format error fields into a human-readable error message with severity, SQLSTATE, detail, and hint. 
func initRow(data: RowData; rowIdx: int32): Row {....raises: [], tags: [],
    forbids: [].}
Create a Row view into the given RowData at the specified row index. 
func isBinarySafeOid(oid: int32): bool {....raises: [], tags: [], forbids: [].}
Check if a type OID can be safely requested in binary format. 
proc newRowData(numCols: int16; colFormats: seq[int16] = @[];
                colTypeOids: seq[int32] = @[]): RowData {....raises: [], tags: [],
    forbids: [].}
Create a new RowData flat buffer for accumulating DataRow messages. 
proc outstandingReplies(data: openArray[byte]): tuple[syncPoints: int,
    unsynced: bool] {....raises: [], tags: [], forbids: [].}

What data leaves the backend owing: syncPoints is the number of ReadyForQuery replies it must send, and unsynced says whether replies were asked for past the last of them, with nothing to close the stream.

Read off the bytes rather than declared by whoever assembled them: no build site has to remember to say so, and a batch carrying one Sync per operation is counted as the several replies it is actually owed.

Framing this cannot walk is charged conservatively (owedForUnreadable): overcounting only retires a reusable connection, while undercounting hands the next borrower a stream with someone else's reply still in it.

proc parseBackendMessage(buf: openArray[byte]; consumed: var int;
                         rowData: RowData = nil;
                         maxLen: int = DefaultMaxBackendMessageLen;
                         skipDataRow: bool = false): ParseResult {.
    ...raises: [PgProtocolError], tags: [], forbids: [].}
Parse one backend message. Sets consumed bytes. Rejects messages over maxLen (<= 0 disables the cap, for tests; production resolves it via effectiveMaxMessageSize). With skipDataRow DataRow is framed only. 
proc parseDataRowInto(body: openArray[byte]; rd: RowData) {.
    ...raises: [PgProtocolError], tags: [], forbids: [].}
Parse DataRow directly into RowData flat buffer. 
proc patchLen(buf: var seq[byte]; offset: int = 1) {.
    ...raises: [PgProtocolError, PgMessageTooLargeError], tags: [], forbids: [].}
Patch length at offset. Int32 overflow raises PgMessageTooLargeError (caller data sized the message); a bad offset is an encoder bug and stays a PgProtocolError. 
proc patchMsgLen(buf: var seq[byte]; msgStart: int) {.
    ...raises: [PgProtocolError, PgMessageTooLargeError], tags: [], forbids: [].}
Patch length for message at msgStart. Same error split as patchLen. 
proc patchMsgLenAtomic(buf: var seq[byte]; msgStart: int) {.
    ...raises: [PgProtocolError, PgMessageTooLargeError], tags: [], forbids: [].}
patchMsgLen, but truncates buf back to msgStart before raising. For the direct macros: a try spliced into the caller's async body trips orc's injectdestructors, so they pre-flight instead and this stays their only raise. A negative msgStart has no rollback point. 
proc preflightBindCounts(portalName, stmtName: string;
                         pfLen, nParams, rfLen: int) {....raises: [PgTypeError],
    tags: [], forbids: [].}
NUL and Int16-count pre-flight shared by every Bind builder. 
proc preflightBindDirect(portalName, stmtName: string; nParams, rfLen: int;
                         payload: int64) {....raises: [PgTypeError], tags: [],
    forbids: [].}
Whole pre-flight for addBindDirect. payload is what foldBindParam summed; the macro writes one format code per argument. 
proc preflightParseDirect(stmtName, sql: string; nParams: int) {.
    ...raises: [PgTypeError], tags: [], forbids: [].}
Whole pre-flight for addParseDirect, so its write phase cannot raise. No count guard: the macro already narrows nParams to int16. 
proc reuseRowData(rd: RowData; numCols: int16): RowData {....raises: [], tags: [],
    forbids: [].}
Create a new RowData that takes over the old buffer's capacity via move, without format metadata. rd remains a valid ref but its buf/cellIndex/colFormats/colTypeOids are emptied — callers still holding rd must not read row data or formats through it after this call. 
proc reuseRowData(rd: RowData; numCols: int16; colFormats: sink seq[int16];
                  colTypeOids: sink seq[int32]): RowData {....raises: [], tags: [],
    forbids: [].}
Create a new RowData that takes over the old buffer's capacity via move. rd remains a valid ref but its buf/cellIndex are emptied — callers still holding rd must not read row data through it after this call. 
func rowIdx(row: Row): int32 {....raises: [], tags: [], forbids: [].}
The row index within the RowData buffer. 
func startupParamBytes(keyLen: int; valueLen: int): int64 {....raises: [],
    tags: [], forbids: [].}
Wire size of one StartupMessage key/value pair (k+NUL + v+NUL).

Templates

template checkMsgLenBound64(lenVal: int64; what: untyped)
Bound an assembled message length against the protocol's Int32 field. Raises what patchMsgLen does, so both are one contract for the caller. 
template withAtomicMessage(buf: var seq[byte]; body: untyped)
Restore buf.len on PgTypeError, PgProtocolError or Defect, so a failed builder leaves no half-written message. Narrow on purpose: any other CatchableError belongs in the pre-flight, not in a rollback here.

Made with Nim. Generated: 2026-09-11 08:44:47 UTC