nish/net/postgres

The client side of PostgreSQL's frontend/backend protocol, version 3.0: a sans-IO connection that writes the frontend's messages into an output buffer and reads the backend's from an input buffer, for a program that owns its socket (nish:net) and its loop.

import {
  PG_ARRAY_BAD,
  PG_ARRAY_ELEMENT,
  PG_ARRAY_END,
  PG_ARRAY_NULL,
  PG_BATCH_DONE,
  PG_BATCH_FAILED,
  PG_BATCH_INT,
  PG_BATCH_MISSING,
  PG_BATCH_NONE,
  PG_BATCH_ROW,
  PG_BATCH_TEXT,
  PG_CLOCK_AVERAGE,
  PG_CLOCK_COUNT,
  PG_CLOCK_IDLE,
  PG_CLOCK_TIMER,
  PG_CLOCK_WAIT,
  PG_COMPLETE,
  PG_DESCRIBED,
  PG_ERROR,
  PG_ERR_AUTH_UNSUPPORTED,
  PG_ERR_CLOSED,
  PG_ERR_ENCODING,
  PG_ERR_FRAME,
  PG_ERR_NONE,
  PG_ERR_SCRAM,
  PG_ERR_SERVER,
  PG_ERR_SERVER_SIGNATURE,
  PG_ERR_SETTING,
  PG_ERR_TLS,
  PG_ERR_TOO_BIG,
  PG_ERR_UNEXPECTED,
  PG_FAILED,
  PG_GROUP_DONE,
  PG_LOST,
  PG_NEED_MORE,
  PG_NOTICE,
  PG_POOL_FULL,
  PG_POOL_NONE,
  PG_READY,
  PG_ROW,
  PG_SSL_REQUEST_CODE,
  PG_TARGET_BAD_ESCAPE,
  PG_TARGET_BAD_HOST,
  PG_TARGET_BAD_PORT,
  PG_TARGET_BAD_URL,
  PG_TARGET_OK,
  PG_TARGET_TOO_LONG,
  PG_TLS_DISABLE,
  PG_TLS_REQUIRE,
  PG_TLS_VERIFY_FULL,
  PG_TURNS_FULL,
  PG_TURNS_NONE,
  PgArrayWalker,
  PgBatchClock,
  PgBatchClockConfig,
  PgBatchConfig,
  PgBatchTurns,
  PgBatcher,
  PgBinary,
  PgBinaryArray,
  PgConfig,
  PgConnection,
  PgError,
  PgPool,
  PgTarget,
  PgText,
  pgSslRequest,
  pgTarget,
  pgTargetUrl,
} from "nish/net/postgres";
import { PG_FAILED, PG_NEED_MORE, PgConfig, PgConnection } from "nish/net/postgres";
import { secret, wipe } from "nish:secret";

const config = new PgConfig();
config.user = "app";
config.database = "app";
const nonce = new Array<u8>(18);
crypto.getRandomValues(nonce);
const password = secret(passwordBytes); // a u8[] the program read from its secret store
const conn = new PgConnection(config, password, nonce);
wipe(password); // the connection keeps its own copy
// write conn.outputBuffer()[conn.outputStart() .. conn.outputEnd()), then conn.sent(n)
// read into conn.inputBuffer() at conn.inputEnd(), up to conn.inputRoom() bytes, then conn.received(n)
let event: i32 = conn.next();
while (event !== PG_NEED_MORE && event !== PG_FAILED) {
  // PG_READY: authenticated; prepare statements and send queries
  //   conn.prepare("by_id", "select id, name from users where id = $1", [23]); conn.sync()
  //   conn.bindStart("by_id"); conn.paramInt(7); conn.bindEnd(); conn.sync()
  //   or conn.bindStartBinary("by_id") for binary result columns
  // PG_ROW: conn.int(0), conn.colStart(1) .. + conn.colLength(1) in conn.inputBuffer()
  //   after bindStartBinary: conn.binaryInt(0), the text column as before
  // PG_COMPLETE: conn.tagRows(); PG_ERROR: conn.lastError.code
  // PG_GROUP_DONE: one sync()'s group has been answered
  event = conn.next();
}
Events

next() answers PG_READY once, when the server has authenticated the connection and is ready for queries; PG_DESCRIBED when a prepared statement has been described (columns and columnType(c) say what its rows hold, columns is 0 when it returns none); PG_ROW for each row, its columns as windows into the input buffer (colStart(c), colLength(c), -1 for NULL); PG_COMPLETE when an execution has finished (tagIs("UPDATE"), tagRows()); PG_ERROR when a statement in the current group failed (lastError); PG_NOTICE for a notice (lastNotice); PG_GROUP_DONE when a group has been answered to its end (groupFailed, txStatus); and PG_FAILED, final: the connection broke a rule or the server ended it, failure says which and lastError holds the server's reason when it gave one.

PG_NEED_MORE asks for more input.

Windows and buffers

A column's window, the tag tagIs and tagRows read are valid until the next next(), which may move the unread input to the start of the buffer or replace the buffer with a larger one. Fetch inputBuffer() again after every next() rather than keep it; the same holds for outputBuffer() after a builder call.

Groups and pipelining

Every statement is sent with the extended query protocol: prepare (Parse and Describe), bindStart, the param... calls and bindEnd (Bind and Execute), closeStatement (Close), then sync(), which ends the group. The server answers groups in order and skips the rest of a group after an error, so one failed statement costs only its own group. In a failed group, PG_DESCRIBED comes once for each prepare the server parsed before the error: a program that counts them knows which statements exist (named ones last past the group) and which must be prepared again.

Up to maxInFlight groups may wait for their answers at once; canSend() says whether another may start, and the builder calls refuse (and write nothing) when it may not. Nothing waits for a round trip that the protocol does not need: a program prepares a statement and executes it in the same flight.

Text results, no copies

Every parameter is in text format unless it is one of the binary integer arrays below, and every result column is text unless the bind asks otherwise. A row is read where it lies in the input buffer: next() frames each message once, validates its layout, and records each column's start and length in two reused arrays, so a row costs no allocation. int, bool, isNull and PgText.timestamp decode a column in place; PgArrayWalker walks a one-dimensional text[] in place. columnText(c) is the one that allocates, a string.

An array parameter is a text array literal too: paramIntArray writes an int8[] from an i64[] window, and arrayStart, arrayElement, arrayInt, arrayNull and arrayEnd build an array one element at a time into the Bind, so a list needs no string built first. A program whose element was refused for room can drop the whole bind, unsent, with bindCancel.

Binary integer arrays

paramInt4Array and paramInt8Array send an i64[] window as an int4[] or int8[] in PostgreSQL's binary layout: four or eight bytes an element and no digits to write or parse, which the benchmark (bench/postgres/arrays.mjs) measured at about a tenth of the text encoder's client CPU, and at 1,000 elements a 51% cut in the server's on unnest for int8[], 30% for int4[]. binaryArrayStart(oid), binaryArrayInt and binaryArrayNull build one element at a time, NULLs included, and arrayEnd closes it.

