Garry's Opinionated OpenClaw/Hermes Agent Brain
GBrain's Postgres driver
postgres/ is the exact published [email protected] package from
https://github.com/porsager/postgres, with GBrain's checked-in
patches/[email protected] applied. The package is Unlicense, not MIT;
the original upstream license is preserved in postgres/UNLICENSE (the npm
tarball omits this file, so the updater retrieves and verifies it separately).
Original package metadata and attribution are retained.
The registry's latest supported release was inspected on 2026-09-27 and was
still 3.4.9. Its stock reserved and transaction owners do not implement the
discard() capability needed by GBrain's cancellation fence. No version
upgrade or opaque third-party fork is being substituted for that capability.
Why source is shipped
The root package-private #postgres import maps directly into this directory.
Every driver import resolves through this one package import. Bun and
Node ESM use src/; CommonJS uses cjs/src/; compiled Bun artifacts embed
those same resolved source bytes. The workerd export receives the identical
ESM patch, preserving its upstream polyfill imports. GBrain itself does not
support a workerd runtime.
This deliberately avoids Bun's transitive file: dependency resolution, which
can report a successful packed installation while leaving the driver absent.
The patched bytes are part of GBrain's checkout and package, not a
patchedDependencies instruction that a global install may ignore. No
postinstall mutation of another package's node_modules is needed. The patch
file remains the auditable source of the delta, not an installation hook.
The patch adds abort-aware reservation, reserved/transaction-owner discard,
CancelRequest settlement tracking and ownership/pipeline fences. It also
terminates, instead of reusing, a pooled connection or released reservation
whose last ReadyForQuery status is not idle, and reports each discard through
the onpoisoned(status) option (#5730). Cancellation
must settle or retire the connection before another query can own it. This
is necessary for worker admission, query timeout and lease-release safety.
See issues #5466 and #5560 and test/e2e/persistence-chaos.test.ts.
Reserved and transaction owners also expose cancelAndDiscard({ timeout })
(#6598): a Terminate cannot interrupt the statement already running on a busy
socket, so it sends the fenced statement's CancelRequest first, refuses new and
queued statements while it waits for that statement to settle, then discards.
It rejects CANCEL_UNCONFIRMED when the statement does not settle within
timeout (default 2000 ms) or was not fenced, so a socket close is never
reported as a confirmed server stop
(test/postgres-transaction-cancel-order.test.ts,
test/e2e/transaction-cancel-held-lock.test.ts).
A statement that fails to build is answered in its place in the pipeline
(#6383; the approach of upstream PR porsager/postgres#1236, which fixes
porsager/postgres#1082, so this hunk drops when that merges). A statement joins
a connection's queue before it is built, so when build throws
(UNDEFINED_VALUE, MAX_PARAMETERS_EXCEEDED) behind an in-flight statement,
stock postgres.js rejects that head statement with its error, leaves the
culprit queued with nothing on the wire, and delivers every later reply on the
socket one statement late until the process restarts. With the patch a query
the server is certain to refuse goes out in the culprit's place: only the
culprit rejects, with its own error, a transaction it was part of is aborted
rather than committed without it, and the pool reports the failure through
onbuilderror(code, statement) (template text with $n placeholders, no
values). The same patch adds the in-flight watchdog: inflight_timeout
(seconds) bounds how long a head statement may wait with nothing coming back;
past it the statement and its queued followers reject with CONNECTION_STUCK,
the pool parks the connection out of rotation, reports onstuck({ age_ms, queued, statement }) and reconnects. sql.pool is a live property getter
(stock Object.assign froze the #6317 numbers at construction) and carries
inflight_oldest_ms and completed. Tests:
test/e2e/postgres-pipelined-build-failure-postgres.test.ts,
test/e2e/postgres-stuck-connection-postgres.test.ts.
The patch also lets a pool share the parameter types of a described statement
across its connections (shared_types, on by default; GBrain turns it off with
GBRAIN_PG_TYPE_CACHE=0). Stock postgres.js describes every parameterized
statement once per connection, and with prepare: false (transaction-mode
poolers) on every run, before it can execute it; that describe costs a round
trip and stops pipelining behind it. With the types known, the statement is
parsed, described and executed in one message group. Only built-in types (oid
below 16384) are shared, since a database's own types (pgvector) can be
recreated under a new oid; a statement that fails forgets its shared types, and
PostgresEngine.initSchema clears them after applying migrations (#5984,
test/e2e/postgres-shared-types.test.ts). shared_types also accepts the Map
to share types in: GBrain passes one per database target, so every pool in a
process that reaches one database shares it, and src/core/pg-type-cache.ts
saves it for the next process.
Stock postgres.js runs a pg_type query on every new connection before its
first statement. The patch's array_types option takes a { rows } object:
the first connection that fetches the array types stores them there, and every
later connection of any pool given the same object applies them without the
round trip. GBrain passes one per database target, in-process only, since
extension type OIDs belong to one database's catalog (#6930,
test/pathological/pg-round-trips-6930.test.ts).
A pool built not to pipeline (max_pipeline: 0, a transaction-mode pooler,
#6543) still pipelines up to transaction_pipeline statements on a
connection its owner holds (sql.begin, sql.reserve) while every statement
in flight leaves the connection inside a transaction: the last ReadyForQuery
said T or E, or an in-flight statement began one, and none since may end
it (COMMIT, ROLLBACK other than ROLLBACK TO, END, ABORT, PREPARE TRANSACTION).
The pooler pins one server connection from BEGIN until the transaction ends,
and nothing is sent behind a statement that may end it, so another owner's
statements never reach that server connection. Default 0 (stock behaviour);
GBrain sets 100 on transaction-mode URLs (#6930,
test/e2e/pgbouncer-transaction-pipeline-6930.test.ts).
With transaction_pipeline in force, sql.begin({ first }, fn) sends the
transaction's first statement behind BEGIN before BEGIN's answer when
first(text) accepts its text; every later statement, and a first one the
test refuses, waits for that answer as stock begin does. If BEGIN fails,
the early statement has run in autocommit and the rest are rejected unsent,
so the test must accept only a read or a transaction-local set_config.
GBrain passes isPersistenceDeclaration (src/core/persistence/protocol.ts)
from the persistence transactions that open with the protocol declaration
(GBRA-156, same test file).
sql.begin({ early }, fn) sends every statement early(text) accepts, in
order, behind BEGIN before BEGIN's answer, on any pool that pipelines inside
a transaction (a pipelining pool, or transaction_pipeline in force); the
first statement it refuses, and every later one, waits for the answer. The
same rule applies: if BEGIN fails the accepted statements have run in
autocommit, so the test must accept only reads and transaction-local
set_config. GBrain passes isPipelinableSearchRead
(src/core/postgres-engine/search-settings.ts) from its search read
transactions, so a scoped search read costs one round trip instead of two
(GBRA-156, test/e2e/pgbouncer-transaction-pipeline-6930.test.ts and
test/e2e/search-read-pipeline-postgres.test.ts).
On a reserved connection (sql.reserve), where the pool does not pipeline,
reservedTransactions().begin({ first }, fn)
(src/core/postgres-engine/reserved-transactions.ts) makes the same
exception outside the driver. It replaces each query's handler property,
the function postgres.js calls when it executes a query, with one that waits
for BEGIN's answer. That code lives in src, not in this patch set, so
update-postgres.sh --check does not cover it: after a driver upgrade,
check that Query.handler is still called on execute, and run
test/persistence-pipeline-first.test.ts.
Each statement's row count resets at its ReadyForQuery. Stock postgres.js
resets it only at CommandComplete. A statement that streams rows and then fails
never gets there: a runtime error after its first rows, or a cancel or timeout
while it is still producing them. The next statement on that connection then
stored its rows after that many empty slots, so a one-row read came back as
[empty, row] (test/e2e/postgres-driver-row-count-postgres.test.ts).
A statement whose result type changed heals every connection in the process,
not only the one that failed. When another session adds, renames or drops a
column of a table that a prepared SELECT * or RETURNING * reads, Postgres
answers that statement's next run with SQLSTATE 0A000 "cached plan must not
change result type" (routine RevalidateCachedQuery) on every connection
that prepared it. Stock postgres.js forgets the statement only on the failing
connection and runs it again, which cannot work inside a transaction the error
already aborted, so each pooled connection failed once. With the patch the
first such error starts a new process-wide plan generation, and each
connection drops its prepared statements before it builds its next query (the
server-side statements stay until the connection closes; new ones take new
names). Only a statement the connection had cached starts a generation: a
fresh statement that fails this way means a pooler (PgBouncer with
max_prepared_statements) mapped it onto an older server-side statement,
which preparing again cannot heal. A prepare: false pool keeps no prepared
statements, so nothing changes there. GBrain's write retry loops treat the aborted transaction as
transient (isStalePlanError in src/core/retry-matcher.ts;
test/stale-plan-heal.test.ts).
An idle connection keeps nothing from its last statement. Stock postgres.js
left its receive buffer as an empty view over the last message it joined from
several socket reads, so the buffer stayed allocated until the connection's
next read. For a 1 MiB bytea row, that buffer is the 2 MiB hex DataRow. The
desync tripwire keeps only the last statement's text, not the query, whose
promise holds its rows, and a connection that closes forgets the last
statement it wrote, with its parameters. Pools hand statements out in turn, so
before this fix each pooled connection held one segment read
(test/e2e/postgres-driver-idle-retention-postgres.test.ts,
test/large-pages/segmented-prior-view.test.ts).
Reproduce and update
Run bash vendor/update-postgres.sh --check to download the pinned upstream
tarball, verify SHA-512, apply the checked-in patch to every published runtime
export, verify the upstream license and compare every byte. Run without
--check to regenerate postgres/. This does not read a brain or alter any
installed service. No driver dependency installation is required after regeneration.
bun run verify runs the check as check:vendor-postgres
(scripts/check-vendor-postgres.sh), so a fix in one copy that is missing from
the patch or the other copies fails CI. The two pinned downloads are retried
(bounded, with backoff) and kept by content hash in ~/.cache/gbrain-vendor
(GBRAIN_VENDOR_CACHE; test.yml caches it), and each is hash-checked on use.
Without network and cache it is a recorded skip locally and a failure under CI.
For security updates, the GBrain release maintainer owns this dependency: review upstream security advisories and supported releases, update the exact version/URLs/hashes here and in the updater, rebase the patch against pristine upstream source, regenerate, then review the entire diff. Never edit only an installed node_modules copy. Do not suppress the runtime capability guard.
Before retiring this vendor, prove the candidate upstream release passes the same runtime reserved-owner check, interrupted reservation and in-query cancellation tests, successor-query fence tests, real Postgres and transaction-mode PgBouncer tests, and fresh/upgrade/packed/GitHub-global and compiled distribution smokes. An ordinary unsignalled SELECT or matching version is not evidence of safe cancellation. Publish the distribution and platform results, including any unavailable target, before changing the dependency back to the registry.
Isolated install smoke
With a disposable test-shaped database, run:
GBRAIN_TEST_ALLOW_DATABASE_URL=1 GBRAIN_TEST_PACKAGE_SMOKE=1 \
DATABASE_URL="$DISPOSABLE_TEST_DATABASE_URL" \
bun test test/e2e/postgres-driver-install.test.ts
This uses isolated HOME/cache/install directories, no paid providers, and
tests a checkout, actual packed installation, global tarball installation,
an independently installed stock-driver negative fixture, a stale stock
module alongside the new installation, and a Linux compiled job fixture.
Each positive runtime validates readiness and cancellation, then completes a
harmless minion job. The macOS ARM64 fixture is cross-compiled, not run; native
macOS execution is a separate platform acceptance gate. To test a published
GitHub revision's global installation instead of the local global tarball,
also set GBRAIN_TEST_GITHUB_PACKAGE=github:garrytan/gbrain#<published-sha>.
Do not claim GitHub transport validation before that revision is available.