@crombolo/data 0.10.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/data",
-  "version": "0.10.0",
+  "version": "0.12.1",
   "description": "SQLite and Postgres storage for crombolo: schema, migrations and repositories.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,6 +28,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.10.0"
+    "@crombolo/core": "0.12.1"
   }
 }

package/src/ambient.ts

@@ -0,0 +1,20 @@
+/** The transaction the current async chain is inside, shared by the drivers and the lock managers. */
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/** Cleared when its transaction ends, so work left running afterwards falls back to the pool. */
+export interface AmbientTransaction<T> {
+  owner: object
+  tx: T | undefined
+}
+
+export const ambient = new AsyncLocalStorage<AmbientTransaction<unknown>>()
+
+/** The open transaction this chain holds on `owner`'s connection, if any. */
+export function ambientFor<T>(owner: object): T | undefined {
+  const store = ambient.getStore()
+  return store?.owner === owner ? (store.tx as T | undefined) : undefined
+}
+
+export function insideTransaction(): boolean {
+  return ambient.getStore()?.tx !== undefined
+}

package/src/audit.ts

@@ -0,0 +1,291 @@
+/**
+ * The audit log: who did what, when and from where. Entries are only ever
+ * added, read and aged out; nothing edits one. docs/audit-log.md.
+ */
+import { normaliseUuid } from '@crombolo/core'
+import type { Db } from './database.ts'
+import { DbDate } from './dialect.ts'
+import { STATE_AUDIT_LOG } from './schema/audit-log.ts'
+
+export type AuditCategory =
+  | 'content'
+  | 'media'
+  | 'member'
+  | 'schema'
+  | 'settings'
+  | 'user'
+  | 'permission'
+  | 'sign-in'
+  | 'system'
+
+export const AUDIT_CATEGORIES: readonly AuditCategory[] = [
+  'content',
+  'media',
+  'member',
+  'schema',
+  'settings',
+  'user',
+  'permission',
+  'sign-in',
+  'system',
+]
+
+/** Where an entry came from: a request (with its address), the command line, or a background job. */
+export type AuditSource = 'request' | 'cli' | 'job'
+
+export interface AuditEntryInput {
+  category: AuditCategory
+  action: string
+  source: AuditSource
+  userKey?: string | null
+  /** The user's name when the entry was written; for a failed sign-in, the login tried. */
+  userName?: string | null
+  entityType?: string | null
+  entityKey?: string | null
+  entityName?: string | null
+  ipAddress?: string | null
+  forwardedFor?: string | null
+  detail?: string | null
+  occurredAt?: Date
+}
+
+export interface AuditEntry {
+  id: number
+  occurredAt: Date
+  category: AuditCategory
+  action: string
+  source: AuditSource
+  userKey: string | null
+  userName: string | null
+  entityType: string | null
+  entityKey: string | null
+  entityName: string | null
+  ipAddress: string | null
+  forwardedFor: string | null
+  detail: string | null
+}
+
+export interface AuditFilter {
+  userKey?: string
+  entityKey?: string
+  category?: AuditCategory
+  action?: string
+  since?: Date
+  until?: Date
+  /** Matched anywhere in the item's name or key, or the user's name. */
+  text?: string
+  ascending?: boolean
+}
+
+/** What a key names, for an entry to carry once the thing itself has gone. */
+export interface AuditSubject {
+  entityType: string
+  entityKey: string
+  entityName: string | null
+}
+
+const UUID = /^\{?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\}?$/i
+
+const LIMITS = {
+  action: 64,
+  userName: 255,
+  entityType: 64,
+  entityKey: 255,
+  entityName: 255,
+  ipAddress: 64,
+  forwardedFor: 255,
+  detail: 4000,
+} as const
+
+function clip(value: string | null | undefined, limit: number): string | null {
+  if (value === null || value === undefined || value === '') return null
+  return value.length > limit ? value.slice(0, limit) : value
+}
+
+function text(value: unknown): string | null {
+  return value === null || value === undefined ? null : String(value)
+}
+
+function toEntry(row: Record<string, unknown>): AuditEntry {
+  return {
+    id: Number(row.id),
+    occurredAt: DbDate.fromDb(row.occurred_at) ?? new Date(0),
+    category: String(row.category) as AuditCategory,
+    action: String(row.action),
+    source: String(row.source) as AuditSource,
+    userKey: row.user_key ? normaliseUuid(String(row.user_key)) : null,
+    userName: text(row.user_name),
+    entityType: text(row.entity_type),
+    entityKey: text(row.entity_key),
+    entityName: text(row.entity_name),
+    ipAddress: text(row.ip_address),
+    forwardedFor: text(row.forwarded_for),
+    detail: text(row.detail),
+  }
+}
+
+export class AuditLog {
+  #db: Db
+
+  constructor(db: Db) {
+    this.#db = db
+  }
+
+  async record(entries: AuditEntryInput | readonly AuditEntryInput[]): Promise<void> {
+    const list = Array.isArray(entries) ? entries : [entries as AuditEntryInput]
+    for (const entry of list) {
+      const userKey =
+        entry.userKey && UUID.test(entry.userKey) ? normaliseUuid(entry.userKey) : null
+      const entityKey =
+        entry.entityKey && UUID.test(entry.entityKey)
+          ? normaliseUuid(entry.entityKey)
+          : entry.entityKey
+      await this.#db.exec(
+        `INSERT INTO audit_entry (occurred_at, category, action, user_key, user_name, entity_type,
+           entity_key, entity_name, source, ip_address, forwarded_for, detail)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [
+          DbDate.toDb(entry.occurredAt ?? new Date()),
+          entry.category,
+          clip(entry.action, LIMITS.action),
+          userKey,
+          clip(entry.userName, LIMITS.userName),
+          clip(entry.entityType, LIMITS.entityType),
+          clip(entityKey, LIMITS.entityKey),
+          clip(entry.entityName, LIMITS.entityName),
+          entry.source,
+          clip(entry.ipAddress, LIMITS.ipAddress),
+          clip(entry.forwardedFor, LIMITS.forwardedFor),
+          clip(entry.detail, LIMITS.detail),
+        ],
+      )
+    }
+  }
+
+  async query(
+    filter: AuditFilter = {},
+    page: { skip: number; take: number } = { skip: 0, take: 100 },
+  ): Promise<{ total: number; items: AuditEntry[] }> {
+    const where: string[] = []
+    const params: unknown[] = []
+    if (filter.userKey !== undefined) {
+      if (!UUID.test(filter.userKey)) return { total: 0, items: [] }
+      where.push('user_key = ?')
+      params.push(normaliseUuid(filter.userKey))
+    }
+    if (filter.entityKey !== undefined) {
+      where.push('entity_key = ?')
+      params.push(UUID.test(filter.entityKey) ? normaliseUuid(filter.entityKey) : filter.entityKey)
+    }
+    if (filter.category !== undefined) {
+      where.push('category = ?')
+      params.push(filter.category)
+    }
+    if (filter.action !== undefined) {
+      where.push('action = ?')
+      params.push(filter.action)
+    }
+    if (filter.since !== undefined) {
+      where.push('occurred_at >= ?')
+      params.push(DbDate.toDb(filter.since))
+    }
+    if (filter.until !== undefined) {
+      where.push('occurred_at < ?')
+      params.push(DbDate.toDb(filter.until))
+    }
+    const needle = filter.text?.trim().toLowerCase()
+    if (needle) {
+      const like = `%${needle.replace(/[\\%_]/g, (c) => `\\${c}`)}%`
+      where.push(
+        `(LOWER(entity_name) LIKE ? ESCAPE '\\' OR LOWER(entity_key) LIKE ? ESCAPE '\\' OR LOWER(user_name) LIKE ? ESCAPE '\\')`,
+      )
+      params.push(like, like, like)
+    }
+    const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''
+    const counted = await this.#db.query<{ total: number }>(
+      `SELECT COUNT(*) AS total FROM audit_entry ${clause}`,
+      params,
+    )
+    const order = filter.ascending ? 'ASC' : 'DESC'
+    const rows = await this.#db.query(
+      `SELECT * FROM audit_entry ${clause} ORDER BY occurred_at ${order}, id ${order} LIMIT ? OFFSET ?`,
+      [...params, page.take, page.skip],
+    )
+    return { total: Number(counted[0]?.total ?? 0), items: rows.map(toEntry) }
+  }
+
+  /** Everyone the log names, by the name they had most recently. */
+  async users(): Promise<Array<{ key: string; name: string }>> {
+    const rows = await this.#db.query<{ user_key: string; user_name: string | null }>(
+      `SELECT e.user_key, e.user_name FROM audit_entry e
+       JOIN (SELECT user_key, MAX(id) AS id FROM audit_entry WHERE user_key IS NOT NULL GROUP BY user_key) latest
+         ON latest.id = e.id
+       ORDER BY e.user_name`,
+    )
+    return rows.map((row) => ({
+      key: normaliseUuid(String(row.user_key)),
+      name: row.user_name ? String(row.user_name) : '',
+    }))
+  }
+
+  /** Deletes entries older than `before`, and returns how many went. */
+  async prune(before: Date): Promise<number> {
+    const counted = await this.#db.query<{ total: number }>(
+      'SELECT COUNT(*) AS total FROM audit_entry WHERE occurred_at < ?',
+      [DbDate.toDb(before)],
+    )
+    const total = Number(counted[0]?.total ?? 0)
+    if (total > 0)
+      await this.#db.exec('DELETE FROM audit_entry WHERE occurred_at < ?', [DbDate.toDb(before)])
+    return total
+  }
+
+  /** When this database began keeping the log; history before it is in the content versions. */
+  async startedAt(): Promise<Date | undefined> {
+    const rows = await this.#db.query<{ applied_at: unknown }>(
+      'SELECT MIN(applied_at) AS applied_at FROM migration_history WHERE to_state = ?',
+      [STATE_AUDIT_LOG],
+    )
+    return DbDate.fromDb(rows[0]?.applied_at)
+  }
+
+  /**
+   * What a key names. A version answers for the item it belongs to, so a
+   * rollback is filed under the page it rolled back.
+   */
+  async describe(entityType: string, key: string): Promise<AuditSubject> {
+    const named = (entityName: unknown, type = entityType, entityKey = key): AuditSubject => ({
+      entityType: type,
+      entityKey,
+      entityName: entityName === null || entityName === undefined ? null : String(entityName),
+    })
+    if (entityType.endsWith('Version') && /^\d+$/.test(key)) {
+      const rows = await this.#db.query<{ unique_id: string; text: string | null }>(
+        'SELECT n.unique_id, n.text FROM content_version cv JOIN node n ON n.id = cv.node_id WHERE cv.id = ?',
+        [Number(key)],
+      )
+      const row = rows[0]
+      const owner = entityType.slice(0, -'Version'.length)
+      return row ? named(row.text, owner, normaliseUuid(String(row.unique_id))) : named(null)
+    }
+    if (entityType === 'Language') {
+      const rows = await this.#db.query<{ culture_name: string }>(
+        'SELECT culture_name FROM language WHERE iso_code = ?',
+        [key],
+      )
+      return named(rows[0]?.culture_name ?? null)
+    }
+    if (!UUID.test(key)) return named(null)
+    const uuid = normaliseUuid(key)
+    const sql =
+      entityType === 'User'
+        ? 'SELECT user_name AS name FROM user_account WHERE key = ?'
+        : entityType === 'UserGroup'
+          ? 'SELECT name FROM user_group WHERE key = ?'
+          : entityType === 'DictionaryItem'
+            ? 'SELECT item_key AS name FROM dictionary_item WHERE key = ?'
+            : 'SELECT text AS name FROM node WHERE unique_id = ?'
+    const rows = await this.#db.query<{ name: string | null }>(sql, [uuid])
+    return named(rows[0]?.name ?? null, entityType, uuid)
+  }
+}

package/src/busy.ts

@@ -0,0 +1,74 @@
+/** Lock contention: recognising it in driver errors, retrying it, and the error an editor sees. */
+
+export type Contention = 'deadlock' | 'lockTimeout' | 'busy'
+
+/** A write gave up waiting for another to finish. Answered as 503 with Retry-After. */
+export class ContentBusyError extends Error {
+  constructor(
+    readonly contention: Contention,
+    readonly retryAfterSeconds = 2,
+  ) {
+    super('Someone else is changing this content right now. Try again in a moment.')
+  }
+}
+
+const POSTGRES_CODES: Record<string, Contention> = {
+  '40P01': 'deadlock',
+  '40001': 'deadlock',
+  '55P03': 'lockTimeout',
+}
+
+/** Which kind of contention a driver error reports, if any. */
+export function classifyContention(error: unknown): Contention | undefined {
+  if (error instanceof ContentBusyError) return error.contention
+  if (!error || typeof error !== 'object') return undefined
+  const { code, errno, message } = error as { code?: unknown; errno?: unknown; message?: unknown }
+  // Bun's Postgres driver reports the SQLSTATE as `errno`, other drivers as `code`.
+  for (const state of [errno, code])
+    if (typeof state === 'string' && POSTGRES_CODES[state]) return POSTGRES_CODES[state]
+  if (
+    typeof code === 'string' &&
+    (code.startsWith('SQLITE_BUSY') || code.startsWith('SQLITE_LOCKED'))
+  )
+    return 'busy'
+  if (errno === 5 || errno === 6) return 'busy'
+  if (typeof message === 'string' && /database (table )?is locked/i.test(message)) return 'busy'
+  return undefined
+}
+
+export interface RetryPolicy {
+  /** Attempts in all, the first included. */
+  attempts: number
+  /** Waits between attempts; injected so a test does not sleep. */
+  sleep: (ms: number) => Promise<void>
+  backoffMs: number
+}
+
+export const DEFAULT_RETRY: RetryPolicy = {
+  attempts: 2,
+  sleep: (ms) => Bun.sleep(ms),
+  backoffMs: 50,
+}
+
+/**
+ * Runs `fn`, retrying a deadlock: the database rolled the transaction back, so
+ * running it again is safe. A lock timeout is not retried, since the wait has
+ * already been spent. Contention that outlasts the policy becomes ContentBusyError.
+ */
+export async function retryContention<T>(
+  fn: () => Promise<T>,
+  policy: RetryPolicy = DEFAULT_RETRY,
+): Promise<T> {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      const contention = classifyContention(error)
+      if (!contention) throw error
+      if (contention !== 'deadlock' || attempt >= policy.attempts) {
+        throw error instanceof ContentBusyError ? error : new ContentBusyError(contention)
+      }
+      await policy.sleep(policy.backoffMs * attempt)
+    }
+  }
+}

package/src/change-report.ts

@@ -23,6 +23,12 @@ export interface Finding {
   subjectType:
     | 'document'
     | 'document-type'
+    | 'media-type'
+    | 'member-type'
+    | 'member'
+    | 'member-group'
+    | 'user'
+    | 'user-group'
     | 'property'
     | 'migration'
     | 'file'

package/src/cluster.ts

@@ -20,6 +20,9 @@ export interface CacheInstruction {
   createdBy: string | null
 }
 
+/** Where Postgres says an instruction was written, so nodes poll now rather than on their timer. */
+export const CACHE_INSTRUCTION_CHANNEL = 'crombolo_cache_instruction'
+
 export async function appendCacheInstruction(
   db: Db,
   instruction: { kind: CacheInstructionKind; payload?: Record<string, unknown>; by?: string },
@@ -33,6 +36,9 @@ export async function appendCacheInstruction(
       instruction.by ?? null,
     ],
   )
+  // Delivered at commit, so a write that rolls back wakes nobody.
+  if (db.dialect.name === 'postgres')
+    await db.exec('SELECT pg_notify(?, ?)', [CACHE_INSTRUCTION_CHANNEL, instruction.kind])
 }
 
 /** The highest instruction id, so a fresh node ignores history. */
@@ -60,25 +66,28 @@ export interface ServerIdentity {
   revision: string
   /** `all`, `api` or `web`: what this node serves, so the cluster can be read back by role. */
   role?: string
+  /** The Crombolo release this node runs; `version` is the schema set's. */
+  cromboloVersion?: string
 }
 
 /** Records this node in `server`; called at boot and on each poll. */
 export async function touchServer(db: Db, identity: ServerIdentity): Promise<void> {
   const now = DbDate.toDb(new Date())
   const role = identity.role ?? null
+  const crombolo = identity.cromboloVersion ?? null
   const existing = await db.query<{ node_id: string }>(
     'SELECT node_id FROM server WHERE node_id = ?',
     [identity.nodeId],
   )
   if (existing[0]) {
     await db.exec(
-      'UPDATE server SET version = ?, revision = ?, role = ?, last_seen = ? WHERE node_id = ?',
-      [identity.version, identity.revision, role, now, identity.nodeId],
+      'UPDATE server SET version = ?, revision = ?, role = ?, crombolo_version = ?, last_seen = ? WHERE node_id = ?',
+      [identity.version, identity.revision, role, crombolo, now, identity.nodeId],
     )
   } else {
     await db.exec(
-      'INSERT INTO server (node_id, version, revision, role, last_seen) VALUES (?, ?, ?, ?, ?)',
-      [identity.nodeId, identity.version, identity.revision, role, now],
+      'INSERT INTO server (node_id, version, revision, role, crombolo_version, last_seen) VALUES (?, ?, ?, ?, ?, ?)',
+      [identity.nodeId, identity.version, identity.revision, role, crombolo, now],
     )
   }
 }
@@ -89,13 +98,15 @@ export interface LiveNode {
   role: string | null
   version: string | null
   revision: string | null
+  /** Null for a row written before node releases were recorded. */
+  cromboloVersion: string | null
   lastSeen: Date
 }
 
 /** The nodes that have polled within `seenWithinMs`: the cluster as it stands. */
 export async function liveNodes(db: Db, options: { seenWithinMs: number }): Promise<LiveNode[]> {
   const rows = await db.query(
-    'SELECT node_id, role, version, revision, last_seen FROM server WHERE last_seen >= ? ORDER BY node_id',
+    'SELECT node_id, role, version, revision, crombolo_version, last_seen FROM server WHERE last_seen >= ? ORDER BY node_id',
     [DbDate.toDb(new Date(Date.now() - options.seenWithinMs))],
   )
   return rows.map((row) => ({
@@ -103,6 +114,7 @@ export async function liveNodes(db: Db, options: { seenWithinMs: number }): Prom
     role: (row.role as string | null) ?? null,
     version: (row.version as string | null) ?? null,
     revision: (row.revision as string | null) ?? null,
+    cromboloVersion: (row.crombolo_version as string | null) ?? null,
     lastSeen: DbDate.fromDb(row.last_seen) as Date,
   }))
 }

package/src/database.ts

@@ -1,7 +1,9 @@
 /** Driver-agnostic database handle. */
+
 import { Database as BunSqlite } from 'bun:sqlite'
+import { ambient, ambientFor } from './ambient.ts'
 import { type Dialect, type DialectName, dialectFor } from './dialect.ts'
-import { createLockManager, type LockManager } from './locks.ts'
+import { createLockManager, DEFAULT_LOCK_TIMEOUT_MS, type LockManager } from './locks.ts'
 
 export interface Db {
   readonly dialect: Dialect
@@ -10,6 +12,8 @@ export interface Db {
   exec(sql: string, params?: unknown[]): Promise<void>
   transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T>
   close(): Promise<void>
+  /** Postgres only: calls `onNotify` for each `NOTIFY` on `channel`; resolves to the way to stop. */
+  listen?(channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>>
 }
 
 export interface ConnectOptions {
@@ -20,18 +24,40 @@ export interface ConnectOptions {
   file?: string
   /** Postgres connection string. Ignored for SQLite. */
   url?: string
+  /** How long a write waits for a content lock; defaults to `CROMBOLO_LOCK_TIMEOUT_SECONDS`, else 15s. */
+  lockTimeoutMs?: number
+}
+
+export function resolveLockTimeoutMs(options: ConnectOptions = {}): number {
+  if (options.lockTimeoutMs !== undefined) return options.lockTimeoutMs
+  const seconds = Number(Bun.env.CROMBOLO_LOCK_TIMEOUT_SECONDS)
+  return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : DEFAULT_LOCK_TIMEOUT_MS
 }
 
+/**
+ * One connection has one transaction at a time, but async chains interleave:
+ * a background job's BEGIN between a request's BEGIN and COMMIT would fail, or
+ * worse, land its statements in the request's transaction. So top-level
+ * transactions queue here, and a chain already inside one joins it.
+ */
 class SqliteDb implements Db {
   readonly dialect = dialectFor('sqlite')
   readonly locks: LockManager
   #db: BunSqlite
   #inTransaction: boolean
-
-  constructor(db: BunSqlite, locks?: LockManager, inTransaction = false) {
+  #gate: { tail: Promise<void> }
+
+  constructor(
+    db: BunSqlite,
+    locks?: LockManager,
+    inTransaction = false,
+    gate: { tail: Promise<void> } = { tail: Promise.resolve() },
+    lockTimeoutMs?: number,
+  ) {
     this.#db = db
-    this.locks = locks ?? createLockManager(this)
+    this.locks = locks ?? createLockManager(this, { timeoutMs: lockTimeoutMs })
     this.#inTransaction = inTransaction
+    this.#gate = gate
   }
 
   async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {
@@ -44,14 +70,29 @@ class SqliteDb implements Db {
 
   async transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T> {
     if (this.#inTransaction) return fn(this)
-    this.#db.exec('BEGIN')
+    const tx = new SqliteDb(this.#db, this.locks, true, this.#gate)
+    if (ambientFor(this.#db)) return fn(tx)
+    const previous = this.#gate.tail
+    let release!: () => void
+    this.#gate.tail = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    await previous
     try {
-      const result = await fn(new SqliteDb(this.#db, this.locks, true))
-      this.#db.exec('COMMIT')
-      return result
-    } catch (error) {
-      this.#db.exec('ROLLBACK')
-      throw error
+      this.#db.exec('BEGIN')
+      const store = { owner: this.#db, tx: tx as unknown }
+      try {
+        const result = await ambient.run(store, () => fn(tx))
+        this.#db.exec('COMMIT')
+        return result
+      } catch (error) {
+        this.#db.exec('ROLLBACK')
+        throw error
+      } finally {
+        store.tx = undefined
+      }
+    } finally {
+      release()
     }
   }
 
@@ -64,6 +105,10 @@ interface SqlTag {
   unsafe(sql: string, params?: unknown[]): Promise<unknown>
   begin<T>(fn: (tx: SqlTag) => Promise<T>): Promise<T>
   close(): Promise<void>
+  listen(
+    channel: string,
+    onNotify: (payload: string) => void,
+  ): Promise<{ unlisten(): Promise<void> }>
 }
 
 class PostgresDb implements Db {
@@ -72,9 +117,9 @@ class PostgresDb implements Db {
   #sql: SqlTag
   #inTransaction: boolean
 
-  constructor(sql: SqlTag, locks?: LockManager, inTransaction = false) {
+  constructor(sql: SqlTag, locks?: LockManager, inTransaction = false, lockTimeoutMs?: number) {
     this.#sql = sql
-    this.locks = locks ?? createLockManager(this)
+    this.locks = locks ?? createLockManager(this, { timeoutMs: lockTimeoutMs })
     this.#inTransaction = inTransaction
   }
 
@@ -86,15 +131,33 @@ class PostgresDb implements Db {
     await this.#sql.unsafe(this.dialect.render(sql), params)
   }
 
-  /** Nested calls join the enclosing transaction, as they do on SQLite. */
+  /**
+   * Nested calls join the enclosing transaction, as they do on SQLite. The
+   * chain is marked as inside one, so a deadlock is not retried into a
+   * transaction Postgres has already aborted.
+   */
   async transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T> {
     if (this.#inTransaction) return fn(this)
-    return this.#sql.begin(async (tx) => fn(new PostgresDb(tx, this.locks, true)))
+    return this.#sql.begin(async (sql) => {
+      const tx = new PostgresDb(sql, this.locks, true)
+      const store = { owner: this, tx: tx as unknown }
+      try {
+        return await ambient.run(store, () => fn(tx))
+      } finally {
+        store.tx = undefined
+      }
+    })
   }
 
   async close(): Promise<void> {
     await this.#sql.close()
   }
+
+  async listen(channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>> {
+    if (this.#inTransaction) throw new Error('A transaction cannot listen.')
+    const subscription = await this.#sql.listen(channel, onNotify)
+    return () => subscription.unlisten()
+  }
 }
 
 export function resolveDialectName(options: ConnectOptions = {}): DialectName {
@@ -109,7 +172,7 @@ export async function connect(options: ConnectOptions = {}): Promise<Db> {
     // A modest pool: many short-lived connections exhaust Postgres' client limit,
     // and a single process does not need more.
     const sql = new SQL({ url, max: options.poolSize ?? 5 }) as unknown as SqlTag
-    const db = new PostgresDb(sql)
+    const db = new PostgresDb(sql, undefined, false, resolveLockTimeoutMs(options))
     await db.exec('CREATE EXTENSION IF NOT EXISTS citext')
     return db
   }
@@ -117,5 +180,5 @@ export async function connect(options: ConnectOptions = {}): Promise<Db> {
   sqlite.exec('PRAGMA journal_mode = WAL')
   sqlite.exec('PRAGMA foreign_keys = ON')
   sqlite.exec('PRAGMA busy_timeout = 5000')
-  return new SqliteDb(sqlite)
+  return new SqliteDb(sqlite, undefined, false, undefined, resolveLockTimeoutMs(options))
 }