The Bind's format codes stay a single zero word while every parameter is text; the first binary one makes bindEnd write a code for each, so an all-text bind costs nothing more. An int4 element outside int4 panics rather than wrapping. The element type must match the statement's parameter: the server answers a mismatch with ErrorResponse (42804) for that execution, and the connection goes on.

Binary results

A bind opened with bindStartBinary instead of bindStart asks for every result column in binary format: an int8 is eight bytes, a timestamptz eight bytes of microseconds since 2000, a bool one byte, so there is nothing to parse and less on the wire. binaryInt, binaryBool and binaryFloat read them in place, and PgBinary's timestamp and iso write a time as PgText.timestamp does. A text column is the same bytes in either format, so columnText and the column windows read it unchanged.

The program knows which of its binds asked for which, and reads each execution's rows with the matching decoders. A PgBatcher with binary set opens each batch this way and reads its routing ordinal with binaryInt, so its rows are binary too. PgBinaryArray walks a one-dimensional int2[], int4[] or int8[] column in its binary layout, and refuses any other array (a text[] or a multi-dimensional one among them).

Authentication

SCRAM-SHA-256 (RFC 5802, RFC 7677) or none (trust). The password arrives as a Secret<u8[]>; the connection keeps a copy in a holder that is wiped as soon as the proof is computed, or when the connection fails or is disposed. The server's signature is checked in constant time before AuthenticationOk is believed, and an AuthenticationOk that skips the end of an exchange SCRAM began is refused.

Cleartext and MD5 passwords, and SASL mechanisms other than SCRAM-SHA-256, are refused: the first sends the password as it is, and the second is a hash any eavesdropper can replay, over a connection that need not be encrypted (TLS is off unless PgConfig.tls asks for it). The password's bytes are used as they are, without SASLprep (RFC 4013): an ASCII password works, and a non-ASCII one works only when it is already in the form SASLprep would give (PostgreSQL itself falls back to the raw bytes when it cannot prepare one). docs/security/postgres.md is the record.

Caps. PgConfig bounds what a server can make the client hold: the longest message (maxMessage), the widest row (maxColumns) and the SCRAM iteration count (minIterations, maxIterations); and what a program can queue unsent (maxOutput), past which a builder call answers false.

A message longer than the cap, a length below 4, a layout that does not add up, a message the protocol does not allow at that point (COPY among them), an encoding other than UTF-8, and a DateStyle other than ISO or a TimeZone other than UTC (at startup or after a SET), each fail the connection with their own failure code. The constructor panics on a cap out of range, as on a missing user or a short nonce.

Pools

PgPool holds up to size connections to one server and a FIFO queue of up to queueSize requests, still sans-IO: wanted() names a slot that needs a socket, connect(slot, nonce) starts its connection, and the program moves its bytes as above through connection(slot).

A request is a ticket from request(); dispatch() gives the oldest to the ready connection with the fewest groups in flight (or, with PgConfig.pack, to the first ready one with room, so a burst fills few connections in fuller writes), the program builds its group and ends it with send(), and next(slot) reads that connection's events with ticket naming the request. Statements given to register are prepared on each connection ahead of its first request. A connection that fails reports PG_LOST for each request it took, then PG_FAILED; the program closes the socket and the slot is built again on its next use.

Carrier

PgCarrier, in nish/net/postgres-carrier, moves a pool's bytes on an HttpHandler's loop, so a route handler queries without blocking its worker. It is a module of its own because it reads sockets, the clock and the entropy source, and this one reaches none of them.

Batching

PgBatcher turns many reads of one row shape by key — a user by id, an article by slug — into one execution of a statement over unnest($1) with ordinality.

addInt or addText queues a request's key and tag; take(conn) binds the oldest waiting, each distinct key once (past PG_BATCH_PROBES slots of its table probe, a key is bound again), up to maxRequests and maxBytes, and answers a run's handle; row, end and fail take that execution's events (a handle already answered makes them a no-op counted in stray, so a server's late event cannot panic), routing each row by its ordinal (checked first: a server's ordinal is refused before it routes anything), and next(run) answers PG_BATCH_ROW, then PG_BATCH_DONE, PG_BATCH_MISSING or PG_BATCH_FAILED, for each request.

The statement orders its rows by ordinal, so a key's last events come as soon as a later key's row does; with sorted false it does not (no Sort node, when orderBy is ""), rows are answered in whatever order they come, and every last event waits for the execution's end. It reads no clock, and the batcher itself allocates only in its constructor (the connection's output buffer a take writes into may still grow, up to its maxOutput); when to take is the program's.

Batch timing

PgBatchClock is one answer to when: given the time in microseconds, check(now, inFlight) says a batch is due once max(minCount, the moving average of recent batch sizes × factor) items wait, once the oldest has waited maxWaitUs, or, with the idle bypass on, at once when nothing is in flight and fewer than lightCount arrived in the last lightWindowUs; average, lastSize, lastReason and startsFor are its metrics. Its defaults are the fixed window. PgBatcher.takeDue takes only when its clock says so, and PgBatchTurns lets one free connection collect while the others execute, woken only when its batch is due. Neither reads a clock or allocates per item.

Written from PostgreSQL's "Frontend/Backend Protocol" chapter (version 18) and RFC 5802 and RFC 7677; not ported from another implementation.

Functions

pgSslRequest

The 8-byte SSLRequest a client sends before its StartupMessage to ask for TLS: its length, 8, and PG_SSL_REQUEST_CODE, both big-endian. The server answers one byte, S to go on with a TLS handshake or N to refuse.

const pgSslRequest: () => u8[]
returnsu8[]

A new 8-byte array holding the message.

pgTarget

The target host and port name, as libpq's host and port do: a host starting with / or @ is the socket <host>/.s.PGSQL.<port>, any other a TCP host. The host is not percent-decoded. A port outside 1 to 65535, an empty host, a , (more than one host) or a NUL byte is refused, and so is a socket path over 107 bytes (an @ name over 107 after its @), never cut short.

const pgTarget: (host: string, port: i32) => PgTarget
hoststringrequired

The host, a socket directory starting with /, or an abstract name starting with @; taken as it is, not percent-decoded.

porti32required

The TCP port, or the number in the socket's name, from 1 to 65535.

returnsPgTarget

The target; read failure before anything else.

pgTargetUrl

The target a postgres:// or postgresql:// URL names, as libpq reads one: postgres://[user[:password]@][host][:port][/dbname][?key=value&...]. The host, the port and every query key and value are percent-decoded, so a socket directory is written %2Ftmp or passed as ?host=/tmp; a host or port in the query overrides the authority's, and other keys are ignored. The user, password and database are not read here, but a bad escape in them still refuses the URL. A % without two hex digits after it, %00, or a part that decodes to bytes that are not UTF-8 is PG_TARGET_BAD_ESCAPE.

