pipework 0.251.0 → 0.252.1

package/src/test/reset.ts

@@ -0,0 +1,253 @@
+import postgres from 'postgres'
+
+// A worker keeps each per-file database across files and returns it to the
+// state it had right after the clone. The baseline is captured once, before
+// any file runs on it; a reset either restores that state exactly or reports
+// that it cannot, and the caller then takes a fresh clone instead.
+
+export const TEST_RESET_LOG_PREFIX = 'pipework:test-reset'
+
+export type FreshCloneReason = 'digest' | 'prepared-xact' | 'matview' | 'rls' | 'error'
+
+export interface Baseline {
+  digest: string
+  /** Main-fork bytes of every user table, partition and matview. */
+  sizes: Map<string, number>
+  /** relfilenode of every matview: a refresh rewrites it. */
+  matviews: Map<string, string>
+  /** Tables that already had storage at baseline: always cleared and reloaded. */
+  stored: Set<string>
+  /** COPY text of every table that had rows. */
+  rows: Map<string, Buffer>
+  /**
+   * Tables with storage whose rows row-level security hid from the connection
+   * that read the baseline (it neither bypasses RLS nor owns them): what they
+   * held is unknown, so a reset cannot restore them.
+   */
+  hidden: string[]
+  /** last_value (null = not called) and start_value of every sequence. */
+  sequences: Map<string, { last: string | null; start: string }>
+}
+
+export type ResetOutcome =
+  | { ok: true; cleared: number; reloaded: number }
+  | { ok: false; reason: FreshCloneReason }
+
+const USER_NAMESPACE = `n.nspname !~ '^pg_(toast_)?temp_' AND n.nspname <> 'information_schema' AND n.nspname <> 'pg_catalog'`
+
+// One md5 over the user-relevant catalogs. Storage fields (relfilenode,
+// relpages, reltuples, relfrozenxid, ...) are left out: they move without any
+// schema change. Objects below oid 16384 are the cluster's own.
+const DIGEST_QUERY = `
+SELECT md5(concat_ws('|',
+  (SELECT md5(coalesce(string_agg(row(n.oid, n.nspname, n.nspowner, n.nspacl)::text, E'\\n' ORDER BY n.oid), ''))
+     FROM pg_namespace n WHERE (n.oid >= 16384 OR n.nspname = 'public') AND ${USER_NAMESPACE}),
+  (SELECT md5(coalesce(string_agg(row(c.oid, c.relname, c.relnamespace, c.relkind, c.relpersistence, c.relowner, c.relacl, c.relrowsecurity, c.relforcerowsecurity, c.reloptions, c.relispartition, c.relpartbound::text)::text, E'\\n' ORDER BY c.oid), ''))
+     FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid >= 16384 AND ${USER_NAMESPACE}),
+  (SELECT md5(coalesce(string_agg(row(a.attrelid, a.attnum, a.attname, a.atttypid, a.attnotnull, a.atthasdef, a.attisdropped, a.attidentity, a.attgenerated, a.attacl, a.atttypmod, a.attcollation)::text, E'\\n' ORDER BY a.attrelid, a.attnum), ''))
+     FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE a.attnum > 0 AND c.oid >= 16384 AND ${USER_NAMESPACE}),
+  (SELECT md5(coalesce(string_agg(row(d.oid, d.adrelid, d.adnum, pg_get_expr(d.adbin, d.adrelid))::text, E'\\n' ORDER BY d.oid), '')) FROM pg_attrdef d WHERE d.adrelid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(k.oid, k.conname, k.contype, k.conrelid, k.convalidated, k.conkey, k.confrelid, k.confkey, k.conbin, k.condeferrable, k.condeferred, k.connoinherit)::text, E'\\n' ORDER BY k.oid), '')) FROM pg_constraint k WHERE k.oid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(i.indexrelid, i.indrelid, i.indkey, i.indisunique, i.indisvalid, i.indisready, i.indpred, i.indexprs)::text, E'\\n' ORDER BY i.indexrelid), '')) FROM pg_index i WHERE i.indexrelid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(p.oid, p.proname, p.pronamespace, p.proowner, p.proacl, p.prokind, md5(p.prosrc), p.proargtypes, p.prorettype, p.provolatile, p.prosecdef, p.proconfig, p.proisstrict)::text, E'\\n' ORDER BY p.oid), '')) FROM pg_proc p WHERE p.oid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(t.oid, t.tgname, t.tgrelid, t.tgenabled, t.tgfoid, t.tgtype, t.tgattr, t.tgqual::text)::text, E'\\n' ORDER BY t.oid), '')) FROM pg_trigger t WHERE t.tgrelid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(o.oid, o.polname, o.polrelid, o.polcmd, o.polroles, o.polqual, o.polwithcheck)::text, E'\\n' ORDER BY o.oid), '')) FROM pg_policy o),
+  (SELECT md5(coalesce(string_agg(row(r.oid, r.rulename, r.ev_class, r.ev_action)::text, E'\\n' ORDER BY r.oid), '')) FROM pg_rewrite r WHERE r.oid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(y.oid, y.typname, y.typnamespace, y.typtype)::text, E'\\n' ORDER BY y.oid), ''))
+     FROM pg_type y JOIN pg_namespace n ON n.oid = y.typnamespace WHERE y.oid >= 16384 AND ${USER_NAMESPACE}),
+  (SELECT md5(coalesce(string_agg(row(s.seqrelid, s.seqtypid, s.seqstart, s.seqincrement, s.seqmax, s.seqmin, s.seqcache, s.seqcycle)::text, E'\\n' ORDER BY s.seqrelid), '')) FROM pg_sequence s WHERE s.seqrelid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(e.oid, e.extname, e.extversion, e.extnamespace)::text, E'\\n' ORDER BY e.oid), '')) FROM pg_extension e),
+  (SELECT md5(coalesce(string_agg(row(u.oid, u.pubname)::text, E'\\n' ORDER BY u.oid), '')) FROM pg_publication u),
+  (SELECT md5(coalesce(string_agg(row(v.oid, v.evtname, v.evtevent, v.evtfoid, v.evtenabled)::text, E'\\n' ORDER BY v.oid), '')) FROM pg_event_trigger v),
+  (SELECT md5(coalesce(string_agg(row(h.inhrelid, h.inhparent, h.inhseqno)::text, E'\\n' ORDER BY h.inhrelid, h.inhparent), '')) FROM pg_inherits h),
+  (SELECT md5(coalesce(string_agg(row(m.oid, m.enumtypid, m.enumlabel, m.enumsortorder)::text, E'\\n' ORDER BY m.oid), '')) FROM pg_enum m),
+  (SELECT md5(coalesce(string_agg(row(q.oid, q.oprname, q.oprnamespace, q.oprleft, q.oprright, q.oprresult, q.oprcode)::text, E'\\n' ORDER BY q.oid), '')) FROM pg_operator q WHERE q.oid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(w.oid, w.castsource, w.casttarget, w.castfunc, w.castcontext, w.castmethod)::text, E'\\n' ORDER BY w.oid), '')) FROM pg_cast w WHERE w.oid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(l.oid, l.collname, l.collnamespace, l.collprovider, l.collisdeterministic, l.collcollate, l.collctype)::text, E'\\n' ORDER BY l.oid), '')) FROM pg_collation l WHERE l.oid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(z.oid, z.stxrelid, z.stxname, z.stxkeys, z.stxkind)::text, E'\\n' ORDER BY z.oid), '')) FROM pg_statistic_ext z WHERE z.oid >= 16384),
+  (SELECT count(*)::text FROM pg_largeobject_metadata),
+  (SELECT md5(coalesce(string_agg(row(x.objoid, x.classoid, x.objsubid, x.description)::text, E'\\n' ORDER BY x.objoid, x.classoid, x.objsubid), '')) FROM pg_description x WHERE x.objoid >= 16384),
+  (SELECT md5(coalesce(string_agg(row(f.oid, f.defaclrole, f.defaclnamespace, f.defaclobjtype, f.defaclacl)::text, E'\\n' ORDER BY f.oid), '')) FROM pg_default_acl f),
+  (SELECT md5(coalesce(string_agg(row(b.setrole, b.setconfig)::text, E'\\n' ORDER BY b.setrole), ''))
+     FROM pg_db_role_setting b WHERE b.setdatabase = (SELECT oid FROM pg_database WHERE datname = current_database())),
+  (SELECT datacl::text FROM pg_database WHERE datname = current_database())
+)) AS digest`
+
+const STORAGE_QUERY = `
+SELECT format('%I.%I', n.nspname, c.relname) AS name, c.relkind::text AS kind,
+       c.relfilenode::text AS filenode, pg_relation_size(c.oid, 'main')::text AS size
+FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind IN ('r', 'm') AND c.oid >= 16384 AND ${USER_NAMESPACE}`
+
+const SEQUENCE_QUERY = `
+SELECT format('%I.%I', schemaname, sequencename) AS name, last_value::text AS last, start_value::text AS start
+FROM pg_sequences WHERE schemaname !~ '^pg_(toast_)?temp_' AND schemaname NOT IN ('information_schema', 'pg_catalog')`
+
+// Tables row-level security applies to for the connected role: not a superuser
+// or BYPASSRLS role, and either not the owner or the owner of a FORCEd table.
+const RLS_QUERY = `
+SELECT format('%I.%I', n.nspname, c.relname) AS name,
+       pg_has_role(current_user, c.relowner, 'USAGE') AS owner
+FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind = 'r' AND c.relrowsecurity AND c.oid >= 16384 AND ${USER_NAMESPACE}
+  AND NOT (SELECT rolsuper OR rolbypassrls FROM pg_roles WHERE rolname = current_user)
+  AND (c.relforcerowsecurity OR NOT pg_has_role(current_user, c.relowner, 'USAGE'))`
+
+type Query = postgres.Sql | postgres.TransactionSql
+
+/**
+ * Tables among `wanted` that RLS hides from this role but that it owns (FORCEd),
+ * and those it does not own, which it cannot read or write at all.
+ */
+async function rlsAccess(q: Query, wanted: ReadonlySet<string>): Promise<{ lift: string[]; hidden: string[] }> {
+  const rows = await q.unsafe<{ name: string; owner: boolean }[]>(RLS_QUERY)
+  const applies = rows.filter(r => wanted.has(r.name))
+  return {
+    lift: applies.filter(r => r.owner).map(r => r.name),
+    hidden: applies.filter(r => !r.owner).map(r => r.name),
+  }
+}
+
+function connect(url: string): postgres.Sql {
+  return postgres(url, { max: 1, onnotice: () => {}, idle_timeout: 0, max_lifetime: 0 })
+}
+
+async function readCopy(sql: Query, table: string): Promise<Buffer> {
+  const stream = await sql.unsafe(`COPY ${table} TO STDOUT`).readable()
+  const chunks: Buffer[] = []
+  for await (const chunk of stream) chunks.push(Buffer.from(chunk as Buffer))
+  return Buffer.concat(chunks)
+}
+
+async function writeCopy(sql: postgres.Sql | postgres.TransactionSql, table: string, data: Buffer): Promise<void> {
+  const sink = await sql.unsafe(`COPY ${table} FROM STDIN`).writable()
+  await new Promise<void>((resolve, reject) => {
+    sink.once('error', reject)
+    sink.once('finish', resolve)
+    sink.end(data)
+  })
+}
+
+/** Run `run` with FORCE ROW LEVEL SECURITY off on `tables` (owned by this role), restored before the transaction commits. */
+async function withForceLifted(sql: postgres.Sql, tables: string[], run: (q: Query) => Promise<void>): Promise<void> {
+  if (tables.length === 0) return run(sql)
+  await sql.begin(async tx => {
+    for (const table of tables) await tx.unsafe(`ALTER TABLE ${table} NO FORCE ROW LEVEL SECURITY`)
+    await run(tx)
+    for (const table of tables) await tx.unsafe(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY`)
+  })
+}
+
+/** Read the state a reset returns to. `url` is a superuser connection to the database. */
+export async function captureBaseline(url: string): Promise<Baseline> {
+  const sql = connect(url)
+  try {
+    const [digestRow] = await sql.unsafe<{ digest: string }[]>(DIGEST_QUERY)
+    const storage = await sql.unsafe<{ name: string; kind: string; filenode: string; size: string }[]>(STORAGE_QUERY)
+    const sizes = new Map<string, number>()
+    const matviews = new Map<string, string>()
+    const stored = new Set<string>()
+    for (const row of storage) {
+      sizes.set(row.name, Number(row.size))
+      if (row.kind === 'm') matviews.set(row.name, row.filenode)
+      else if (Number(row.size) > 0) stored.add(row.name)
+    }
+    // A forced-RLS table the connection owns is read with the force lifted for
+    // this transaction; one it does not own shows no rows, whatever it holds.
+    const { lift, hidden } = await rlsAccess(sql, stored)
+    const rows = new Map<string, Buffer>()
+    await withForceLifted(sql, lift, async q => {
+      for (const table of stored) {
+        if (hidden.includes(table)) continue
+        const [has] = await q.unsafe<{ has: boolean }[]>(`SELECT EXISTS (SELECT 1 FROM ${table}) AS has`)
+        if (has!.has) rows.set(table, await readCopy(q, table))
+      }
+    })
+    const sequences = new Map<string, { last: string | null; start: string }>()
+    for (const row of await sql.unsafe<{ name: string; last: string | null; start: string }[]>(SEQUENCE_QUERY)) {
+      sequences.set(row.name, { last: row.last, start: row.start })
+    }
+    return { digest: digestRow!.digest, sizes, matviews, stored, rows, hidden, sequences }
+  } finally {
+    await sql.end()
+  }
+}
+
+/**
+ * Return the database to its baseline. Call after the file's backends are gone.
+ * Refuses (ok: false) rather than reset a database whose state a reset cannot
+ * undo; nothing is changed in that case.
+ */
+export async function resetDatabase(
+  url: string,
+  baseline: Baseline,
+  superuser = true,
+): Promise<ResetOutcome> {
+  let sql: postgres.Sql | null = null
+  try {
+    sql = connect(url)
+    const [prepared] = await sql.unsafe<{ n: number }[]>(
+      `SELECT count(*)::int AS n FROM pg_prepared_xacts WHERE database = current_database()`,
+    )
+    if (prepared!.n > 0) return { ok: false, reason: 'prepared-xact' }
+    if (baseline.hidden.length > 0) return { ok: false, reason: 'rls' }
+    const [digestRow] = await sql.unsafe<{ digest: string }[]>(DIGEST_QUERY)
+    if (digestRow!.digest !== baseline.digest) return { ok: false, reason: 'digest' }
+
+    const storage = await sql.unsafe<{ name: string; kind: string; filenode: string; size: string }[]>(STORAGE_QUERY)
+    const dirty: string[] = []
+    for (const row of storage) {
+      const base = baseline.sizes.get(row.name)
+      if (base === undefined) return { ok: false, reason: 'digest' }
+      if (row.kind === 'm') {
+        if (Number(row.size) !== base || row.filenode !== baseline.matviews.get(row.name)) {
+          return { ok: false, reason: 'matview' }
+        }
+      } else if (Number(row.size) > base || baseline.stored.has(row.name)) {
+        dirty.push(row.name)
+      }
+    }
+
+    if (dirty.length > 0) {
+      await sql.begin(async tx => {
+        // Superuser: reload without firing triggers or checking FKs. Otherwise
+        // reload plainly, then refuse if a trigger wrote into a table that
+        // should be empty.
+        if (superuser) await tx.unsafe(`SET LOCAL session_replication_role = replica`)
+        await tx.unsafe(`TRUNCATE ${dirty.join(', ')} CASCADE`)
+        // Policies apply to the reload as to any write: lift a forced one on
+        // the tables it fills, as the baseline read did.
+        const { lift } = await rlsAccess(tx, new Set(baseline.rows.keys()))
+        for (const table of lift) await tx.unsafe(`ALTER TABLE ${table} NO FORCE ROW LEVEL SECURITY`)
+        for (const [table, data] of baseline.rows) await writeCopy(tx, table, data)
+        for (const table of lift) await tx.unsafe(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY`)
+        if (!superuser && baseline.rows.size > 0) {
+          for (const row of await tx.unsafe<{ name: string; size: string }[]>(STORAGE_QUERY)) {
+            if (baseline.stored.has(row.name) || baseline.matviews.has(row.name)) continue
+            if (Number(row.size) > (baseline.sizes.get(row.name) ?? 0)) throw new Error(`reload wrote to ${row.name}`)
+          }
+        }
+      })
+    }
+
+    const current = await sql.unsafe<{ name: string; last: string | null }[]>(SEQUENCE_QUERY)
+    const fixes: string[] = []
+    for (const row of current) {
+      const base = baseline.sequences.get(row.name)
+      if (base === undefined) return { ok: false, reason: 'digest' }
+      if (row.last === base.last) continue
+      const literal = `'${row.name.replace(/'/g, "''")}'::regclass`
+      fixes.push(base.last === null
+        ? `setval(${literal}, ${base.start}, false)`
+        : `setval(${literal}, ${base.last}, true)`)
+    }
+    if (fixes.length > 0) await sql.unsafe(`SELECT ${fixes.join(', ')}`)
+
+    return { ok: true, cleared: dirty.length, reloaded: baseline.rows.size }
+  } catch {
+    return { ok: false, reason: 'error' }
+  } finally {
+    if (sql !== null) await sql.end().catch(() => {})
+  }
+}

