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();
}
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.
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.
pgTargetUrl
The target a postgres:// or postgresql:// URL names, as libpq reads one: postgres://[user[:password]@][host][:port][/dbname][?key=value&...].
PgArrayWalker
A walk over a one-dimensional text[] column in place: begin the column, then next() until PG_ARRAY_END or PG_ARRAY_BAD.
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.
PgBatchClockConfig
When a PgBatchClock starts a batch.
PgBatchConfig
What a PgBatcher sends: one statement shape, its key, and its caps.
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.
PgBatcher
Batches keyed reads of one statement shape, sans-IO like PgConnection: it reads no clock and makes no socket.
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.
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.
PgConfig
The caps a connection enforces, and the startup parameters it sends.
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.
PgError
A server's ErrorResponse or NoticeResponse: the fields a program acts on.
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.
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.
PgText
Decoders for PostgreSQL's text format, in place; a bad input sets failed, which stays set.
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.
porti32requiredThe TCP port, or the number in the socket's name, from 1 to 65535.
returnsPgTargetThe 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
urlstringrequiredThe URL; any user or password it holds is not kept in the target.
returnsPgTargetThe 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.