The user information ends at the first @, as in libpq; a raw @ after a ? or after that first @ in the authority, or a raw NUL byte anywhere, is PG_TARGET_BAD_HOST, as is a URL with no host anywhere, where libpq would use its default socket directory. An empty port or query value is refused, where libpq would take it as unset. The decoded host is then resolved as pgTarget resolves one.

const pgTargetUrl: (url: string) => PgTarget
urlstringrequired

The URL; any user or password it holds is not kept in the target.

returnsPgTarget

The target; read failure before anything else.

Classes

PgArrayWalker

A walk over a one-dimensional text[] column in place: begin the column, then next() until PG_ARRAY_END or PG_ARRAY_BAD. Each element is the window [start, start + length) of the column's buffer; a quoted element with a backslash escape in it has escaped set, and copy writes its bytes unescaped. An unquoted NULL, in any case, is PG_ARRAY_NULL. Dimension decorations ([1:2]={...}) and nested arrays are PG_ARRAY_BAD.

class PgArrayWalker
Member
new PgArrayWalker() A walker with nothing begun; next() answers PG_ARRAY_END until begin.
escaped: boolean Whether the current element holds a backslash escape.
length: i32 The current element's length, escapes included.
start: i32 The current element's first byte in the buffer.
begin(b: u8[], start: i32, length: i32): void Starts a walk over b[start, start + length), which must be a {...} literal; anything else makes next() answer PG_ARRAY_BAD. The walker keeps b and reads it until the next begin, so for a column the walk must end before the connection's next next().
copy(out: u8[], at: i32): i32 Writes the current element, unescaped (each backslash dropped and the byte after it kept), to out[at, ...). Nothing is allocated.
next(): i32 Steps to the next element, setting start, length and escaped.

PgBatchClock

Says when to start a batch, sans-IO like PgBatcher: the program passes the time, in microseconds from any fixed point, and the clock reads none. It keeps the arrival time of each waiting item, oldest first, and the moving average (EWMA) of the batches started. check answers the reason a batch should start now, or PG_CLOCK_WAIT: the target count is waiting (the larger of minCount and the average times factor, never more than maxCount), the oldest has waited maxWaitUs, or, with the idle bypass on, nothing is in flight and the load is light. deadline() is when the timer fires, for a poll's timeout.

Under a backlog the target is already waiting, so the batch starts by count the moment a connection is free, and nothing waits on the timer; a batch started by count is at least the target, so the average does not fall while the backlog lasts. Only a batch the timer or the bypass starts can be smaller than the average and pull it down, as the load falls.

The program mirrors its queue: arrived(now) for each item queued, started(size, now) for each batch taken, oldest items first. A PgBatcher does both itself through takeDue; a program forming its own batches calls them by hand. The fields after a start are for metrics. Everything is allocated in the constructor; nothing per item.

class PgBatchClock
Member
new PgBatchClock(config: PgBatchClockConfig) A clock for config; panics when a setting is out of the range its field names, or minCount is above maxCount.
average: f64 The moving average of the batch sizes started, 0 before the first.
lastReason: i32 Why the last batch started: the reason check last answered, PG_CLOCK_WAIT when it started without one.
lastSize: i32 The size of the last batch started, 0 before the first.
lastWaitUs: i64 How long the oldest item of the last batch waited, in microseconds.
arrived(nowUs: i64): boolean Records an item queued at nowUs; false when queueSize are waiting. A time before the last one given counts as the last one, so a clock that steps back cannot make an item older than its neighbours.
check(nowUs: i64, inFlight: i32): i32 The reason a batch should start at nowUs, with inFlight batches (or groups) still running, or PG_CLOCK_WAIT. It only says; the program starts the batch when a connection is free, then calls started.
deadline(): i64 When the oldest waiting item will have waited maxWaitUs.
started(size: i32, nowUs: i64): void Records a batch of the size oldest items started at nowUs, and moves the average toward it; the first batch sets it. Panics when size is below 1 or more than are waiting or than maxCount.
startsFor(reason: i32): i64 How many batches have started for reason, one of the PG_CLOCK_* (PG_CLOCK_WAIT counts those started without a due check). Panics on any other reason.
target(): i32 The count that starts a batch now.
waiting(): i32 How many items wait for a batch.

PgBatchClockConfig

When a PgBatchClock starts a batch. The defaults are the fixed window: a batch starts when maxCount items wait or the oldest has waited maxWaitUs, whatever the load. To adapt, set factor (1.1 is a good start), lower minCount (16), and turn on the idle bypass (lightCount 8); bench/pg-batch-clock.ts measures each against the fixed windows.

class PgBatchClockConfig
Member
new PgBatchClockConfig()
factor: f64 The share of the recent batch size that must wait before a batch starts, 0 to 64; 0 leaves the average out, the fixed window. Above 1 batches grow until the timer bounds them (fewer statements, more wait); below 1 they shrink toward minCount.
lightCount: i32 The idle bypass: with nothing in flight and fewer than lightCount items arrived in the last lightWindowUs, an item goes at once. 0, the default, turns it off; up to 1024.
lightWindowUs: i64 The window lightCount counts arrivals over, in microseconds, 0 to a minute.
maxCount: i32 The most items one batch takes, PgBatchConfig.maxRequests for a batcher's clock. The count to start never passes it, so a backlog always starts by count.
maxWaitUs: i64 The longest the oldest item waits for others, in microseconds, 0 to a minute: the most latency batching adds when the load is light.
minCount: i32 The fewest items that start a batch by count. Lower answers sooner under light load and spends more statements per item; maxCount is the fixed window.
queueSize: i32 The most items waiting, 1 to 2^20: PgBatchConfig.queueSize for a batcher's clock.
weight: f64 How far each batch moves the average, over 0 up to 1. Higher follows a change of load sooner and jumps more on one odd batch.

PgBatchConfig

What a PgBatcher sends: one statement shape, its key, and its caps.

class PgBatchConfig
Member
new PgBatchConfig()
binary: boolean Whether every row of a batch comes in binary format, read with the binary decoders and its ordinal by binaryInt; false for text.
keyType: i32 PG_BATCH_INT or PG_BATCH_TEXT.
maxBytes: i32 The most bytes the key array parameter takes, {} included.
maxRequests: i32 The most requests one execution answers.
name: string The prepared statement's name, which PgBatcher.sql is prepared under.
orderBy: string Columns of t, the query's rows, ordering the rows of one key: t.created_at desc; "" for none.
queueBytes: i32 The most bytes of text keys waiting.
queueSize: i32 The most requests waiting.
runs: i32 The most executions in flight at once.
select: string The query for one key, q.key: select id, title from articles where slug = q.key.
sorted: boolean Whether the statement orders its rows by ordinal, so each key's last event comes as soon as a later key's row does. False drops q.ord from the order by (and the Sort node it costs, when orderBy is ""): rows route in whatever order they come, and every request's last event waits for the execution's end.

PgBatchTurns