package/src/test/savepoints.ts

@@ -0,0 +1,172 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type postgres from 'postgres'
+import { PostgresJsTransaction, type PostgresJsDatabase } from '../data/query/postgres-js/index.js'
+import { throughErrorBoundary } from '../data/query/postgres-js/driver-error-boundary.js'
+
+type Handle = PostgresJsDatabase
+
+/**
+ * Makes `db.transaction(fn)` — and `transaction` on the handle `fn` receives,
+ * to any depth — a SAVEPOINT on the transaction the harness already holds on
+ * this connection: `RELEASE` on success, `ROLLBACK TO` and rethrow on error.
+ * Without this, drizzle sends `BEGIN … COMMIT` and the `COMMIT` ends the test's
+ * transaction.
+ *
+ * A savepoint inherits the outer transaction's isolation level, so the
+ * `config` argument is ignored. Settings changed by statements sent from inside
+ * the block (`set_config(..., true)`, `SET LOCAL`) and the role it set are put
+ * back to their values before the savepoint when it releases; statements sent
+ * on the connection from outside the block (another task) are not undone.
+ * Postgres cannot list custom settings (`pipework.*` is not in `pg_settings`),
+ * so the names are taken from the statements this connection sends.
+ *
+ * Returns a function that puts another handle over the same connection on the
+ * same savepoint queue.
+ */
+export function collapseTransactionsToSavepoints(db: PostgresJsDatabase, client: postgres.Sql): (other: PostgresJsDatabase) => void {
+  let counter = 0
+  const known = new Set<string>()
+
+  const unsafe = client.unsafe.bind(client) as (...args: unknown[]) => unknown
+  ;(client as { unsafe: unknown }).unsafe = (query: string, params?: unknown[], ...rest: unknown[]): unknown => {
+    const names = settingNames(query, params ?? [])
+    let owner = inBlock.getStore()
+    while (owner !== undefined && !owner.open) owner = owner.parent
+    for (const name of names) {
+      known.add(name)
+      owner?.touched.add(name)
+    }
+    if (owner !== undefined && ROLE_CHANGE.test(query)) owner.roleTouched = true
+    return unsafe(query, params, ...rest)
+  }
+
+  // One connection runs one savepoint at a time among siblings, as drizzle's
+  // reserved `begin` made concurrent transactions do: Postgres savepoints are
+  // a stack, so releasing one releases those opened after it. Calls made
+  // outside any block queue FIFO on `tail`; calls made from one open block
+  // queue FIFO on that block's own `tail`. A call made inside a savepoint's
+  // scope, on the root db or on a handle alike, nests in that savepoint at
+  // once, or it would wait on the block that is waiting for it. A block
+  // releases only after the savepoints started in it settle; a call made from
+  // its scope after it ended nests in the nearest block still open, or queues
+  // on `tail` when none is.
+  let tail: Promise<unknown> = Promise.resolve()
+  interface Block {
+    open: boolean
+    children: Set<Promise<unknown>>
+    parent: Block | undefined
+    tail: Promise<unknown>
+    touched: Set<string>
+    roleTouched: boolean
+  }
+  const inBlock = new AsyncLocalStorage<Block>()
+
+  // `target` is the handle `fn` receives and its descendants: statements sent
+  // through it travel its session, the savepoint statements always travel `db`'s.
+  const transactionFor = (target: Handle) => <T>(fn: (tx: Handle) => Promise<T>): Promise<T> => {
+    let parent = inBlock.getStore()
+    while (parent !== undefined && !parent.open) parent = parent.parent
+    const run = (): Promise<T> => {
+      const block: Block = { open: true, children: new Set(), parent, tail: Promise.resolve(), touched: new Set(), roleTouched: false }
+      return throughErrorBoundary(client, () => inBlock.run(block, () => runSavepoint(fn, block, target)))
+    }
+    const queued = (parent?.tail ?? tail).then(run)
+    const settled = queued.then(() => undefined, () => undefined)
+    if (parent !== undefined) {
+      parent.tail = settled
+      parent.children.add(settled)
+    } else {
+      tail = settled
+    }
+    return queued
+  }
+
+  const wrap = (target: Handle): void => {
+    ;(target as { transaction: unknown }).transaction = transactionFor(target)
+  }
+
+  const settleChildren = async (block: Block): Promise<void> => {
+    for (let seen = -1; seen !== block.children.size;) {
+      seen = block.children.size
+      await Promise.all([...block.children])
+    }
+    block.open = false
+  }
+
+  // Each of the three steps below is one simple-protocol round trip on the
+  // raw client, so the harness adds no more than two per block.
+  const send = unsafe as (query: string) => Promise<unknown>
+
+  const runSavepoint = async <T>(fn: (tx: Handle) => Promise<T>, block: Block, target: Handle): Promise<T> => {
+    const name = `pw_${++counter}`
+    const before = await openSavepoint(send, name, known)
+    let result: T
+    try {
+      const handle = new PostgresJsTransaction(target.dialect, target.session as never, undefined) as unknown as Handle
+      wrap(handle)
+      result = await fn(handle)
+    } catch (err) {
+      await settleChildren(block)
+      await send(`ROLLBACK TO SAVEPOINT ${name}; RELEASE SAVEPOINT ${name}`)
+      throw err
+    }
+    await settleChildren(block)
+    await send(releaseAndRestore(name, before, block))
+    return result
+  }
+
+  wrap(db)
+  // Another handle over the same connection joins this savepoint queue.
+  return wrap
+}
+
+const ROLE_CHANGE = /^\s*(?:set\s+(?:local\s+|session\s+)?role\b|reset\s+role\b)/i
+
+const SETTING_NAME = /^[A-Za-z_][\w.]*$/
+
+/** Names of the settings a statement changes: `set_config(name, ...)` and `SET [LOCAL] name =`. */
+function settingNames(query: string, params: unknown[]): string[] {
+  const names: string[] = []
+  for (const m of query.matchAll(/set_config\s*\(\s*(?:'([^']+)'|\$(\d+))/gi)) {
+    const name = m[1] ?? params[Number(m[2]) - 1]
+    if (typeof name === 'string' && SETTING_NAME.test(name)) names.push(name)
+  }
+  const set = /^\s*set\s+(?:(?:local|session)\s+)?([A-Za-z_][\w.]*)\s*(?:=|to\b)/i.exec(query)
+  if (set?.[1] !== undefined) names.push(set[1])
+  return names
+}
+
+interface Snapshot {
+  settings: Map<string, string | null>
+  role: string
+}
+
+const literal = (value: string): string => `'${value.replaceAll("'", "''")}'`
+
+/** `SAVEPOINT name` and the snapshot of the known settings and the role, in one query. */
+async function openSavepoint(send: (query: string) => Promise<unknown>, name: string, names: ReadonlySet<string>): Promise<Snapshot> {
+  const settings = names.size === 0
+    ? 'NULL'
+    : `(SELECT jsonb_object_agg(n, current_setting(n, true)) FROM unnest(ARRAY[${[...names].map(literal).join(', ')}]::text[]) AS n)`
+  // postgres.js answers a multi-statement simple query with one result per statement.
+  const results = await send(`SAVEPOINT ${name}; SELECT current_user AS role, ${settings} AS settings`) as Array<Array<Record<string, unknown>>>
+  const row = results[1]?.[0]
+  const values = (row?.['settings'] ?? {}) as Record<string, string | null>
+  return { settings: new Map(Object.entries(values)), role: String(row?.['role']) }
+}
+
+/** `RELEASE SAVEPOINT name`, then every touched setting and a touched role set back, in one query. */
+function releaseAndRestore(
+  name: string,
+  before: Snapshot,
+  block: { touched: ReadonlySet<string>; roleTouched: boolean },
+): string {
+  let query = `RELEASE SAVEPOINT ${name}`
+  if (block.touched.size > 0) {
+    // A setting first seen inside the savepoint was unset before it.
+    const calls = [...block.touched].map(n => `set_config(${literal(n)}, ${literal(before.settings.get(n) ?? '')}, true)`)
+    query += `; SELECT ${calls.join(', ')}`
+  }
+  if (block.roleTouched) query += `; SET LOCAL ROLE "${before.role.replaceAll('"', '""')}"`
+  return query
+}