Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import postgres from '#postgres'
import { claimOwner, isOneShotCommand } from './persistence/claim-phase.ts';
import { traceSqlOptions } from './sql-trace.ts';
import { tlsRequiredDefaultError, withPgTls } from './pg-tls.ts';
import { beginReadWrite } from './postgres-engine/read-write-transactions.ts';
import { warnPoolerPrepareOffOnce } from './pooler-notice.ts';
import { GBrainError, type EngineConfig } from './types.ts';
import { SCHEMA_SQL } from './schema-embedded.generated.ts';
import { applyPostgresForwardReferenceBootstrap } from './engine-sql/bootstrap.ts';
import type { BrainEngine } from './engine.ts';
import { verifySchema } from './schema-verify.ts';
import { POOL_END_TIMEOUT_SECONDS } from './pool-end-timeout.ts';
import { isConnectTimeoutError, isRetryableConnError } from './retry-matcher.ts';
import { loadSharedParameterTypes, sharedArrayTypes, sharedParameterTypes, type SharedArrayTypes, type SharedParameterTypes } from './pg-type-cache.ts';
let sql: ReturnType<typeof postgres> | null = null;
let connectedUrl: string | null = null;
export { POOL_END_TIMEOUT_SECONDS };
/**
* #1972: end a postgres.js pool with a gbrain-owned hard bound. Resolves as soon
* as `.end()` settles OR after POOL_END_TIMEOUT_SECONDS + a small slack — so
* teardown never hangs (the prior bare `.end()` blocked until the CLI's 10s
* force-exit fired, which `process.exit()`s and truncated pending stdout, e.g.
* #1959's relational query came back empty). Never throws: a teardown that
* rejects is worse than one that races past a stuck socket. The race timer is
* the real guarantee; `{ timeout }` just lets a healthy drain return in ms.
*
* Note callers that close MULTIPLE pools should `Promise.all` them rather than
* awaiting sequentially, so the per-pool bounds run concurrently instead of
* stacking.
*/
export async function endPoolBounded(
pool: { end: (opts?: { timeout?: number }) => Promise<void> },
): Promise<void> {
let timer: ReturnType<typeof setTimeout> | undefined;
// The guard timer stays ref'd while the race is pending (#5332): an unref'd
// timer is dropped by a runtime with nothing else to wait on (and parked
// under `bun test` on Windows), so the never-settling .end() it exists for
// was the one case it did not bound. The finally clears it, so a healthy
// drain never holds the process open past the race.
const guard = new Promise<void>((resolve) => {
timer = setTimeout(resolve, POOL_END_TIMEOUT_SECONDS * 1000 + 500);
});
try {
await Promise.race([
pool.end({ timeout: POOL_END_TIMEOUT_SECONDS }).catch(() => { /* idempotent / already-closed */ }),
guard,
]);
} finally {
if (timer) clearTimeout(timer);
}
}
/**
* Default pool size for Postgres connections. Users on the Supabase transaction
* pooler (port 6543) or any multi-tenant pooler can lower this to avoid
* MaxClients errors when `gbrain upgrade` spawns subprocesses that each open
* their own pool. Set `GBRAIN_POOL_SIZE=2` (or similar) before the command.
*/
const DEFAULT_POOL_SIZE_FALLBACK = 10;
/**
* Supabase PgBouncer transaction-mode convention: port 6543 routes through
* PgBouncer, which recycles the backend connection between queries and
* invalidates per-client prepared-statement caches. On that port postgres.js
* defaults (prepare=true) surface as `prepared statement "..." does not exist`
* under sustained load and silently drop rows during sync.
*
* This is a heuristic, not a protocol guarantee. A direct-Postgres server
* deliberately bound to 6543 will also get `prepare: false`; the
* `GBRAIN_PREPARE=true` env var (or `?prepare=true` on the URL) is the
* documented escape hatch.
*/
const AUTO_DETECT_PORTS = new Set(['6543']);
/**
* Decide whether to force `prepare: true`/`false` on the postgres.js client.
*
* Precedence:
* 1. `GBRAIN_PREPARE` env var (`true`/`1` or `false`/`0`)
* 2. `?prepare=true|false` query param on the URL
* 3. Auto-detect: port 6543 → `false`
* 4. Default: `undefined` (caller omits the option; postgres.js default stands)
*
* Returns `boolean | undefined`. `undefined` is meaningful — callers MUST
* omit the `prepare` key entirely in that case rather than passing
* `undefined` through to `postgres(url, {prepare: undefined})`.
*/
export function resolvePrepare(url: string): boolean | undefined {
const envPrepare = process.env.GBRAIN_PREPARE;
if (envPrepare === 'false' || envPrepare === '0') return false;
if (envPrepare === 'true' || envPrepare === '1') return true;
try {
const parsed = new URL(url.replace(/^postgres(ql)?:\/\//, 'http://'));
const urlPrepare = parsed.searchParams.get('prepare');
if (urlPrepare === 'false') return false;
if (urlPrepare === 'true') return true;
if (AUTO_DETECT_PORTS.has(parsed.port)) {
return false;
}
} catch {
// URL parse failure — fall through to default
}
return undefined;
}
/** Why a read-side pool got its `max_pipeline` (#6543); `/health?deep=1` reports it beside the live value. */
export type ReadPoolPipelineReason = 'url_max_pipeline' | 'env_pgmax_pipeline' | 'transaction_pooler_port' | 'url_prepare_false' | 'gbrain_prepare_off' | 'default';
/**
* #6543: the `max_pipeline` a read-side pool (the module singleton, an engine's
* instance pool, the connection manager's read pool) is built with. A
* transaction-mode pooler cannot carry statements pipelined on one client
* connection across transaction boundaries: through Supavisor they hung or came
* back with another statement's rows. So a transaction-mode URL (port 6543 or
* `?prepare=false`, read from the URL itself because `GBRAIN_PREPARE` wins
* inside `resolvePrepare`) or `GBRAIN_PREPARE=0` gets `0`. A session-mode
* pooler (Supabase's :5432) keeps pipelining. The driver lets the options
* object outrank the URL and `PGMAX_PIPELINE`, so `value` is null (the option
* stays unset and the driver reads them, default 100) whenever the URL names
* `max_pipeline` or `PGMAX_PIPELINE` is set and non-empty. The direct pool
* never calls this.
*/
export function resolveReadPoolPipeline(url: string): { value: number | null; reason: ReadPoolPipelineReason } {
const [beforeFragment = ''] = url.split('#', 1);
const queryAt = beforeFragment.indexOf('?');
const params = new URLSearchParams(queryAt >= 0 ? beforeFragment.slice(queryAt + 1) : '');
if (params.has('max_pipeline')) return { value: null, reason: 'url_max_pipeline' };
if ((process.env.PGMAX_PIPELINE ?? '').trim() !== '') return { value: null, reason: 'env_pgmax_pipeline' };
let port = '';
try { port = new URL(url.replace(/^postgres(ql)?:\/\//, 'http://')).port; } catch { /* unparseable: no port */ }
if (AUTO_DETECT_PORTS.has(port)) return { value: 0, reason: 'transaction_pooler_port' };
if (params.get('prepare') === 'false') return { value: 0, reason: 'url_prepare_false' };
if (process.env.GBRAIN_PREPARE === 'false' || process.env.GBRAIN_PREPARE === '0') return { value: 0, reason: 'gbrain_prepare_off' };
return { value: null, reason: 'default' };
}
/** The read-side pool option `resolveReadPoolPipeline` decides: `{ max_pipeline: 0 }` or nothing. */
export function readPoolPipelineOptions(url: string): { max_pipeline?: number } {
const { value } = resolveReadPoolPipeline(url);
return value === null ? {} : { max_pipeline: value };
}
/** Pipeline depth inside a transaction on a pool that does not pipeline across transactions (#6930). */
export const TRANSACTION_PIPELINE_DEPTH = 100;
/**
* #6930: a read-side pool that `resolveReadPoolPipeline` keeps from pipelining (a transaction-mode pooler) still
* pipelines the statements of one transaction on the connection its owner holds (sql.begin, sql.reserve): the pooler
* pins one server connection from BEGIN until the transaction ends, and the driver never sends a statement behind one
* that may end the transaction, so #6543's boundary stays closed. Prepared statements stay off (`resolvePrepare`).
* `GBRAIN_PG_TXN_PIPELINE=0` restores one round trip per statement.
*/
export function transactionPipelineOptions(url: string): { transaction_pipeline?: number } {
const off = process.env.GBRAIN_PG_TXN_PIPELINE === '0' || process.env.GBRAIN_PG_TXN_PIPELINE === 'false';
return !off && resolveReadPoolPipeline(url).value === 0 ? { transaction_pipeline: TRANSACTION_PIPELINE_DEPTH } : {};
}
/**
* Seconds a pool waits for a connection before giving up with CONNECT_TIMEOUT
* when its URL names no `connect_timeout` of its own.
*/
const FALLBACK_CONNECT_TIMEOUT_S = 10;
/**
* Upper bound for a URL-supplied `connect_timeout`. postgres.js arms the
* connect timer with `setTimeout(seconds * 1000)`, and a delay past 2^31-1 ms
* does not fit the runtime's timer: Bun and Node replace it with 1 ms, so a
* "wait practically forever" value would fail every connect at once.
*/
const MAX_CONNECT_TIMEOUT_S = Math.floor(0x7fffffff / 1000);
/**
* #5984: the store a pool shares described parameter types in (the vendored
* driver's `shared_types`): one per database target in this process, saved for
* the next process (src/core/pg-type-cache.ts). A connection running a statement
* for the first time then skips the describe round trip and keeps pipelining.
* On by default; GBRAIN_PG_TYPE_CACHE=0 turns it off.
*/
export function resolveSharedTypes(url?: string): SharedParameterTypes | false {
return sharedParameterTypes(url);
}
/** #6930: the array types every pool for this database target shares, so only the process's first connection fetches them. */
export function resolveArrayTypes(url?: string): SharedArrayTypes | null {
return sharedArrayTypes(url);
}
/** Forgets the shared parameter and array types of these pools; a schema change may have changed them. */
export function clearSharedTypes(...pools: unknown[]): void {
for (const pool of pools) {
const options = (pool as { options?: { shared_types?: Map<string, number[]> | null; array_types?: SharedArrayTypes | null } } | null)?.options;
options?.shared_types?.clear();
if (options?.array_types) options.array_types.rows = null;
}
}
/**
* A new pool's connection check. It also reads the scope of the saved parameter
* types (server version, schema version and the database as the server names
* it) in the same round trip and loads them; a database without a `config`
* table falls back to `SELECT 1`.
*/
/** `persisted: false` (an engine opened from settings) keeps the shared descriptions in this process and reads no file under the home. */
export async function checkPoolAndLoadSharedTypes(pool: ReturnType<typeof postgres>, url: string, opts: { persisted?: boolean } = {}): Promise<void> {
let rows: Array<{ server: string; schema: string | null; database: string | null }>;
try {
rows = await pool.unsafe(`SELECT current_setting('server_version_num') AS server, (SELECT value FROM config WHERE key='version') AS schema,
current_database() || '@' || coalesce(host(inet_server_addr()), '') || ':' || coalesce(inet_server_port()::text, '') || '?' || current_user AS database`) as unknown as typeof rows;
} catch (err) {
if ((err as { code?: string }).code !== '42P01') throw err;
await pool`SELECT 1`;
return;
}
if (opts.persisted !== false) loadSharedParameterTypes(url, String(rows[0]?.server ?? ''), rows[0]?.schema ?? null, rows[0]?.database ?? null);
}
/**
* The `connect_timeout` each postgres() pool is built with, read from that
* pool's own URL.
*
* Every call site has to pass the option explicitly (an unset option would
* drop to postgres.js's 30s default), and postgres.js lets an explicit option
* override the URL query. So the URL's value is honoured only if we read it
* here and hand it back. The query is located the way the driver's `new URL()`
* does (after the first `?`, before any `#`), so userinfo and host text are
* never consulted. Accepted: whole seconds, surrounding blanks allowed, capped
* at MAX_CONNECT_TIMEOUT_S. Everything else, including `0` (no timer at all in
* postgres.js), keeps the fallback so no gbrain connect waits unbounded.
*/
export function resolveUrlConnectTimeout(url: string): number {
const [beforeFragment = ''] = url.split('#', 1);
const queryAt = beforeFragment.indexOf('?');
if (queryAt < 0) return FALLBACK_CONNECT_TIMEOUT_S;
const requested = new URLSearchParams(beforeFragment.slice(queryAt + 1)).get('connect_timeout');
const digits = requested?.match(/^\s*(\d+)\s*$/)?.[1];
const seconds = digits === undefined ? 0 : parseInt(digits, 10);
if (seconds < 1) return FALLBACK_CONNECT_TIMEOUT_S;
return Math.min(seconds, MAX_CONNECT_TIMEOUT_S);
}
export function resolvePoolSize(explicit?: number): number {
if (typeof explicit === 'number' && explicit > 0) return explicit;
const raw = process.env.GBRAIN_POOL_SIZE;
if (raw) {
const parsed = parseInt(raw, 10);
if (Number.isFinite(parsed) && parsed > 0) return parsed;
}
return DEFAULT_POOL_SIZE_FALLBACK;
}
let warnedBadMaxLifetime = false;
/** Test-only: reset the warn-once latch. */
export function _resetMaxLifetimeWarningForTests(): void {
warnedBadMaxLifetime = false;
}
/**
* Client-pool connection max lifetime for every postgres() call site
* (module singleton, engine instance pool, ConnectionManager read + direct
* pools).
*
* postgres.js already defaults to `60 * (30 + Math.random() * 30)` — and
* critically that built-in default is a FUNCTION, re-evaluated PER
* CONNECTION (connection.js: `typeof seconds === 'function' ? seconds() :
* seconds`), so each connection gets its own 30–60min deadline. A
* pre-evaluated number would make every connection in a pool share ONE
* recycle deadline — a warm-up burst then reconnects simultaneously
* (data-migration specialist finding). The default here is therefore the
* same per-connection jitter function; only the env override returns a
* fixed number (the explicit escape hatch):
*
* GBRAIN_POOL_MAX_LIFETIME_S=900 # recycle after 15 min
* GBRAIN_POOL_MAX_LIFETIME_S=0 # disable recycling entirely
*
* max_lifetime only recycles connections as they are RETURNED to the pool;
* it cannot reclaim a leaked checkout — this is explicitness + a knob, not
* a starvation fix. Invalid values warn once on stderr and fall back to the
* default. The env param is injectable so tests never mutate process.env.
*/
export function resolveMaxLifetimeSeconds(
env: Record<string, string | undefined> = process.env,
): number | null | (() => number) {
const raw = env.GBRAIN_POOL_MAX_LIFETIME_S;
if (raw !== undefined && raw !== '') {
const parsed = Number(raw);
if (Number.isFinite(parsed) && Number.isInteger(parsed) && parsed >= 0) {
return parsed === 0 ? null : parsed;
}
if (!warnedBadMaxLifetime) {
warnedBadMaxLifetime = true;
process.stderr.write(
`[gbrain] Ignoring invalid GBRAIN_POOL_MAX_LIFETIME_S=${JSON.stringify(raw)} (want a non-negative integer of seconds; 0 disables); using the jittered 30-60min default\n`,
);
}
}
// Per-connection jitter, matching the postgres.js built-in default shape.
return () => Math.floor(60 * (30 + Math.random() * 30));
}
/**
* Session-level GUCs applied to every new backend connection. Prevents
* orphan pgbouncer sessions from holding locks or running queries
* indefinitely when the postgres.js client disconnects mid-transaction
* (typical cause: autopilot SIGKILL'd by launchd, worker crash-loop,
* or transient network drop).
*
* Observed failure mode these prevent: a single autopilot UPDATE on
* `minion_jobs.lock_until` left a pooler backend in `state='active'`
* / `wait_event='ClientRead'` for 24h+, holding a RowExclusiveLock
* that blocked every subsequent `ALTER TABLE minion_jobs ...`.
*
* Defaults are conservative (chosen not to interfere with bulk work
* like long-running embed passes or CREATE INDEX on large tables):
* - statement_timeout = '5min'
* - idle_in_transaction_session_timeout = '5min' (matches v0.18.0
* posture; #363's original 2min default was tightened to 5min on
* merge with v0.21.0's setSessionDefaults to avoid regressing
* long-running embed passes)
*
* Override per-GUC with env vars:
* - GBRAIN_STATEMENT_TIMEOUT
* - GBRAIN_IDLE_TX_TIMEOUT
* - GBRAIN_CLIENT_CHECK_INTERVAL (Postgres 14+; empty default - opt-in
* only since older self-hosted Postgres rejects this startup param)
*
* Set any env var to '0' or 'off' to disable that GUC entirely.
*
* Delivered via postgres.js's `connection` option, which sends these as
* startup parameters in the initial connection packet. A direct server and a
* session-mode pooler apply them for the backend's lifetime. A transaction-mode
* pooler does not: PgBouncer and Supavisor (Supabase :6543) drop or ignore
* startup parameters, so `SHOW statement_timeout` through them reads `0` and no
* server-side timeout bounds an autocommit statement (#6543; doctor's
* `persistence_session_timeouts` and serve's transport line report it, and
* `ALTER ROLE ... SET statement_timeout` is the fix there).
*
* Supersedes the v0.21.0 `setSessionDefaults(sql)` helper, which used
* a post-pool `SET` command; transaction-mode poolers strip session-state
* SETs between transactions.
*/
const DEFAULT_STATEMENT_TIMEOUT = '5min';
const DEFAULT_IDLE_TX_TIMEOUT = '5min';
/**
* #6317 (C1): the `application_name` every gbrain pool starts its connections
* with, `gbrain <kind>:<pid>:<nonce8>`, so `writer status` can find the owner
* process's backends in `pg_stat_activity` (and a ClientRead wedge is visible
* in one command). Through a transaction-mode pooler the server connection is
* shared, so the mapping is partial; readers say `backend_visibility: pooled`.
*/
export function gbrainApplicationName(): string {
const owner = claimOwner();
return `gbrain ${owner.kind}:${owner.pid}:${(owner.nonce ?? '').slice(0, 8)}`.slice(0, 63);
}
/**
* #6383: the driver's pool-health hooks and the in-flight watchdog budget, one
* set per pool. `PoolHealthHooks` is what an engine passes to every pool it
* opens; `poolHealthOptions` turns it into postgres.js options.
*/
/** #6543 (A4): `reason` is `age` when the statement kept receiving bytes past its budget, `idle` when nothing came back; `budget_ms` is that statement's own cap. */
export interface StuckConnectionInfo { age_ms: number; queued: number; statement: string; reason?: 'age' | 'idle'; budget_ms?: number }
/** #6543 (A6): a connection the driver retired for an incident (`stuck`, `desync`, `closed` under statements) reconnected, or failed to. */
export interface ConnectionRecoveryInfo { connection: number; cause: 'stuck' | 'desync' | 'closed'; code?: string }
export interface PoolHealthHooks {
/** #5730: a connection came back to the pool inside a transaction and was discarded. */
onpoisoned?: (status: string) => void;
/** #6383: the in-flight watchdog retired a connection whose statement never answered. */
onstuck?: (info: StuckConnectionInfo) => void;
/** #6383: a statement failed to build (`UNDEFINED_VALUE`, `MAX_PARAMETERS_EXCEEDED`) and was rejected alone; #6543: `parameter` is the undefined one's 1-based index. */
onbuilderror?: (code: string, statement: string, parameter?: number) => void;
/** An answer arrived on a connection with no statement waiting for it; the driver retired the connection. */
ondesync?: (info: DesyncConnectionInfo) => void;
/** #6543 (A6): a connection retired by an incident completed a new startup. */
onrecovered?: (info: ConnectionRecoveryInfo) => void;
/** #6543 (A6): the reconnect of a connection retired by an incident failed. */
onrecoveryfailed?: (info: ConnectionRecoveryInfo) => void;
}
export interface DesyncConnectionInfo { message: string; connection: number; statement: string }
const DEFAULT_STUCK_GRACE_MS = 30_000;
/** A `statement_timeout` GUC value in milliseconds (a bare number is milliseconds), or null when unset or 0. */
export function gucMilliseconds(value: string | undefined): number | null {
if (value === undefined) return null;
const m = /^\s*(\d+(?:\.\d+)?)\s*(us|ms|s|min|h|d)?\s*$/i.exec(value);
if (!m) return null;
const n = Number(m[1]);
const unit = (m[2] ?? 'ms').toLowerCase();
const ms = unit === 'us' ? n / 1000 : unit === 'ms' ? n : unit === 's' ? n * 1000 : unit === 'min' ? n * 60_000 : unit === 'h' ? n * 3_600_000 : n * 86_400_000;
return ms > 0 ? ms : null;
}
/**
* #6383: the pool's in-flight budget in seconds: its `statement_timeout` plus
* `GBRAIN_PG_STUCK_GRACE_MS` (default 30000). The driver retires a connection
* whose head statement waits that long with nothing coming back (`reason=idle`)
* or, since #6543, runs that long in total while bytes keep arriving
* (`reason=age`). A statement whose operation declared a longer
* `statement_timeout` on its connection gets that timeout plus the grace; a
* declared 0 has no cap. Null, which disables the watchdog, when the statement
* timeout is off or the grace is `0`/`off`.
*/
export function resolveInflightTimeoutSeconds(statementTimeout: string | undefined): number | null {
const grace = resolveStuckGraceMs();
const budget = gucMilliseconds(statementTimeout);
return budget === null || grace === null ? null : Math.ceil((budget + grace) / 1000);
}
/** `GBRAIN_PG_STUCK_GRACE_MS` (default 30000), or null when it is `0`/`off` (the watchdog is disabled). */
export function resolveStuckGraceMs(): number | null {
const raw = process.env.GBRAIN_PG_STUCK_GRACE_MS;
if (raw === '0' || raw === 'off') return null;
return raw !== undefined && Number.isFinite(Number(raw)) && Number(raw) > 0 ? Number(raw) : DEFAULT_STUCK_GRACE_MS;
}
/**
* The postgres.js options for `PoolHealthHooks` on a pool whose connections start with `connection.statement_timeout`.
* #6543 (A4): the same budget caps a statement's total age (`inflight_max`, never reset by received bytes) and its
* silence (`inflight_timeout`). The driver raises both for a statement whose operation declared a longer
* `statement_timeout` on its connection (to that timeout plus `inflight_grace`) and drops both for a declared 0, so
* the budget travels with the operation and does not depend on a session `SET` reaching the backend.
*/
export function poolHealthOptions(hooks: PoolHealthHooks | undefined, statementTimeout: string | undefined): Record<string, unknown> {
const seconds = resolveInflightTimeoutSeconds(statementTimeout);
const grace = resolveStuckGraceMs();
return {
onpoisoned: hooks?.onpoisoned,
onstuck: hooks?.onstuck,
onbuilderror: hooks?.onbuilderror,
ondesync: hooks?.ondesync,
onrecovered: hooks?.onrecovered,
onrecoveryfailed: hooks?.onrecoveryfailed,
inflight_timeout: seconds,
inflight_max: seconds,
inflight_grace: seconds === null || grace === null ? null : grace / 1000,
};
}
export function resolveSessionTimeouts(): Record<string, string> {
const out: Record<string, string> = {};
const add = (envKey: string, gucKey: string, defaultVal: string) => {
const raw = process.env[envKey];
if (raw === '0' || raw === 'off') return; // explicitly disabled
const val = raw ?? defaultVal;
if (val) out[gucKey] = val;
};
add('GBRAIN_STATEMENT_TIMEOUT', 'statement_timeout', DEFAULT_STATEMENT_TIMEOUT);
add('GBRAIN_IDLE_TX_TIMEOUT', 'idle_in_transaction_session_timeout', DEFAULT_IDLE_TX_TIMEOUT);
// client_connection_check_interval is opt-in: Postgres 14+ only, and some
// managed pooler tiers reject unknown startup parameters. Users can enable
// it explicitly once they know their Postgres version supports it.
add('GBRAIN_CLIENT_CHECK_INTERVAL', 'client_connection_check_interval', '');
return out;
}
/**
* Backward-compat shim for v0.21.0's `setSessionDefaults` callers.
* The current implementation no-ops because session timeouts are now
* applied at connection-startup time via `resolveSessionTimeouts()` +
* postgres.js's `connection` option (more durable across PgBouncer
* transaction mode).
*
* Kept as a callable function so existing call sites in `connect()` and
* `PostgresEngine.connect()` don't need to be touched on the merge —
* the work has already happened by the time this function would run.
*/
export async function setSessionDefaults(_sql: ReturnType<typeof postgres>): Promise<void> {
// No-op: timeouts are now applied as startup parameters in resolveSessionTimeouts().
}
export function getConnection(): ReturnType<typeof postgres> {
if (!sql) {
throw new GBrainError(
'No database connection',
'connect() has not been called',
'Run gbrain init --supabase or gbrain init --url <connection_string>',
);
}
return sql;
}
/**
* Connect the module-level singleton. Returns `true` iff THIS call created the
* singleton, `false` if it joined an existing one.
*
* #1471 ownership: the create-vs-join decision is made HERE, atomically. There
* is no `await` between the `if (sql)` null-check below and the synchronous
* `sql = postgres(url, opts)` assignment, so two concurrent module connects
* cannot both observe `sql === null` and both create. Callers store the return
* as their ownership token (`PostgresEngine._ownsModuleSingleton`); only the
* creator may later tear the singleton down. Borrowers (probe engines created
* while the singleton already exists) get `false` and must NOT disconnect it.
*
* Back-compat: callers that ignore the return value are unaffected.
*/
export async function connect(config: EngineConfig, hooks: PoolHealthHooks = {}): Promise<boolean> {
if (sql) {
// Warn if a different URL is passed — the old connection is still in use
if (config.database_url && connectedUrl && config.database_url !== connectedUrl) {
console.warn('[gbrain] connect() called with a different database_url but a connection already exists. Using existing connection.');
}
return false; // joined an existing singleton — caller is a borrower
}
const url = config.database_url;
if (!url) {
throw new GBrainError(
'No database URL',
'database_url is missing from config',
'Run gbrain init --supabase or gbrain init --url <connection_string>',
);
}
try {
const prepare = resolvePrepare(url);
const timeouts = resolveSessionTimeouts();
const opts: Record<string, unknown> = {
max: resolvePoolSize(config.pool_max),
idle_timeout: 20,
connect_timeout: resolveUrlConnectTimeout(url),
// Explicit (matches the postgres.js implicit default; GBRAIN_POOL_MAX_LIFETIME_S overrides).
max_lifetime: resolveMaxLifetimeSeconds(),
types: {
// Register pgvector type
bigint: postgres.BigInt,
},
// Silence postgres NOTICE-level messages by default ("relation already
// exists, skipping" floods stdout under idempotent CREATE statements
// during migrations + initSchema, and breaks stdout-parsing callers like
// `gbrain jobs submit --json | ...`). Opt back in with GBRAIN_PG_NOTICES=1.
onnotice: process.env.GBRAIN_PG_NOTICES === '1' ? undefined : () => {},
...poolHealthOptions(hooks, timeouts.statement_timeout),
shared_types: resolveSharedTypes(url),
array_types: resolveArrayTypes(url),
...readPoolPipelineOptions(url),
...transactionPipelineOptions(url),
};
opts.connection = { ...timeouts, application_name: gbrainApplicationName() };
if (typeof prepare === 'boolean') {
opts.prepare = prepare;
if (!prepare) warnPoolerPrepareOffOnce(url);
}
sql = postgres(url, traceSqlOptions(withPgTls(url, opts), 'module'));
// GBRA-156: a one-shot command's startup reads its retired-marker state beside its persistence row, which opened the
// pool's second connection on the critical path (about three round trips behind a pooler); it opens beside the first.
if (isOneShotCommand() && Number(opts.max) >= 3) sql`SELECT 1`.catch(() => undefined);
// Test connection
await checkPoolAndLoadSharedTypes(sql, url);
connectedUrl = url;
await setSessionDefaults(sql);
return true; // we created the singleton — caller is the owner
} catch (e: unknown) {
sql = null;
connectedUrl = null;
const tlsRefusal = await tlsRequiredDefaultError(url, e);
if (tlsRefusal) throw tlsRefusal;
const msg = e instanceof Error ? e.message : String(e);
throw new GBrainError(
'Cannot connect to database',
msg,
'Check the database URL; `gbrain engine status --probe` names where it comes from (environment variable or the config file under GBRAIN_HOME)',
);
}
}
export async function disconnect(): Promise<void> {
// v0.41.25.0 (#1570) — instrument every disconnect call site so v0.41.26
// can identify the caller that's nulling the module singleton mid-cycle.
// Best-effort: audit failure must never block the actual disconnect.
// The audit module is lazy-imported to keep db.ts cold-path-free for
// tools that import db without ever calling disconnect.
try {
const { logDbDisconnect } = await import('./audit/db-disconnect-audit.ts');
// db.ts is always the module-singleton path by construction; no
// instance-pool callers go through here.
logDbDisconnect('postgres', 'module');
} catch { /* best-effort; never block disconnect on audit failure */ }
// #1471 (codex #6): snapshot + null the singleton BEFORE awaiting end(), so a
// concurrent module connect() can't observe a non-null `sql` mid-teardown and
// join a pool that's already closing. Mirrors the v0.41.8.0 PGLite-disconnect
// snapshot+early-null pattern.
const s = sql;
sql = null;
connectedUrl = null;
if (s) await endPoolBounded(s);
}
export async function initSchema(): Promise<void> {
const conn = getConnection();
// Advisory lock prevents concurrent initSchema() calls from deadlocking
// Lock-census (PR6 D5): INTENTIONALLY brain-global (session lock, fixed key 42) — schema replay mutates the whole database, not one source.
await conn`SELECT pg_advisory_lock(42)`;
try {
// #4477: run the same forward-reference bootstrap as
// PostgresEngine.initSchema BEFORE replaying the schema blob. Without
// it, an older brain whose tables predate the blob's forward-referenced
// columns (e.g. pages.deleted_at ← pages_deleted_at_purge_idx) wedges
// on the blob's CREATE INDEX. Idempotent single-probe no-op on fresh
// installs and modern brains.
await applyPostgresForwardReferenceBootstrap(conn);
await conn.unsafe(SCHEMA_SQL);
} finally {
await conn`SELECT pg_advisory_unlock(42)`;
}
}
export { verifySchema } from './schema-verify.ts';
export async function withTransaction<T>(fn: (tx: ReturnType<typeof postgres>) => Promise<T>): Promise<T> {
return beginReadWrite(getConnection(), async (tx) => fn(tx as unknown as ReturnType<typeof postgres>));
}
// issue #1720 (proposal 4): the startup connect matcher and the runtime
// matcher drifted — this used to be a private 5-pattern list that predated
// /connection.*closed/i and the CONNECTION_ENDED/CONNECTION_CLOSED codes, so
// a pooler close hitting connectWithRetry was treated as permanent. One
// canonical source now: retry-matcher.ts's isRetryableConnError (a strict
// superset of the old list). Do NOT reintroduce a local pattern list here;
// the agreement guard in test/worker-conn-resilience-1720.test.ts pins it.
export const isRetryableDbConnectError = isRetryableConnError;
export interface ConnectWithRetryOpts {
attempts?: number;
baseDelayMs?: number;
noRetry?: boolean;
log?: (line: string) => void;
/**
* Also retry postgres.js CONNECT_TIMEOUT (#5946). Set it only when this
* process already holds a connection to the same database_url, as the
* per-worker pools of parallel import and incremental sync do: the route is
* then known to work, so a missed handshake timer means the handshake was
* starved (typically by a long synchronous stretch on this event loop), and
* no session existed yet, so dialing again is safe. Every other caller
* keeps failing fast on a timeout, which usually means a bad route.
*/
retryConnectTimeout?: boolean;
}
export async function connectWithRetry(
engine: BrainEngine,
config: EngineConfig & { poolSize?: number },
opts: ConnectWithRetryOpts = {},
): Promise<void> {
const noRetry = opts.noRetry ?? (process.env.GBRAIN_NO_RETRY_CONNECT === '1');
const attempts = noRetry ? 1 : (opts.attempts ?? 3);
const baseDelayMs = opts.baseDelayMs ?? 1000;
const log = opts.log ?? ((line) => console.warn(line));
let lastErr: unknown;
for (let i = 0; i < attempts; i++) {
try {
await engine.connect(config);
return;
} catch (e: unknown) {
lastErr = e;
const retryable = isRetryableDbConnectError(e) || (opts.retryConnectTimeout === true && isConnectTimeoutError(e));
const isLast = i === attempts - 1;
if (!retryable || isLast) {
throw e;
}
const delay = baseDelayMs * Math.pow(2, i);
const msg = e instanceof Error ? e.message : String(e);
log(`[connect] attempt ${i + 1} failed (${msg.slice(0, 80)}), retrying in ${delay}ms`);
await new Promise(resolve => setTimeout(resolve, delay));
}
}
// Unreachable, but TS needs the throw.
throw lastErr;
}