Turn-taking for a program with several connections that forms batches with one PgBatchClock: one free connection, the collector, gathers while the others execute, and a push wakes it only when its batch is due, not on every item. Sans-IO like the clock: a slot is the program's own number for a connection, 0 to size - 1, and the answer to each call is the slot to wake, or PG_TURNS_NONE.

The collector is the lowest-numbered free slot. push(now) records an item and answers the collector when this item makes the batch due; poll(now) answers it when the timer has made it due, at deadline(). Once a slot is named, no other is until it calls started(slot, size, now) with the batch it took, or release(slot) when it took none. finished(slot, now) frees a slot after its batch. Both started and finished answer the next slot to wake when a batch is already due, as under a backlog: nothing waits on the timer then. The in-flight count the idle bypass reads is the slots holding a batch.

class PgBatchTurns
Member
new PgBatchTurns(clock: PgBatchClock, size: i32) Turns over size slots (1 to 1024), all free; panics on a size out of range.
readonly clock: PgBatchClock The clock the turns read and record into.
collector(): i32 The slot that collects the next batch.
deadline(): i64 When the collector's timer fires, as PgBatchClock.deadline() gives it.
finished(slot: i32, nowUs: i64): i32 Records slot's batch done at nowUs, and answers the slot to wake. Panics on a slot out of range or holding no batch.
inFlight(): i32 How many slots hold a batch.
poll(nowUs: i64): i32 The slot to wake at nowUs, when a batch is due and no slot is named already.
push(nowUs: i64): i32 Records an item queued at nowUs and answers the slot to wake, or PG_TURNS_FULL when the clock is full.
release(slot: i32): void Gives back a wake that started nothing, so the next push or poll can wake a slot again. Panics on a slot out of range or holding a batch.
started(slot: i32, size: i32, nowUs: i64): i32 Records slot starting a batch of size items at nowUs, and answers the next slot to wake. Panics on a slot out of range or holding a batch already, or as PgBatchClock.started.

PgBatcher

Batches keyed reads of one statement shape, sans-IO like PgConnection: it reads no clock and makes no socket. Each request is a key and the caller's tag, queued by addInt or addText. When a connection is free, take(conn) binds up to maxRequests of them, and up to maxBytes of keys, as one execution of sql, each distinct key once (a key whose probe of the batcher's table passes 1024 slots, which takes keys chosen to collide, is bound again and answered the same), and answers the execution's run handle.

Each PG_ROW of that execution goes to row(run, conn), its PG_COMPLETE to end(run), and an error or a lost connection to fail(run); after each, next(run) answers events until PG_BATCH_NONE, tag naming the request each is about. Every row goes to every request for its key, and every request gets one last event: PG_BATCH_DONE, PG_BATCH_MISSING or PG_BATCH_FAILED.

Sorted (the default), rows come in key order and a key's last events come as soon as a later key's row does; with sorted false, rows come in any order, each answered at once, and every last event waits for end or fail, then comes in key order. A batch with binary set comes in binary format: its rows are read with the binary decoders, binaryInt for each ordinal, and the caller's binary.failed is left as it was.

Nothing outlives its execution: a run is free again once the events end or fail owe are answered, and its handle is then spent. What the server or the network can send after that — a second PG_COMPLETE, a row or an error after one, a lost connection — goes to a spent handle, and row, end and fail count it in stray and do nothing, even once take has given the run out again under a new handle. The ordinal each row carries comes from the server and is checked before it routes anything.

What panics is only the program's own misuse: a handle out of the range take can give (-1 or any negative, or runs * 2^20 or more), or row, end or fail before next(run) has answered PG_BATCH_NONE for the event before. A handle in that range that take never gave is spent like any other: counted in stray, not a panic.

class PgBatcher
Member
new PgBatcher(config: PgBatchConfig) A batcher for config; panics when a name or query is empty or holds a NUL, or a cap is out of range.
readonly name: string The prepared statement's name.
refused: i32 The number of runs failed by a bad ordinal (missing, NULL, not an integer, or naming no key still open; with sorted false, any key of the run is open), stopping at 2^31 - 1: each counts its first refused row, and the rows after it, dropped with the failed run, are not counted.
readonly sql: string The statement to prepare under name (PgPool.register or PgConnection.prepare, no parameter types); each row's last column is the ordinal it routes by.
stray: i32 The number of row, end and fail calls on a spent handle, each ignored, stopping at 2^31 - 1.
tag: i32 The request the last next(run) answered about; -1 for none.
addInt(key: i64, tag: i32): boolean Queues a request for the int8 key; false when queueSize are waiting. Panics on a text batcher.
addText(bytes: u8[], start: i32, length: i32, tag: i32): boolean Queues a request for the text key bytes[start, start + length), which is copied; false when the key is not UTF-8 or holds a NUL (the server would fail the whole execution over it), queueSize are waiting, the key would not fit in queueBytes beside those waiting, or it is too long for one execution's maxBytes. Panics on an int8 batcher, or when the window is not inside bytes.
end(r: i32): void Ends run r's execution, on its PG_COMPLETE: next(r) then closes every request left. Ignores a spent handle, and panics, as row does.
fail(r: i32): void Fails run r's execution, on its PG_ERROR or PG_LOST: next(r) then answers PG_BATCH_FAILED for every request left. Ignores a spent handle, and panics, as row does.
next(r: i32): i32 The next event row, end or fail owes on run r, with tag the request it is about; PG_BATCH_NONE, and tag -1, when there is none. Once end or fail has had all its events the run is over, free for take again, and its handle spent: PG_BATCH_NONE ever after. Panics on a handle take cannot give.
row(r: i32, conn: PgConnection): boolean Routes conn's current row, of run r's execution, by the ordinal in its last column: next(r) then answers PG_BATCH_ROW for each request of its key, after the last events of the keys before it (with sorted false, at once: no last event comes before end). False, and the row dropped, when the run has failed; and when the ordinal is NULL, not an integer, or names no key still open (one out of range, or, sorted, one before the key the last row was for): that counts in refused and fails the run; and on a spent handle, which counts in stray. Panics on a handle take cannot give, or when the run's events are not all answered.
take(conn: PgConnection): i32 Binds the oldest waiting requests on conn as one execution of sql, prepared there already, and answers its run's handle, which names this execution and no later one of the same run; the caller ends the group (sync(), or PgPool.send()). It takes up to maxRequests requests, oldest first, and stops at the first whose key would pass maxBytes or the connection's maxOutput; those not taken stay queued. -1, and nothing written, when none waits, every run is in flight, or conn refused the bind or the first key.
takeDue(conn: PgConnection, clock: PgBatchClock, nowUs: i64, inFlight: i32): i32 take(conn) when clock says a batch is due at nowUs, with inFlight of the program's executions or groups running (PgPool.inFlight()), and the batch taken recorded in clock; -1 when it is not due or take answers -1. The program calls clock.arrived(now) for each request it adds. Panics when the clock's waiting count is not this batcher's, or its maxCount is below maxRequests.
waiting(): i32 How many requests wait for take.

