@makaio/storage-pg 1.0.0-dev-1781260968078

package/dist/index.mjs

@@ -0,0 +1,527 @@
+import path from "node:path";
+import { and, asc, count, eq, getTableColumns, sql } from "drizzle-orm";
+import { brandDatabase, buildFirstUserMessagePreviewQuery, getRawSqlExecutor, quoteSqlIdentifier, readErrorCode, someInCauseChain } from "@makaio/framework/storage/drizzle";
+import { PgDialect } from "drizzle-orm/pg-core";
+import { createHash } from "node:crypto";
+
+//#region src/raw-sql.ts
+/**
+* Attach the idle-connection error listener to a `pg` Pool.
+*
+* When the backend goes down or a network partition occurs, node-postgres
+* emits an error for every idle pooled connection on the pool itself; without
+* a listener that `'error'` event becomes an uncaught exception and kills the
+* host process. A dropped idle connection is routine (server restart, network
+* blip) and the pool replaces it on the next checkout, so the listener logs
+* the failure and lets the process continue.
+* @param pool - Pool to guard against unhandled idle-connection errors.
+*/
+function attachPgPoolErrorLogger(pool) {
+	pool.on("error", (error) => {
+		console.error("[makaio:storage-pg] Postgres pool: an idle pooled connection failed (backend restart or network drop); the pool replaces it on next use.", error);
+	});
+}
+/**
+* Create a {@link RawSqlExecutor} over a `pg` Pool.
+*
+* Standalone `run` and `all` calls go through the pool directly. `withSession`
+* checks out a single `pool.connect()` client for the duration of the callback.
+* The client is always released: returned to the pool on success, destroyed via
+* `release(true)` when the callback rejects so a poisoned connection (open or
+* aborted transaction) never re-enters the pool.
+*
+* INVARIANT: raw transaction control (BEGIN/COMMIT/ROLLBACK) may only ever be
+* issued inside {@link RawSqlExecutor.withSession}. On Postgres, standalone
+* `run` goes through the pool — raw BEGIN there would stripe statements across
+* connections as the pool re-assigns them per call.
+*
+* SQL objects are serialized using `PgDialect.sqlToQuery`, which produces
+* `$1`-style positional placeholders compatible with the `pg` driver.
+* @param pool - Postgres pool to execute statements against.
+* @returns Executor delegating to the pool.
+*/
+function createPostgresRawSqlExecutor(pool) {
+	const pgDialect = new PgDialect();
+	const sessionOver = (target) => ({
+		async run(query) {
+			const { sql: text, params } = pgDialect.sqlToQuery(query);
+			return { rowsAffected: (await target.query(text, params)).rowCount ?? 0 };
+		},
+		async all(query) {
+			const { sql: text, params } = pgDialect.sqlToQuery(query);
+			return (await target.query(text, params)).rows;
+		}
+	});
+	const standalone = sessionOver(pool);
+	return {
+		dialect: "postgres",
+		run: standalone.run,
+		all: standalone.all,
+		async withSession(fn) {
+			const client = await pool.connect();
+			try {
+				const result = await fn(sessionOver(client));
+				client.release();
+				return result;
+			} catch (error) {
+				client.release(true);
+				throw error;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/client.ts
+/**
+* node-postgres driver glue.
+*
+* Delegation target of the engine's `createClient` — deliberately kept off
+* the package barrel: consumers create Postgres clients through the engine
+* registry (`createDatabaseClient` in `@makaio/storage-drizzle/client`),
+* never by calling the driver glue directly.
+* @packageDocumentation
+*/
+/**
+* Production driver loaders: direct dynamic imports resolved relative to this
+* module. Both specifiers are declared dependencies of this package, so the
+* import resolves correctly even under strict installs (pnpm, Yarn PnP).
+*/
+const defaultDriverLoaders = {
+	loadPg: () => import("pg"),
+	loadDrizzlePg: () => import("drizzle-orm/node-postgres")
+};
+/**
+* Default maximum pool size for Postgres connections.
+*
+* Sized for direct connections to a small managed Postgres tier without an
+* external connection pooler. Callers that need a different limit pass
+* `postgres.poolMax` in `DatabaseClientConfig`.
+*/
+const DEFAULT_PG_POOL_MAX = 4;
+/**
+* Creates a database client backed by the node-postgres (`pg`) driver.
+*
+* Delegation target of the Postgres engine's `createClient`: the engine
+* package owns both the dialect-specific behavior registered through the
+* engine seam and this driver glue.
+*
+* Both `'pg'` and `'drizzle-orm/node-postgres'` load through direct dynamic
+* `import()` calls, so the drivers load on the first Postgres client rather
+* than at module load (laziness is preserved). Resolution happens from this
+* module, which declares both as regular dependencies, so it stays
+* strict-install-safe (pnpm, Yarn PnP) where the drivers are only resolvable
+* from this package. Bundle-time resolvability is acceptable here precisely
+* because they are declared dependencies of this package — the build leaves
+* them external (see `build.ts`); bundler-opacity is only required for
+* specifiers the resolving package does not declare.
+* @param url - Postgres connection URL (`postgres://` or `postgresql://`).
+* @param options - Optional pool tuning options.
+* @param loaders - Internal driver-loader seam; defaults to the literal
+*   dynamic imports. Tests inject a throwing loader to exercise the error path.
+* @returns Database client with drizzle ORM instance and async close method.
+*/
+async function createNodePgClient(url, options, loaders = defaultDriverLoaders) {
+	let pg;
+	let drizzlePg;
+	try {
+		({default: pg} = await loaders.loadPg());
+		({drizzle: drizzlePg} = await loaders.loadDrizzlePg());
+	} catch (error) {
+		throw new Error("createNodePgClient: failed to load the Postgres driver modules ('pg' and 'drizzle-orm/node-postgres'). 'pg' is a dependency of @makaio/storage-pg — verify the host application's install is intact.", { cause: error });
+	}
+	const pool = new pg.Pool({
+		connectionString: url,
+		max: options?.poolMax ?? DEFAULT_PG_POOL_MAX
+	});
+	attachPgPoolErrorLogger(pool);
+	const db = drizzlePg(pool);
+	brandDatabase(db, "postgres", createPostgresRawSqlExecutor(pool));
+	let closed = false;
+	return {
+		db,
+		dialect: "postgres",
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			await pool.end();
+		}
+	};
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* Postgres-specific classification of database errors.
+*
+* node-postgres surfaces server failures as `DatabaseError` instances carrying
+* the SQLSTATE in a non-standard `code` property (and the violated constraint
+* name in `constraint` for constraint failures). These classifiers walk the
+* cause chain via the shared helpers from `@makaio/storage-drizzle`, so
+* wrapped driver errors classify the same as bare ones.
+* @packageDocumentation
+*/
+/**
+* SQLSTATE codes Postgres raises for an already-existing schema object:
+* `42P07` (duplicate_table) and `42710` (duplicate_object — indexes,
+* triggers, and other named objects).
+*/
+const POSTGRES_DUPLICATE_OBJECT_CODES = new Set(["42P07", "42710"]);
+/**
+* Returns `true` when the error (or any link in its cause chain) reports
+* that a schema object already exists on Postgres.
+*
+* Matches the SQLSTATE codes `42P07`/`42710`. Used by the migration
+* applicator to decide whether a failed first CREATE can be adopted into the
+* ledger.
+* @param error - Error thrown by a DDL statement.
+* @returns Whether the failure is a duplicate-schema-object conflict.
+*/
+function isPostgresDuplicateObjectError(error) {
+	return someInCauseChain(error, (link) => {
+		const code = readErrorCode(link);
+		return code !== void 0 && POSTGRES_DUPLICATE_OBJECT_CODES.has(code);
+	});
+}
+/**
+* Returns `true` when the error (or any link in its cause chain) reports a
+* Postgres unique-constraint violation.
+*
+* Matches SQLSTATE `23505` (unique_violation); when `constraint` is given,
+* the driver error's `constraint` property must match it too, so callers can
+* react to one specific index without swallowing unrelated violations.
+*
+* Used by write paths that resolve write-write races through a bounded retry
+* (for example MAX-based counter assignment under `READ COMMITTED`, where two
+* concurrent statements can compute the same next value).
+* @param error - Error thrown by a DML statement.
+* @param constraint - Optional constraint/index name to scope the match.
+* @returns Whether the failure is a unique-constraint violation.
+*/
+function isPostgresUniqueViolationError(error, constraint) {
+	return someInCauseChain(error, (link) => {
+		if (readErrorCode(link) !== "23505") return false;
+		if (constraint === void 0) return true;
+		const { constraint: violated } = link;
+		return violated === constraint;
+	});
+}
+
+//#endregion
+//#region src/fts-strategy.ts
+/**
+* Postgres full-text-search strategy.
+*
+* Postgres full-text search runs over the `messages.content_tsv` stored
+* generated tsvector column (english regconfig) and its GIN index — both ship
+* through the central Postgres migration chain, so provisioning here is a
+* no-op. Message search operates on the messages table object passed in by
+* the caller (the congruent twin resolved per handle); session search and the
+* preview query are raw SQL against the fixed physical names.
+* @packageDocumentation
+*/
+/**
+* Resolve one required column from a table's column map.
+* @param columns - Column map produced by `getTableColumns`.
+* @param name - Property name of the required column.
+* @returns The resolved column.
+* @throws Error naming the missing column.
+*/
+function requireColumn(columns, name) {
+	const column = columns[name];
+	if (column === void 0) throw new Error(`postgresFtsSearchStrategy: the messages table passed in is missing the '${name}' column`);
+	return column;
+}
+/**
+* Resolve the columns the message-search queries need, failing loudly when
+* the passed table is not a messages table.
+* @param messagesTable - Messages table object received from the caller.
+* @returns The three columns referenced by the search queries.
+* @throws Error naming the first missing column.
+*/
+function requireMessageSearchColumns(messagesTable) {
+	const columns = getTableColumns(messagesTable);
+	return {
+		messageId: requireColumn(columns, "messageId"),
+		sessionId: requireColumn(columns, "sessionId"),
+		timestamp: requireColumn(columns, "timestamp")
+	};
+}
+/**
+* Builds SQL predicates for optional session-search filters.
+*
+* Postgres uses native boolean literals for the import filter.
+* @param input - Optional status/import filters from the search input.
+* @returns SQL fragment appended to WHERE clauses.
+*/
+function buildSearchFilterSql(input) {
+	const conditions = [];
+	if (input.status !== void 0) conditions.push(sql`s.status = ${input.status}`);
+	if (input.isImported !== void 0) conditions.push(input.isImported ? sql`s.is_imported = true` : sql`COALESCE(s.is_imported, false) = false`);
+	if (conditions.length === 0) return sql``;
+	return sql` AND ${sql.join(conditions, sql` AND `)}`;
+}
+/**
+* Builds the shared session-match `WHERE` predicate for the session-search and
+* session-count queries.
+*
+* Both queries match a session when any of its messages matches the FTS query
+* OR its title matches the LIKE pattern, narrowed by the optional status/import
+* filters. The predicate is authored once here so the two queries can never
+* drift; the leading-whitespace layout and `query` → `likePattern` → filter
+* parameter order are preserved verbatim from the inlined form, keeping the
+* emitted SQL byte-identical to the previously-pinned behavior.
+* @param input - Session-search/count input carrying the query, LIKE pattern,
+*   and optional filters.
+* @returns The `WHERE (...)` predicate fragment including the filter clause.
+*/
+function buildSessionMatchWhere(input) {
+	const filterClause = buildSearchFilterSql(input);
+	return sql`WHERE (
+        EXISTS (
+          SELECT 1
+          FROM messages m
+          WHERE m.session_id = s.session_id
+            AND m.content_tsv @@ websearch_to_tsquery('english', ${input.query})
+        )
+        OR LOWER(s.title) LIKE ${input.likePattern}
+      )
+      ${filterClause}`;
+}
+/**
+* The Postgres FTS strategy: tsvector matching via `websearch_to_tsquery`,
+* `ts_rank` ordering, and `ts_headline` excerpts.
+*/
+const postgresFtsSearchStrategy = {
+	dialect: "postgres",
+	async provisionSearchIndex() {},
+	async searchMessages(db, messagesTable, input) {
+		const { sessionId, limit } = input;
+		const columns = requireMessageSearchColumns(messagesTable);
+		const tsQuery = sql`websearch_to_tsquery('english', ${input.query})`;
+		const matches = sql`content_tsv @@ ${tsQuery}`;
+		const where = sessionId ? and(eq(columns.sessionId, sessionId), matches) : matches;
+		const rows = await db.select().from(messagesTable).where(where).orderBy(sql`ts_rank(content_tsv, ${tsQuery}) DESC`, asc(columns.timestamp), asc(columns.messageId)).limit(limit);
+		const [countRow] = await db.select({ total: count() }).from(messagesTable).where(where);
+		return {
+			rows,
+			total: countRow?.total ?? 0
+		};
+	},
+	async searchMessageExcerpts(db, messagesTable, input) {
+		const { sessionId, limit } = input;
+		const columns = requireMessageSearchColumns(messagesTable);
+		const tsQuery = sql`websearch_to_tsquery('english', ${input.query.trim()})`;
+		const matches = sql`content_tsv @@ ${tsQuery}`;
+		const where = sessionId !== void 0 ? and(eq(columns.sessionId, sessionId), matches) : matches;
+		const rows = await db.select({
+			messageId: columns.messageId,
+			sessionId: columns.sessionId,
+			score: sql`ts_rank(content_tsv, ${tsQuery})`,
+			excerpt: sql`ts_headline('english', content_text, ${tsQuery}, 'StartSel=<mark>, StopSel=</mark>, MaxWords=40, MinWords=15')`
+		}).from(messagesTable).where(where).orderBy(sql`ts_rank(content_tsv, ${tsQuery}) DESC`, asc(columns.timestamp), asc(columns.messageId)).limit(limit);
+		const [countRow] = await db.select({ total: count() }).from(messagesTable).where(where);
+		return {
+			results: rows,
+			total: countRow?.total ?? 0
+		};
+	},
+	async searchSessionRows(db, input) {
+		return getRawSqlExecutor(db).all(sql`
+      SELECT DISTINCT
+        s.session_id,
+        s.created_at::double precision AS created_at,
+        s.last_activity_at::double precision AS last_activity_at,
+        s.status,
+        s.title,
+        s.lead_agent_id,
+        s.parent_session_id,
+        s.root_session_id,
+        s.fork_point_message_id,
+        s.branch_kind,
+        s.adapter_name,
+        s.adapter_session_id,
+        s.adapter_id,
+        s.is_orchestrated::int AS is_orchestrated,
+        s.is_imported::int AS is_imported,
+        s.summary,
+        s.summary_updated_at::double precision AS summary_updated_at,
+        s.fork_transforms,
+        s.target_working_directory
+      FROM sessions s
+      ${buildSessionMatchWhere(input)}
+      ORDER BY last_activity_at DESC
+      LIMIT ${input.limit}
+    `);
+	},
+	async countSessionMatches(db, input) {
+		const [totalRow] = await getRawSqlExecutor(db).all(sql`
+      SELECT COUNT(DISTINCT s.session_id)::int as total
+      FROM sessions s
+      ${buildSessionMatchWhere(input)}
+    `);
+		return totalRow?.total ?? 0;
+	},
+	async fetchFirstUserMessagePreviews(db, sessionIds) {
+		if (sessionIds.length === 0) return /* @__PURE__ */ new Map();
+		const previewRows = await getRawSqlExecutor(db).all(buildFirstUserMessagePreviewQuery(sessionIds, sql`m2.message_id < m.message_id`));
+		const previewBySession = /* @__PURE__ */ new Map();
+		for (const row of previewRows) previewBySession.set(row.sessionId, row.preview);
+		return previewBySession;
+	}
+};
+
+//#endregion
+//#region src/migrations.ts
+/**
+* Postgres migration behavior: ledger DDL, transaction pinning, and the
+* cross-process advisory lock protocol.
+*
+* The statement texts and key derivations in this module are cross-version
+* contracts — runners built from different framework versions must agree on
+* them byte-for-byte, otherwise concurrent runs stop serializing against each
+* other or stop recognizing each other's ledgers. Every value is pinned by
+* unit tests and exercised by the live conformance coverage in
+* `storage/conformance/src/suites/migration-runner-postgres.test.ts`.
+* @packageDocumentation
+*/
+/**
+* Derive the 64-bit advisory lock key for a migration ledger table.
+*
+* The key is the first 8 bytes (big-endian, signed) of
+* `SHA-256("makaio:migrations:<tableName>")`. The derivation is a
+* cross-version contract: concurrent runners built from different framework
+* versions must compute the same key for the same ledger table, otherwise
+* they stop serializing against each other.
+* @param tableName - Ledger table name the run serializes on.
+* @returns Signed 64-bit key for `pg_advisory_xact_lock`.
+*/
+function migrationAdvisoryLockKey(tableName) {
+	return createHash("sha256").update(`makaio:migrations:${tableName}`).digest().readBigInt64BE(0);
+}
+/**
+* Build the idempotent `CREATE TABLE IF NOT EXISTS` DDL for the Postgres
+* migration ledger table.
+*
+* Uses an identity primary key and additionally enforces hash uniqueness at
+* the schema level: the runner already treats the hash as a migration's
+* identity, and the constraint backstops the advisory-lock serialization —
+* should a cross-process double-record ever slip past it, the insert fails
+* loudly instead of silently corrupting the ledger. The exact statement text
+* is a cross-version contract pinned by tests.
+* @param tableName - Ledger table name (engine default or caller-provided).
+* @returns Complete DDL statement text.
+*/
+function buildPostgresLedgerDdl(tableName) {
+	return `CREATE TABLE IF NOT EXISTS ${quoteSqlIdentifier(tableName)} (
+      id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+      hash text NOT NULL UNIQUE,
+      created_at numeric
+    )`;
+}
+/**
+* `BEGIN` statement that opens a Postgres migration transaction.
+*
+* Pins `READ COMMITTED` explicitly instead of inheriting
+* `default_transaction_isolation` (a database/role-settable setting the
+* framework does not control). The migration applicator's in-lock ledger
+* recheck requires a snapshot taken after the advisory lock is acquired;
+* under an ambient `REPEATABLE READ` or `SERIALIZABLE` default the
+* transaction snapshot would be established by the lock SELECT itself —
+* before the lock wait completes — so the recheck would miss a concurrent
+* runner's committed ledger row and re-apply the migration. `READ COMMITTED`
+* takes a fresh snapshot per statement, and commit visibility precedes lock
+* release, so the recheck observes every ledger row committed before the
+* lock was handed over.
+*/
+const POSTGRES_MIGRATION_BEGIN = "BEGIN ISOLATION LEVEL READ COMMITTED";
+/**
+* Acquire the transaction-scoped advisory lock that serializes concurrent
+* migration runners on the same ledger table.
+*
+* Must be called inside an open transaction on the pinned session; the lock
+* releases automatically at COMMIT/ROLLBACK. The key is bound as text and
+* cast server-side: signed 64-bit keys exceed JS number precision and driver
+* BigInt parameter support varies. The caller owns rollback-on-failure — a
+* rejected lock acquisition (lock timeout, administrative cancel during a
+* contended wait) leaves the transaction open for the caller to roll back.
+* @param session - Pinned raw SQL session with the transaction open.
+* @param ledgerTableName - Ledger table name the lock key is derived from.
+* @returns Resolves once the lock is held for the transaction's lifetime.
+*/
+async function acquirePostgresMigrationLock(session, ledgerTableName) {
+	const lockKey = migrationAdvisoryLockKey(ledgerTableName).toString();
+	await session.run(sql`SELECT pg_advisory_xact_lock(CAST(${lockKey} AS bigint))`);
+}
+
+//#endregion
+//#region src/engine.ts
+/**
+* The Postgres storage engine definition.
+*
+* The `'postgres'` literals in this module denote the engine's own identity —
+* they are declarations, not branches over dialects.
+* @packageDocumentation
+*/
+/**
+* The Postgres storage engine.
+*
+* Claims `postgres://` and `postgresql://` URLs (case-insensitively,
+* mirroring the engine hint table in `@makaio/storage-drizzle`) and creates
+* clients over the node-postgres driver glue owned by this package (`pg` is
+* a regular dependency, loaded lazily when a client is created). Register it
+* explicitly via `registerStorageEngine` or host boot options; Node runtime hosts
+* additionally auto-register it for recognized database URLs through this
+* package's well-known `storageEngine` export.
+*
+* Migration behavior preserves the cross-version Postgres contracts
+* byte-for-byte (`__makaio_migrations` ledger name and DDL,
+* `BEGIN ISOLATION LEVEL READ COMMITTED`, the advisory-lock key derivation,
+* `__makaio_migrations_<hash>` extension ledgers). The chain directory name
+* `drizzle-postgres` is deliberately distinct from the default `drizzle`
+* directory so embedded-host chain discovery never picks up the Postgres
+* chain.
+*/
+const postgresStorageEngine = {
+	dialect: "postgres",
+	matchesUrl: (url) => /^postgres(ql)?:\/\//i.test(url),
+	async createClient(config) {
+		if (config.url === void 0) throw new Error("postgresStorageEngine: a Postgres connection URL is required to create a client. Pass a postgres:// or postgresql:// URL in config.url — the engine never applies a default URL.");
+		return createNodePgClient(config.url, config.postgres);
+	},
+	errors: {
+		isDuplicateObjectError: isPostgresDuplicateObjectError,
+		isUniqueViolationError: isPostgresUniqueViolationError
+	},
+	capabilities: {
+		binaryColumnType: "bytea",
+		maxCounterAssignmentRaces: true,
+		async tableExists(executor, tableName) {
+			return (await executor.all(sql`SELECT table_name FROM information_schema.tables WHERE table_schema = current_schema() AND table_name = ${tableName}`)).length > 0;
+		}
+	},
+	migrations: {
+		defaultLedgerTable: "__makaio_migrations",
+		journalDialect: "postgresql",
+		chainDirName: "drizzle-postgres",
+		resolveSourceChainDir: () => path.resolve(import.meta.dirname, "..", "drizzle-postgres"),
+		buildLedgerDdl: buildPostgresLedgerDdl,
+		beginTransactionStatement: POSTGRES_MIGRATION_BEGIN,
+		acquireTransactionLock: acquirePostgresMigrationLock,
+		extensionLedgerName: (sourceHash) => `__makaio_migrations_${sourceHash}`
+	},
+	fts: postgresFtsSearchStrategy
+};
+
+//#endregion
+//#region src/index.ts
+/**
+* Well-known engine export consumed by host URL auto-resolve: runtime hosts
+* that recognize a Postgres database URL import this package and register
+* `storageEngine` with the engine registry. Same object as
+* {@link postgresStorageEngine}.
+*/
+const storageEngine = postgresStorageEngine;
+
+//#endregion
+export { POSTGRES_MIGRATION_BEGIN, buildPostgresLedgerDdl, isPostgresDuplicateObjectError, isPostgresUniqueViolationError, migrationAdvisoryLockKey, postgresFtsSearchStrategy, postgresStorageEngine, storageEngine };

package/dist/migrations.d.ts

@@ -0,0 +1,58 @@
+import { type RawSqlSession } from '@makaio/framework/storage/drizzle';
+/**
+ * Derive the 64-bit advisory lock key for a migration ledger table.
+ *
+ * The key is the first 8 bytes (big-endian, signed) of
+ * `SHA-256("makaio:migrations:<tableName>")`. The derivation is a
+ * cross-version contract: concurrent runners built from different framework
+ * versions must compute the same key for the same ledger table, otherwise
+ * they stop serializing against each other.
+ * @param tableName - Ledger table name the run serializes on.
+ * @returns Signed 64-bit key for `pg_advisory_xact_lock`.
+ */
+export declare function migrationAdvisoryLockKey(tableName: string): bigint;
+/**
+ * Build the idempotent `CREATE TABLE IF NOT EXISTS` DDL for the Postgres
+ * migration ledger table.
+ *
+ * Uses an identity primary key and additionally enforces hash uniqueness at
+ * the schema level: the runner already treats the hash as a migration's
+ * identity, and the constraint backstops the advisory-lock serialization —
+ * should a cross-process double-record ever slip past it, the insert fails
+ * loudly instead of silently corrupting the ledger. The exact statement text
+ * is a cross-version contract pinned by tests.
+ * @param tableName - Ledger table name (engine default or caller-provided).
+ * @returns Complete DDL statement text.
+ */
+export declare function buildPostgresLedgerDdl(tableName: string): string;
+/**
+ * `BEGIN` statement that opens a Postgres migration transaction.
+ *
+ * Pins `READ COMMITTED` explicitly instead of inheriting
+ * `default_transaction_isolation` (a database/role-settable setting the
+ * framework does not control). The migration applicator's in-lock ledger
+ * recheck requires a snapshot taken after the advisory lock is acquired;
+ * under an ambient `REPEATABLE READ` or `SERIALIZABLE` default the
+ * transaction snapshot would be established by the lock SELECT itself —
+ * before the lock wait completes — so the recheck would miss a concurrent
+ * runner's committed ledger row and re-apply the migration. `READ COMMITTED`
+ * takes a fresh snapshot per statement, and commit visibility precedes lock
+ * release, so the recheck observes every ledger row committed before the
+ * lock was handed over.
+ */
+export declare const POSTGRES_MIGRATION_BEGIN = "BEGIN ISOLATION LEVEL READ COMMITTED";
+/**
+ * Acquire the transaction-scoped advisory lock that serializes concurrent
+ * migration runners on the same ledger table.
+ *
+ * Must be called inside an open transaction on the pinned session; the lock
+ * releases automatically at COMMIT/ROLLBACK. The key is bound as text and
+ * cast server-side: signed 64-bit keys exceed JS number precision and driver
+ * BigInt parameter support varies. The caller owns rollback-on-failure — a
+ * rejected lock acquisition (lock timeout, administrative cancel during a
+ * contended wait) leaves the transaction open for the caller to roll back.
+ * @param session - Pinned raw SQL session with the transaction open.
+ * @param ledgerTableName - Ledger table name the lock key is derived from.
+ * @returns Resolves once the lock is held for the transaction's lifetime.
+ */
+export declare function acquirePostgresMigrationLock(session: RawSqlSession, ledgerTableName: string): Promise<void>;

package/dist/raw-sql.d.ts

@@ -0,0 +1,100 @@
+import type { RawSqlExecutor } from '@makaio/framework/storage/drizzle';
+/**
+ * Structural result shape of a node-postgres `query()` call.
+ *
+ * Self-owned so the published declaration file never references `import('pg')`.
+ */
+export interface PostgresQueryResultLike {
+    /** Result rows, each keyed by column name. */
+    rows: Array<Record<string, unknown>>;
+    /** Number of rows affected (INSERT/UPDATE/DELETE), or `null` when not applicable. */
+    rowCount: number | null;
+}
+/**
+ * Structural surface shared by a `pg` Pool and a checked-out pool client.
+ *
+ * Self-owned so the published declaration file never references `import('pg')`.
+ */
+export interface PostgresQueryableLike {
+    /**
+     * Execute a parameterized SQL statement.
+     * @param text - SQL text with `$1`-style positional placeholders.
+     * @param params - Positional parameter values corresponding to the placeholders.
+     * @returns Query result with rows and affected-row count.
+     */
+    query(text: string, params: unknown[]): Promise<PostgresQueryResultLike>;
+}
+/**
+ * Structural surface of a checked-out `pg` pool client.
+ *
+ * Self-owned so the published declaration file never references `import('pg')`.
+ */
+export interface PostgresPoolClientLike extends PostgresQueryableLike {
+    /**
+     * Return the connection to the pool.
+     * @param destroy - When truthy, destroy the connection instead of returning it.
+     *   Pass `true` after a failed callback to prevent a poisoned connection from
+     *   re-entering the pool.
+     */
+    release(destroy?: boolean): void;
+}
+/**
+ * Structural surface of a `pg` Pool.
+ *
+ * Self-owned so the published declaration file never references `import('pg')`.
+ */
+export interface PostgresPoolLike extends PostgresQueryableLike {
+    /**
+     * Check out a dedicated connection from the pool.
+     * @returns A pool client pinned to one server connection.
+     */
+    connect(): Promise<PostgresPoolClientLike>;
+    /**
+     * Drain the pool and close all connections.
+     * Called once during client shutdown.
+     * @returns Promise that resolves when the pool has fully closed.
+     */
+    end(): Promise<void>;
+    /**
+     * Subscribe to pool events. Only the `'error'` event is part of this
+     * structural surface: node-postgres re-emits failures of idle pooled
+     * connections on the pool's own event emitter, and an `'error'` event
+     * without a listener escalates to an uncaught exception that terminates
+     * the process.
+     * @param event - Pool event name; only `'error'` is consumed here.
+     * @param listener - Listener invoked with the emitted error.
+     */
+    on(event: 'error', listener: (error: Error) => void): void;
+}
+/**
+ * Attach the idle-connection error listener to a `pg` Pool.
+ *
+ * When the backend goes down or a network partition occurs, node-postgres
+ * emits an error for every idle pooled connection on the pool itself; without
+ * a listener that `'error'` event becomes an uncaught exception and kills the
+ * host process. A dropped idle connection is routine (server restart, network
+ * blip) and the pool replaces it on the next checkout, so the listener logs
+ * the failure and lets the process continue.
+ * @param pool - Pool to guard against unhandled idle-connection errors.
+ */
+export declare function attachPgPoolErrorLogger(pool: Pick<PostgresPoolLike, 'on'>): void;
+/**
+ * Create a {@link RawSqlExecutor} over a `pg` Pool.
+ *
+ * Standalone `run` and `all` calls go through the pool directly. `withSession`
+ * checks out a single `pool.connect()` client for the duration of the callback.
+ * The client is always released: returned to the pool on success, destroyed via
+ * `release(true)` when the callback rejects so a poisoned connection (open or
+ * aborted transaction) never re-enters the pool.
+ *
+ * INVARIANT: raw transaction control (BEGIN/COMMIT/ROLLBACK) may only ever be
+ * issued inside {@link RawSqlExecutor.withSession}. On Postgres, standalone
+ * `run` goes through the pool — raw BEGIN there would stripe statements across
+ * connections as the pool re-assigns them per call.
+ *
+ * SQL objects are serialized using `PgDialect.sqlToQuery`, which produces
+ * `$1`-style positional placeholders compatible with the `pg` driver.
+ * @param pool - Postgres pool to execute statements against.
+ * @returns Executor delegating to the pool.
+ */
+export declare function createPostgresRawSqlExecutor(pool: PostgresPoolLike): RawSqlExecutor;