PgBinary

Decoders for PostgreSQL's binary format, in place, for the rows of a bind that bindStartBinary opened; a bad input sets failed, which stays set. A text or varchar column's bytes are the same in either format, so columnText, colStart and colLength read it as they read a text one.

class PgBinary
Member
new PgBinary()
failed: boolean Whether a decode since the last reset() was given something it could not read.
bool(b: u8[], start: i32, length: i32): boolean A bool column: one byte, 1 or 0.
float(b: u8[], start: i32, length: i32): f64 A float8 column: eight bytes, IEEE 754 big-endian. A float4 (four bytes) is refused.
int(b: u8[], start: i32, length: i32): i64 An int2, int4 or int8 column, told apart by its length (2, 4 or 8 bytes, big-endian two's complement); 0 and failed for any other length, NULL's -1 among them. A timestamptz or timestamp reads as an int8: microseconds since 2000-01-01 00:00:00 UTC, which iso writes out.
iso(micros: i64, out: u8[], at: i32): i32 micros, microseconds since 2000-01-01 00:00:00 UTC, written to out[at, at + 24) as 2024-01-02T03:04:05.123Z: the microseconds cut, not rounded, to milliseconds, as PgText.timestamp cuts the same time. Answers 24, or -1 and failed with out untouched for a year outside 0001–9999 (infinity and -infinity among them) or no room in out. Nothing is allocated.
reset(): void Clears failed.
timestamp(b: u8[], start: i32, length: i32, out: u8[], at: i32): i32 A timestamptz or timestamp column, written to out[at, at + 24) as iso writes it. Answers 24, or -1 and failed for a column that is not eight bytes or a time iso refuses.

PgBinaryArray

A walk over a one-dimensional int2[], int4[] or int8[] column in PostgreSQL's binary array layout, in place: begin the column, then next() until PG_ARRAY_END or PG_ARRAY_BAD, and int() decodes the current element through binary. The header is ndim, hasnull and the element OID, then for ndim 1 the dimension's length and lower bound (the bound is read and not used); each element is a length word and its bytes, and a NULL is a length of -1 with no bytes. ndim 0 is the empty array.

Every refusal sets binary.failed: an ndim above 1, another element type, an element whose length is not its type's size, a NULL when hasnull is 0, a column cut short, or bytes after the last element. The walk allocates nothing, and it reads nothing outside the column.

class PgBinaryArray
Member
new PgBinaryArray(binary: PgBinary) A walker with nothing begun; next() answers PG_ARRAY_BAD until begin.
count: i32 The number of elements the header gives: 0 for an empty array.
elementOid: i32 The element type's OID, 20, 21 or 23, once begin has read a header it accepts.
begin(b: u8[], start: i32, length: i32): void Starts a walk over b[start, start + length), reading its header; a header this walker does not read is refused, which sets binary.failed and makes next() answer PG_ARRAY_BAD. The walker keeps b and reads it until the next begin, so the window must stay valid that long: for a column, until the connection's next next().
int(): i64 The current element as an integer, through PgBinary.int; a NULL, or a walk that was refused, sets binary.failed.
next(): i32 Steps to the next element, which int() then reads.

PgConfig

The caps a connection enforces, and the startup parameters it sends.

class PgConfig
Member
new PgConfig()
applicationName: string application_name, shown in pg_stat_activity; empty sends none.
database: string The database; empty means the server's default, the role's name.
inputSize: i32 The input buffer's first size, in bytes; it grows to a message's length, up to maxMessage + 1.
maxColumns: i32 The widest row; past it, PG_ERR_TOO_BIG. PostgreSQL's own limit is 1664.
maxInFlight: i32 The most groups waiting for their answers at once.
maxIterations: i32 The most SCRAM iterations computed, so a server cannot make the client spin.
maxMessage: i32 The longest backend message, in bytes, its type byte aside; past it, PG_ERR_TOO_BIG.
maxOutput: i32 The most bytes the builder calls may queue unsent; a call that would pass it answers false and writes nothing, so a program that never drains its output cannot grow the buffer without bound.
minIterations: i32 The fewest SCRAM iterations accepted; 4096 is PostgreSQL's default and RFC 7677's floor.
options: string The startup options parameter (-c name=value ...); empty sends none.
pack: boolean Read by PgPool only: whether dispatch() packs requests onto the first ready connection with room, filling it to maxInFlight before the next, rather than spreading them over every connection, fewest in flight first. Fewer connections in use send fuller writes, fewer packets, which pays on a lossy link to the server; a connection is still wanted only once every ready one is full.
tls: i32 Read by the carrier only: PG_TLS_DISABLE (the default), PG_TLS_REQUIRE or PG_TLS_VERIFY_FULL. TLS needs a TCP target.
tlsRootsPath: string Read by the carrier only, under PG_TLS_VERIFY_FULL: a PEM file of the roots to trust; empty means the system's store.
tlsServerName: string Read by the carrier only: the name the server's certificate must carry, and the SNI sent; empty means the target's host.
user: string The role to connect as; required.

PgConnection

One connection to a PostgreSQL server, sans IO: the program moves bytes between the socket and the two buffers, and next() says what they meant.

class PgConnection
Member
new PgConnection(config: PgConfig, password: Secret<u8[]>, nonce: u8[]) A connection that has queued its startup message. password is copied, so the caller may wipe its own; nonce must be at least 18 bytes from a cryptographic random source (crypto.getRandomValues), and is fixed only in a test. Panics on a PgConfig that is a mistake (no user, a cap out of range, a NUL in a startup parameter), on one whose tls asks for TLS, which only PgCarrier speaks, so a connection driven by hand never runs in the clear when TLS was asked for, or on a nonce shorter than 18 bytes.
backendPid: i32 The server's process id, from BackendKeyData.
readonly binary: PgBinary The decoders binaryInt, binaryBool and binaryFloat use, for a bind bindStartBinary opened; binary.failed as text.failed.
columns: i32 The columns of the current row, or of the statement just described.
failure: i32 Why the connection failed, PG_ERR_NONE while it has not.
groupFailed: boolean Whether a statement in the group PG_GROUP_DONE just finished failed.
inFlight: i32 The number of groups sent and not yet answered.
lastError: PgError | null The last ErrorResponse, kept until the next.
lastNotice: PgError | null The last NoticeResponse, kept until the next.
notices: i32 The number of notices received, stopping at 2^31 - 1.
serverVersion: string The server's server_version parameter.
readonly text: PgText The decoders int, bool and isNull use; text.failed says whether one was given a column it could not read.
txStatus: i32 The transaction status the last PG_GROUP_DONE reported: I idle, T in a transaction, E in a failed one (as a byte).
arrayElement(bytes: u8[], start: i32, length: i32): boolean A text element from bytes[start, start + length), UTF-8, quoted with " and \ escaped; false, and nothing written, when there is no room. Panics when no text array is open or the window is not inside bytes.
arrayEnd(): void Ends the open array parameter, text or binary; never refused for room, which its elements kept. An array with no elements is sent as the empty array. Panics when no array is open.
arrayInt(value: i64): boolean An integer element of the open text array, in decimal. Panics when no text array is open.
arrayNull(): boolean A NULL element of the open text array. Panics when no text array is open.
arrayStart(): boolean Opens a text array parameter, {} so far, which arrayElement, arrayInt and arrayNull fill and arrayEnd() closes. Panics while an array is open.
binaryArrayInt(value: i64): boolean An integer element of the open binary array; false, and nothing written, when there is no room. Panics when no binary array is open, or when it is an int4[] and value is outside int4.
binaryArrayNull(): boolean A NULL element of the open binary array, length -1. Panics when no binary array is open.
binaryArrayStart(elementOid: i32): boolean Opens a binary array parameter of elementOid's elements, which binaryArrayInt and binaryArrayNull fill and arrayEnd() closes. Panics on another OID, or while an array is open.
binaryBool(c: i32): boolean Binary column c as a boolean; NULL or a bad value sets binary.failed.
binaryFloat(c: i32): f64 Binary column c, a float8; NULL or another length sets binary.failed.
binaryInt(c: i32): i64 Binary column c, an int2, int4, int8 or a time's microseconds since 2000, as an integer; NULL or another length sets binary.failed.
bindCancel(): boolean Drops the open bind, and the array open in it, unsent, so that a program whose parameter was refused for room can send the group without it; a group the bind opened is closed again. False when no bind is open.
bindEnd(): boolean Ends the Bind (every result column in text, or in binary after bindStartBinary) and queues its Execute, for every row. False, and nothing written, when no bind is open; never for room, which the calls before it kept. Panics while an array parameter is open. The Bind's bytes count toward outputEnd() from here on.
bindStart(name: string): boolean Starts a Bind of the prepared statement name; its parameters follow, in order, then bindEnd(). False, and nothing written, as prepare is. It opens a group when none is open. Until bindEnd() or bindCancel(), outputEnd() holds the Bind's bytes back.
bindStartBinary(name: string): boolean bindStart, asking for every result column of the execution in binary format rather than text: fixed-size integers, booleans, floats and times, read in place by binaryInt, binaryBool, binaryFloat and binary.timestamp. A text column's bytes are the same in either format, so columnText and the column windows read it as before. An int2[], int4[] or int8[] column comes in PostgreSQL's binary layout, which PgBinaryArray reads; a text[] or numeric column comes in that layout too, and no decoder here reads it. PgBatcher opens its batches with this when its binary is set, and reads their routing ordinals with binaryInt. Its bindEnd() writes two bytes more, kept free under maxOutput from here on. False as prepare is.
bool(c: i32): boolean Text column c as a boolean, through text.bool; NULL or a bad value sets text.failed.
canSend(): boolean Whether another group may start, or the open one take another message.
closed(): i32 Reports the end of the stream (a read of 0 bytes, or a socket error): unless it already has, the connection fails with PG_ERR_CLOSED, which wipes the password. Input already received and not yet read is dropped.
closeStatement(name: string): boolean Close: forgets the prepared statement name on the server. False, and nothing written, as prepare is. It opens a group when none is open.
colLength(c: i32): i32 Column c's length.
colStart(c: i32): i32 Column c's first byte in inputBuffer(), valid until the next next().
columnText(c: i32): string Column c as a string; the one result read that allocates, and the string outlives the row.
columnType(c: i32): i32 Column c of the statement just described, after PG_DESCRIBED.
dispose(): void Wipes the password if the connection still holds it. A program that drops a connection before it is ready calls this. It does not close anything or queue a Terminate: that is terminate(), and the socket is the program's.
inputBuffer(): u8[] The input buffer: read from the socket into it at inputEnd(). The connection owns it, and next() may replace it with a larger one, so fetch it again after every next().
inputEnd(): i32 Where the next byte read goes.
inputRoom(): i32 How many bytes may be read into the input buffer now.
int(c: i32): i64 Text column c as an integer, through text.int; NULL or a bad value sets text.failed.
isNull(c: i32): boolean Whether column c of the current row is NULL.
next(): i32 Reads input until it has an event to answer. Each call may move the unread input to the start of the buffer or replace the buffer, which ends the windows the last event gave (colStart, the tag) and calls for a fresh inputBuffer().
outputBuffer(): u8[] The output buffer: write [outputStart(), outputEnd()) to the socket. The connection owns it, and a builder call or sent may grow or compact it, so fetch it again after each.
outputEnd(): i32 One past the last byte that may be sent: a Bind still open is held back until bindEnd() has written its lengths.
outputStart(): i32 The first byte not yet sent.
paramBytes(bytes: u8[], start: i32, length: i32): boolean A text parameter from bytes[start, start + length), UTF-8, copied into the Bind so the caller may reuse bytes at once. Panics while an array parameter is open.
paramInt(value: i64): boolean An integer parameter, in decimal text, which the server reads as the statement's type (int2, int4, int8, numeric, ...). Panics while an array parameter is open.
paramInt4Array(values: i64[], start: i32, count: i32): boolean An int4[] parameter in binary from values[start, start + count); false as the param... calls are. Panics, writing nothing, when the window is not inside values or an element is outside int4, and while an array parameter is open.
paramInt8Array(values: i64[], start: i32, count: i32): boolean An int8[] parameter in binary from values[start, start + count); false as the param... calls are. Panics when the window is not inside values, and while an array parameter is open.
paramIntArray(values: i64[], start: i32, count: i32): boolean An int8[] parameter from values[start, start + count), in decimal text ({1,2,3}, or {} for none); panics when the range is not inside values, or while an array parameter is open.
paramNull(): boolean A NULL parameter, of whatever type the statement gives it. Panics while an array parameter is open.
paramText(value: string): boolean A text parameter: the string's bytes as they are. Panics while an array parameter is open.
paramTextArray(items: string[]): boolean A text[] parameter: every element quoted, with each double quote and backslash escaped by a backslash, so no element reads as NULL (build one with arrayNull for that). Panics while an array parameter is open.
passwordWiped(): boolean Whether every byte of the connection's copy of the password is zero: true once the proof is computed, the connection has failed or dispose() has run (and for an empty password). It reads the copy itself, so a test can see the wipe happen; a program has no use for it.
prepare(name: string, sql: string, paramTypes: i32[]): boolean Parse and Describe: prepares sql as the statement name ("" is the unnamed one), its parameters' types given by paramTypes (OIDs, 0 to let the server infer one, and parameters past the array are inferred too). The server answers PG_DESCRIBED. False, and nothing written, when canSend() is false, a bind is open, name or sql holds a NUL, more than 65535 types are given, or the message would pass maxOutput. It opens a group when none is open; sync() ends it.
receive(src: u8[], start: i32, length: i32): i32 Copies what fits of src[start, start + length) into the input buffer at inputEnd(), for a program whose bytes arrive in a buffer of its own. Panics on a window outside src.
received(n: i32): void Records that n bytes were read into the input buffer at inputEnd(). Panics on a negative n or one past inputRoom().
sent(n: i32): void Records that n bytes from outputStart() were written to the socket. Panics on a negative n or one past outputEnd() - outputStart().
sync(): boolean Sync: ends the open group, which the server answers with PG_GROUP_DONE; the group stays in inFlight until then.
tagIs(word: string): boolean Whether the tag of the execution just completed starts with the word word, read after PG_COMPLETE and before the next next().
tagRows(): i64 The row count the tag of the execution just completed ends with, read after PG_COMPLETE and before the next next(); text.failed is left as it was.
terminate(): void Terminate: tells the server the connection is ending; close the socket once it is sent. A bind still open is dropped unsent. It is queued in any state, and is never refused for room.
tlsFailed(): i32 Reports that TLS under the connection failed, or the server refused it: unless it already has, the connection fails with PG_ERR_TLS, which wipes the password.

PgError

A server's ErrorResponse or NoticeResponse: the fields a program acts on.

class PgError
Member
new PgError(severity: string, code: string, message: string, detail: string, hint: string, constraint: string, position: string) Builds the record from the fields of one ErrorResponse or NoticeResponse; a program reads it from lastError or lastNotice rather than building one.
readonly code: string The SQLSTATE, five characters: 23505 is a unique violation.
readonly constraint: string The constraint that was violated, or "".
readonly detail: string The detail, or "".
readonly hint: string The hint, or "".
readonly message: string The primary message.
readonly position: string The 1-based character position in the statement's text, or "".
readonly severity: string ERROR, FATAL or PANIC; WARNING, NOTICE, DEBUG, INFO or LOG for a notice. Never localised, unless the server sent no V field (before 9.6) and the localised S field stands in for it.

PgPool

A pool of connections to one server, sans-IO like PgConnection: it makes no socket and reads no clock, and says which slot needs a socket and when. Its size is a cap, and no connection is made until a request needs one and no ready connection has room.

A request is a ticket from request(), queued in FIFO order. dispatch() hands the queue's head to the ready connection with the fewest groups in flight, or under PgConfig.pack the lowest-numbered ready one with room, never past maxInFlight on one; the program builds the request's group on connection(slot) and ends it with send(), not sync(). next(slot) then reads that connection's events, ticket naming the request each is about. A connection that fails reports PG_LOST for each request it took with it, then PG_FAILED, and is built again on its next use. Statements given to register are prepared on each connection in the same group as its first request, so a request may bind them at once.

class PgPool
Member
new PgPool(config: PgConfig, password: Secret<u8[]>, size: i32, queueSize: i32) A pool of up to size connections (1 to 1024) and up to queueSize waiting requests (1 to 2^20). password is copied and kept until dispose(), since a connection is made again after a failure. Panics as PgConnection does on config, and on a maxInFlight over 1024.
readonly size: i32 The number of slots, the most connections the pool makes.
ticket: i32 The request the last dispatch(), or event from next(slot), is about; -1 for none.
connect(slot: i32, nonce: u8[]): void Makes the wanted slot's connection, nonce as PgConnection takes it: send its output once the socket is connected, and if the socket fails, call connection(slot).closed(). Panics when slot is not wanted, the pool is disposed, or its PgConfig.tls asks for TLS and no PgCarrier drives the pool: only the carrier speaks TLS.
connection(slot: i32): PgConnection The connection in slot, its buffers the carrier's to fill and drain; the last one made after it fails. Panics when none was made.
dispatch(): i32 Hands the oldest waiting request to a ready connection with room (the one with the fewest in flight, or under PgConfig.pack the first), and answers its slot, ticket set to the request: build its group on connection(slot), then send(). PG_POOL_NONE when nothing waits, a request is still being built, or no ready connection has room; then a connection may be wanted (wanted()): one more for every maxInFlight waiting requests that the connections already starting cannot take. A request handed out is the program's to end with send(): until then no other is handed out.
dispose(): void Wipes the pool's password and every connection's; connect panics after it.
inFlight(): i32 How many groups are in flight across every connection: the inFlight a PgBatchClock reads.
next(slot: i32): i32 The next event from slot's input, as PgConnection.next() answers it, ticket naming the request it is about (-1 for PG_READY, PG_FAILED, and a notice while no request is in flight). The PG_DESCRIBED of a registered statement is the pool's and is not answered. When the connection fails, PG_LOST comes for each request in flight on it, oldest first, then PG_FAILED: close its socket. A connection that fails before it is ready, while no other is, takes the oldest waiting request with it, so that a server that cannot be reached empties the queue rather than holds it. PG_NEED_MORE once PG_FAILED was answered, until connect builds the slot again. Panics as connection(slot) does.
passwordWiped(): boolean Whether every byte of the pool's copy of the password is zero, as PgConnection.passwordWiped() reads its own: true once it is wiped, and for an empty password before any wipe.
register(name: string, sql: string, paramTypes: i32[]): boolean Registers a statement for every connection to prepare before its first request. False when a connection has been made already, name or sql holds a NUL, or 256 are registered.
request(): i32 Queues a request and answers its ticket, or PG_POOL_FULL when queueSize are waiting.
send(): boolean Ends the group of the request dispatch() handed out. False when there is none; when a bind is still open, so finish it and call again; and when no message of the group was written, so the request is dropped and gets no events (PG_LOST if its connection has failed).
settings(): PgConfig The settings the pool's connections are made with, as given to the constructor.
waiting(): i32 How many requests wait for a connection.
wanted(): i32 A slot that needs a socket, or PG_POOL_NONE: connect it, then call connect(slot, nonce).

PgTarget

Where a connection goes, from libpq's host and port or a postgres:// URL: pgTarget and pgTargetUrl make one, reading no socket and no file. When failure is PG_TARGET_OK, a unix target is unixConnect(path), and any other is host and port, for netAddress and tcpConnect.

A host starting with / is a socket directory, and one starting with @ a Linux abstract name, as in libpq: the socket is <host>/.s.PGSQL.<port>. The host is always the directory, never the socket file itself. Any other host is TCP.

class PgTarget
Member
new PgTarget()
failure: i32 PG_TARGET_OK, or the PG_TARGET_* reason the input was refused.
host: string The host as given (a URL's decoded, without an IPv6 address's brackets); for a socket, its directory or @ name.
path: string The socket's path, <host>/.s.PGSQL.<port>, when unix; otherwise "".
port: i32 The port: the TCP port, or the number in the socket's name.
unix: boolean Whether the target is a Unix socket, at path.

PgText

Decoders for PostgreSQL's text format, in place; a bad input sets failed, which stays set.

class PgText
Member
new PgText()
failed: boolean Whether a decode since the last reset() was given something it could not read.
bool(b: u8[], start: i32, length: i32): boolean A bool column: t or f, in place.
int(b: u8[], start: i32, length: i32): i64 An int2, int4 or int8 column: an optional - and its digits, in place. Leading zeros are allowed; a value outside i64 is an overflow.
reset(): void Clears failed.
timestamp(b: u8[], start: i32, length: i32, out: u8[], at: i32): i32 A timestamptz column, as the connection's DateStyle=ISO and TimeZone=UTC spell it (2024-01-02 03:04:05.123456+00), or a timestamp column (the same without +00), written to out[at, at + 24) as 2024-01-02T03:04:05.123Z, the fraction cut to milliseconds. Answers 24, or -1 and failed for anything else: a year outside 0001–9999, BC, infinity, an offset other than +00. Nothing is allocated.

Constants

-3

PG_ARRAY_BAD: i32

PgArrayWalker.next(): the text is not a one-dimensional array literal.

0

PG_ARRAY_ELEMENT: i32

PgArrayWalker.next(): an element, at start for length bytes.

-2

PG_ARRAY_END: i32

PgArrayWalker.next(): no more elements.

-1

PG_ARRAY_NULL: i32

PgArrayWalker.next(): a NULL element.

2

PG_BATCH_DONE: i32

PgBatcher.next(run): the request tag has had all its rows, at least one.

4

PG_BATCH_FAILED: i32

PgBatcher.next(run): the request tag's execution failed, and its rows so far may be incomplete.

0

PG_BATCH_INT: i32

PgBatchConfig.keyType: the keys are int8, given to PgBatcher.addInt.

3

PG_BATCH_MISSING: i32

PgBatcher.next(run): no row answered the request tag's key.

0

PG_BATCH_NONE: i32

PgBatcher.next(run): no event until the next row, end or fail.

1

PG_BATCH_ROW: i32

PgBatcher.next(run): the connection's current row answers the request tag.

1

PG_BATCH_TEXT: i32

PgBatchConfig.keyType: the keys are text, given to PgBatcher.addText.

2

PG_CLOCK_AVERAGE: i32

PgBatchClock.check: the moving average of recent batches, times factor, is waiting.

1

PG_CLOCK_COUNT: i32

PgBatchClock.check: minCount items are waiting, and the average asks no more.

4

PG_CLOCK_IDLE: i32

PgBatchClock.check: nothing is in flight and little has arrived lately, so the item goes at once.

3

PG_CLOCK_TIMER: i32

PgBatchClock.check: the oldest item has waited maxWaitUs.

0

PG_CLOCK_WAIT: i32

PgBatchClock.check: not yet; wait for an item or for deadline().

3

PG_COMPLETE: i32

An execution has finished: tagIs, tagRows.

7

PG_DESCRIBED: i32

A prepared statement has been described: columns, columnType(c).

4

PG_ERROR: i32

A statement in the current group failed: lastError.

4

PG_ERR_AUTH_UNSUPPORTED: i32

An authentication method this client refuses (cleartext, MD5, GSS, SSPI, a SASL mechanism other than SCRAM-SHA-256).

9

PG_ERR_CLOSED: i32

The program reported the end of the stream (closed()).

8

PG_ERR_ENCODING: i32

The server's client_encoding is not UTF8.

1

PG_ERR_FRAME: i32

A message length below 4, or a message whose layout does not add up.

0

PG_ERR_NONE: i32

failure while the connection is alive.

5

PG_ERR_SCRAM: i32

A SCRAM exchange the server got wrong: a malformed message, a nonce that does not extend ours, an iteration count out of bounds.

7

PG_ERR_SERVER: i32

The server sent a FATAL or PANIC error, or any error before the connection was ready: lastError.

6

PG_ERR_SERVER_SIGNATURE: i32

The server's SCRAM signature is not the one the password gives: it does not know the password.

10

PG_ERR_SETTING: i32

The server's DateStyle is not ISO or its TimeZone is not UTC, the two the decoders read: at startup, or after a SET.

11

PG_ERR_TLS: i32

TLS to the server failed, reported by the carrier (tlsFailed()): the server answered N to the SSLRequest while PgConfig.tls asks for TLS, its certificate was refused, or the handshake failed.

2

PG_ERR_TOO_BIG: i32

A message longer than maxMessage, or a row wider than maxColumns.

3

PG_ERR_UNEXPECTED: i32

A message the protocol does not allow at this point.

8

PG_FAILED: i32

Final: the connection is over, and failure says why.

5

PG_GROUP_DONE: i32

A group has been answered: groupFailed, txStatus.

9

PG_LOST: i32

PgPool.next(slot): the request ticket names will get no answer, because its connection failed first.

0

PG_NEED_MORE: i32

next() needs more input before it can say anything.

6

PG_NOTICE: i32

A notice: lastNotice.

-2

PG_POOL_FULL: i32

PgPool.request(): the queue is full, and the request was not taken.

-1

PG_POOL_NONE: i32

PgPool.dispatch() and PgPool.wanted(): no slot.

1

PG_READY: i32

The connection is authenticated and ready for queries; answered once.

2

PG_ROW: i32

A row: columns columns, each at colStart(c) for colLength(c) bytes.

80,877,103

PG_SSL_REQUEST_CODE: i32

The SSLRequest's code, in place of a protocol version: 1234 in the high 16 bits, 5679 in the low.

2

PG_TARGET_BAD_ESCAPE: i32

PgTarget.failure: a % not followed by two hex digits, %00, or escapes that decode to bytes that are not UTF-8.

3

PG_TARGET_BAD_HOST: i32

PgTarget.failure: no host, more than one (a ,), an unclosed [ or text after its ], a raw @ past the user information, or a NUL byte.

4

PG_TARGET_BAD_PORT: i32

PgTarget.failure: a port that is not 1 to 65535 in decimal digits.

1

PG_TARGET_BAD_URL: i32

PgTarget.failure: not a postgres:// or postgresql:// URL, or a query parameter with no =.

0

PG_TARGET_OK: i32

PgTarget.failure: none; connect as unix says.

5

PG_TARGET_TOO_LONG: i32

PgTarget.failure: a socket path longer than Linux's sun_path holds.

0

PG_TLS_DISABLE: i32

PgConfig.tls: no SSLRequest; the connection is cleartext. The default.

1

PG_TLS_REQUIRE: i32

PgConfig.tls: an SSLRequest first, and TLS 1.3 or nothing, the server's certificate not checked. Keeps a passive eavesdropper out; an active one who answers in the server's place is not.

2

PG_TLS_VERIFY_FULL: i32

PgConfig.tls: an SSLRequest first, and TLS 1.3 or nothing, the server's chain checked against the trusted roots and its name against the host (libpq's sslmode=verify-full).

-2

PG_TURNS_FULL: i32

PgBatchTurns.push: the item was not recorded, queueSize are waiting.

-1

PG_TURNS_NONE: i32

PgBatchTurns: no slot to wake.