@crombolo/data 0.0.0-stage → 0.10.0

package/src/change-report.ts

@@ -0,0 +1,166 @@
+/**
+ * Findings, persisted. A run upserts by `(code, subject, property, culture)`
+ * within its own `(source, scope)` and resolves whatever it no longer reports,
+ * so the dashboard shows items disappearing as they are fixed.
+ *
+ * `source` is required rather than defaulted: the sweep resolves what a run
+ * omits, so a caller that forgot to say which findings it owns would silently
+ * resolve somebody else's. `scope` narrows it again — one bundle's findings do
+ * not resolve another's.
+ */
+import type { Db } from './database.ts'
+import { DbDate } from './dialect.ts'
+
+export type FindingKind = 'auto' | 'person' | 'blocking'
+
+/** Who a run of findings belongs to. Scopes the resolve sweep. */
+export type FindingSource = 'upgrade' | 'transfer'
+
+export interface Finding {
+  kind: FindingKind
+  /** Stable machine name: 'mandatory-missing', 'value-conversion', … */
+  code: string
+  subjectType:
+    | 'document'
+    | 'document-type'
+    | 'property'
+    | 'migration'
+    | 'file'
+    | 'data-type'
+    | 'media'
+    | 'element'
+    | 'bundle'
+    | 'dictionary-item'
+  subjectKey: string
+  subjectName: string
+  propertyAlias: string | null
+  culture: string | null
+  message: string
+  /** A backoffice URL, when the subject has one. */
+  link: string | null
+}
+
+export interface ReportedFinding extends Finding {
+  id: number
+  runId: string
+  source: FindingSource
+  /** What within the source these findings are about: a bundle id, or null for an upgrade. */
+  scope: string | null
+  status: 'open' | 'resolved'
+  firstSeen: Date
+  lastSeen: Date
+  resolvedAt: Date | null
+}
+
+export interface WriteReportOptions {
+  source: FindingSource
+  scope?: string | null
+  runId?: string
+}
+
+export interface ReadReportOptions {
+  includeResolved?: boolean
+  source?: FindingSource
+  scope?: string | null
+}
+
+const identity = (f: Finding) =>
+  `${f.code}|${f.subjectKey}|${f.propertyAlias ?? ''}|${f.culture ?? ''}`
+
+/** Records a run: new findings inserted, seen ones refreshed, absent ones resolved. Returns the run id. */
+export async function writeReport(
+  db: Db,
+  findings: readonly Finding[],
+  options: WriteReportOptions,
+): Promise<string> {
+  const { source } = options
+  const scope = options.scope ?? null
+  const runId = options.runId ?? crypto.randomUUID()
+  const now = DbDate.toDb(new Date())
+  const open = await readReport(db, { source, scope })
+  const openByIdentity = new Map(open.map((f) => [identity(f), f]))
+  const seen = new Set<string>()
+  for (const finding of findings) {
+    const key = identity(finding)
+    seen.add(key)
+    const existing = openByIdentity.get(key)
+    if (existing) {
+      await db.exec(
+        'UPDATE change_report SET run_id = ?, kind = ?, subject_name = ?, message = ?, link = ?, last_seen = ? WHERE id = ?',
+        [runId, finding.kind, finding.subjectName, finding.message, finding.link, now, existing.id],
+      )
+    } else {
+      await db.exec(
+        `INSERT INTO change_report (run_id, source, scope, kind, code, subject_type, subject_key, subject_name, property_alias, culture, message, link, status, first_seen, last_seen)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'open', ?, ?)`,
+        [
+          runId,
+          source,
+          scope,
+          finding.kind,
+          finding.code,
+          finding.subjectType,
+          finding.subjectKey,
+          finding.subjectName,
+          finding.propertyAlias,
+          finding.culture,
+          finding.message,
+          finding.link,
+          now,
+          now,
+        ],
+      )
+    }
+  }
+  for (const [key, existing] of openByIdentity) {
+    if (seen.has(key)) continue
+    await db.exec("UPDATE change_report SET status = 'resolved', resolved_at = ? WHERE id = ?", [
+      now,
+      existing.id,
+    ])
+  }
+  return runId
+}
+
+export async function readReport(
+  db: Db,
+  options: ReadReportOptions = {},
+): Promise<ReportedFinding[]> {
+  const where: string[] = []
+  const params: unknown[] = []
+  if (!options.includeResolved) where.push("status = 'open'")
+  if (options.source !== undefined) {
+    where.push('source = ?')
+    params.push(options.source)
+  }
+  // `scope` is meaningful when null, so only an explicit key filters.
+  if ('scope' in options) {
+    const scope = options.scope ?? null
+    where.push(scope === null ? 'scope IS NULL' : 'scope = ?')
+    if (scope !== null) params.push(scope)
+  }
+  const rows = await db.query(
+    `SELECT id, run_id, source, scope, kind, code, subject_type, subject_key, subject_name, property_alias, culture, message, link, status, first_seen, last_seen, resolved_at
+     FROM change_report ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY id`,
+    params,
+  )
+  return rows.map((row) => ({
+    id: Number(row.id),
+    runId: String(row.run_id),
+    source: String(row.source) as FindingSource,
+    scope: (row.scope as string | null) ?? null,
+    kind: String(row.kind) as FindingKind,
+    code: String(row.code),
+    subjectType: String(row.subject_type) as Finding['subjectType'],
+    subjectKey: String(row.subject_key),
+    subjectName: String(row.subject_name ?? ''),
+    propertyAlias: (row.property_alias as string | null) ?? null,
+    culture: (row.culture as string | null) ?? null,
+    message: String(row.message),
+    link: (row.link as string | null) ?? null,
+    status: String(row.status) as 'open' | 'resolved',
+    firstSeen: DbDate.fromDb(row.first_seen) ?? new Date(0),
+    lastSeen: DbDate.fromDb(row.last_seen) ?? new Date(0),
+    resolvedAt: DbDate.fromDb(row.resolved_at) ?? null,
+  }))
+}

package/src/cluster.ts

@@ -0,0 +1,108 @@
+/**
+ * Multi-node plumbing: node identity in `server`, and the polled
+ * `cache_instruction` table that tells other nodes what changed.
+ * docs/schema-as-code.md, "Cache coherence".
+ */
+import type { Db } from './database.ts'
+import { DbDate } from './dialect.ts'
+
+/**
+ * `views` is a code change, not a data one: a template was written, so every
+ * node has to look at its views tree again. The other two invalidate the
+ * published cache; this one makes a node take a new snapshot.
+ */
+export type CacheInstructionKind = 'schema' | 'content' | 'components'
+
+export interface CacheInstruction {
+  id: number
+  kind: CacheInstructionKind
+  payload: Record<string, unknown>
+  createdBy: string | null
+}
+
+export async function appendCacheInstruction(
+  db: Db,
+  instruction: { kind: CacheInstructionKind; payload?: Record<string, unknown>; by?: string },
+): Promise<void> {
+  await db.exec(
+    'INSERT INTO cache_instruction (kind, payload, created_at, created_by) VALUES (?, ?, ?, ?)',
+    [
+      instruction.kind,
+      JSON.stringify(instruction.payload ?? {}),
+      DbDate.toDb(new Date()),
+      instruction.by ?? null,
+    ],
+  )
+}
+
+/** The highest instruction id, so a fresh node ignores history. */
+export async function latestCacheInstructionId(db: Db): Promise<number> {
+  const rows = await db.query<{ n: number | null }>('SELECT MAX(id) AS n FROM cache_instruction')
+  return Number(rows[0]?.n ?? 0)
+}
+
+export async function cacheInstructionsAfter(db: Db, afterId: number): Promise<CacheInstruction[]> {
+  const rows = await db.query(
+    'SELECT id, kind, payload, created_by FROM cache_instruction WHERE id > ? ORDER BY id',
+    [afterId],
+  )
+  return rows.map((row) => ({
+    id: Number(row.id),
+    kind: String(row.kind) as CacheInstructionKind,
+    payload: row.payload ? (JSON.parse(String(row.payload)) as Record<string, unknown>) : {},
+    createdBy: (row.created_by as string | null) ?? null,
+  }))
+}
+
+export interface ServerIdentity {
+  nodeId: string
+  version: string
+  revision: string
+  /** `all`, `api` or `web`: what this node serves, so the cluster can be read back by role. */
+  role?: 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 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],
+    )
+  } else {
+    await db.exec(
+      'INSERT INTO server (node_id, version, revision, role, last_seen) VALUES (?, ?, ?, ?, ?)',
+      [identity.nodeId, identity.version, identity.revision, role, now],
+    )
+  }
+}
+
+export interface LiveNode {
+  nodeId: string
+  /** Null for a row written before roles were recorded. */
+  role: string | null
+  version: string | null
+  revision: 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',
+    [DbDate.toDb(new Date(Date.now() - options.seenWithinMs))],
+  )
+  return rows.map((row) => ({
+    nodeId: String(row.node_id),
+    role: (row.role as string | null) ?? null,
+    version: (row.version as string | null) ?? null,
+    revision: (row.revision as string | null) ?? null,
+    lastSeen: DbDate.fromDb(row.last_seen) as Date,
+  }))
+}

package/src/database.ts

@@ -0,0 +1,121 @@
+/** Driver-agnostic database handle. */
+import { Database as BunSqlite } from 'bun:sqlite'
+import { type Dialect, type DialectName, dialectFor } from './dialect.ts'
+import { createLockManager, type LockManager } from './locks.ts'
+
+export interface Db {
+  readonly dialect: Dialect
+  readonly locks: LockManager
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>
+  exec(sql: string, params?: unknown[]): Promise<void>
+  transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T>
+  close(): Promise<void>
+}
+
+export interface ConnectOptions {
+  dialect?: DialectName
+  /** Postgres connection pool size. */
+  poolSize?: number
+  /** SQLite file path, or ':memory:'. Ignored for Postgres. */
+  file?: string
+  /** Postgres connection string. Ignored for SQLite. */
+  url?: string
+}
+
+class SqliteDb implements Db {
+  readonly dialect = dialectFor('sqlite')
+  readonly locks: LockManager
+  #db: BunSqlite
+  #inTransaction: boolean
+
+  constructor(db: BunSqlite, locks?: LockManager, inTransaction = false) {
+    this.#db = db
+    this.locks = locks ?? createLockManager(this)
+    this.#inTransaction = inTransaction
+  }
+
+  async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {
+    return this.#db.query(this.dialect.render(sql)).all(...(params as never[])) as T[]
+  }
+
+  async exec(sql: string, params: unknown[] = []): Promise<void> {
+    this.#db.query(this.dialect.render(sql)).run(...(params as never[]))
+  }
+
+  async transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T> {
+    if (this.#inTransaction) return fn(this)
+    this.#db.exec('BEGIN')
+    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
+    }
+  }
+
+  async close(): Promise<void> {
+    this.#db.close()
+  }
+}
+
+interface SqlTag {
+  unsafe(sql: string, params?: unknown[]): Promise<unknown>
+  begin<T>(fn: (tx: SqlTag) => Promise<T>): Promise<T>
+  close(): Promise<void>
+}
+
+class PostgresDb implements Db {
+  readonly dialect = dialectFor('postgres')
+  readonly locks: LockManager
+  #sql: SqlTag
+  #inTransaction: boolean
+
+  constructor(sql: SqlTag, locks?: LockManager, inTransaction = false) {
+    this.#sql = sql
+    this.locks = locks ?? createLockManager(this)
+    this.#inTransaction = inTransaction
+  }
+
+  async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {
+    return (await this.#sql.unsafe(this.dialect.render(sql), params)) as T[]
+  }
+
+  async exec(sql: string, params: unknown[] = []): Promise<void> {
+    await this.#sql.unsafe(this.dialect.render(sql), params)
+  }
+
+  /** Nested calls join the enclosing transaction, as they do on SQLite. */
+  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)))
+  }
+
+  async close(): Promise<void> {
+    await this.#sql.close()
+  }
+}
+
+export function resolveDialectName(options: ConnectOptions = {}): DialectName {
+  return options.dialect ?? (Bun.env.CROMBOLO_DB as DialectName | undefined) ?? 'sqlite'
+}
+
+export async function connect(options: ConnectOptions = {}): Promise<Db> {
+  if (resolveDialectName(options) === 'postgres') {
+    const url = options.url ?? Bun.env.CROMBOLO_POSTGRES_URL ?? Bun.env.DATABASE_URL
+    if (!url) throw new Error('Postgres selected but no connection string was provided.')
+    const { SQL } = await import('bun')
+    // 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)
+    await db.exec('CREATE EXTENSION IF NOT EXISTS citext')
+    return db
+  }
+  const sqlite = new BunSqlite(options.file ?? ':memory:', { create: true })
+  sqlite.exec('PRAGMA journal_mode = WAL')
+  sqlite.exec('PRAGMA foreign_keys = ON')
+  sqlite.exec('PRAGMA busy_timeout = 5000')
+  return new SqliteDb(sqlite)
+}

package/src/dialect.ts

@@ -0,0 +1,136 @@
+/**
+ * The single seam between the services and SQL. Queries are written once with
+ * `?` placeholders and rendered per dialect, so no service ever needs to know
+ * which database it is talking to.
+ */
+export type DialectName = 'sqlite' | 'postgres'
+
+export interface ColumnTypes {
+  identity: string
+  integer: string
+  bigint: string
+  boolean: string
+  uuid: string
+  /** Case-insensitive text. Umbraco compares aliases and logins case-insensitively. */
+  textCi: string
+  text: string
+  varchar: (n: number) => string
+  /** A varchar that compares case-sensitively on both dialects, as a bundle's tables do. */
+  varcharExact: (n: number) => string
+  /** JSON, held as text and parsed by whoever reads it. */
+  json: string
+  timestamp: string
+  numeric: string
+  blob: string
+}
+
+export interface Dialect {
+  readonly name: DialectName
+  readonly types: ColumnTypes
+  placeholder(index: number): string
+  quote(identifier: string): string
+  /** Rewrites `?` placeholders into the dialect's own form. */
+  render(sql: string): string
+  now(): string
+  boolValue(value: boolean): unknown
+  /** Appended to a SELECT that must block a concurrent state change; empty where the engine is single-writer. */
+  readonly forShare: string
+  readonly forUpdate: string
+  /**
+   * SQL that moves a table's identity past rows inserted with explicit ids, or
+   * undefined where the engine does that itself.
+   */
+  syncIdentity(table: string): string | undefined
+}
+
+const RESERVED_RENDER = /\?/g
+
+export const sqliteDialect: Dialect = {
+  name: 'sqlite',
+  types: {
+    identity: 'INTEGER PRIMARY KEY AUTOINCREMENT',
+    integer: 'INTEGER',
+    bigint: 'INTEGER',
+    boolean: 'INTEGER',
+    uuid: 'TEXT',
+    // COLLATE NOCASE is how Umbraco gets case-insensitive aliases on SQLite.
+    textCi: 'TEXT COLLATE NOCASE',
+    text: 'TEXT',
+    varchar: (n) => `VARCHAR(${n}) COLLATE NOCASE`,
+    varcharExact: (n) => `VARCHAR(${n})`,
+    json: 'TEXT',
+    timestamp: 'TEXT',
+    // REAL would be lossy for decimal property values.
+    numeric: 'TEXT',
+    blob: 'BLOB',
+  },
+  placeholder: () => '?',
+  quote: (id) => `"${id.replaceAll('"', '""')}"`,
+  render: (sql) => sql,
+  now: () => "strftime('%Y-%m-%dT%H:%M:%fZ','now')",
+  boolValue: (value) => (value ? 1 : 0),
+  forShare: '',
+  forUpdate: '',
+  syncIdentity: () => undefined,
+}
+
+export const postgresDialect: Dialect = {
+  name: 'postgres',
+  types: {
+    identity: 'INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY',
+    integer: 'INTEGER',
+    bigint: 'BIGINT',
+    boolean: 'BOOLEAN',
+    uuid: 'UUID',
+    // Postgres collates case-sensitively by default; citext restores Umbraco's semantics.
+    textCi: 'CITEXT',
+    text: 'TEXT',
+    varchar: (n) => `VARCHAR(${n})`,
+    varcharExact: (n) => `VARCHAR(${n})`,
+    json: 'TEXT',
+    timestamp: 'TIMESTAMPTZ',
+    numeric: 'NUMERIC',
+    blob: 'BYTEA',
+  },
+  placeholder: (index) => `$${index}`,
+  quote: (id) => `"${id.replaceAll('"', '""')}"`,
+  render(sql) {
+    let i = 0
+    return sql.replace(RESERVED_RENDER, () => `$${++i}`)
+  },
+  now: () => 'now()',
+  boolValue: (value) => value,
+  forShare: 'FOR SHARE',
+  forUpdate: 'FOR UPDATE',
+  syncIdentity: (table) =>
+    `SELECT setval(pg_get_serial_sequence('${table}', 'id'), (SELECT COALESCE(MAX(id), 1) FROM ${table}))`,
+}
+
+export function dialectFor(name: DialectName): Dialect {
+  return name === 'sqlite' ? sqliteDialect : postgresDialect
+}
+
+/**
+ * Timestamps are written as ISO strings in both dialects — SQLite stores TEXT,
+ * and Postgres parses ISO into timestamptz — but they read back differently
+ * (string vs Date), so every read goes through `fromDb`.
+ */
+export const DbDate = {
+  toDb(value: Date): string {
+    return value.toISOString()
+  },
+  fromDb(value: unknown): Date | undefined {
+    if (value === null || value === undefined) return undefined
+    if (value instanceof Date) return value
+    if (typeof value === 'string') {
+      const parsed = new Date(value)
+      return Number.isNaN(parsed.getTime()) ? undefined : parsed
+    }
+    return undefined
+  },
+}
+
+/** SQLite has no boolean type, so a 0/1 integer comes back for one dialect only. */
+export function fromDbBool(value: unknown): boolean {
+  return value === true || value === 1 || value === '1' || value === 't'
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+export * from './bundle-tables/index.ts'
+export * from './change-report.ts'
+export * from './cluster.ts'
+export * from './database.ts'
+export * from './dialect.ts'
+export * from './locks.ts'
+export * from './maintenance.ts'
+export * from './migrations.ts'
+export * from './node-ref.ts'
+export * from './pending.ts'
+export * from './repositories/bundles.ts'
+export * from './repositories/content-types.ts'
+export * from './repositories/data-types.ts'
+export * from './repositories/dictionary.ts'
+export * from './repositories/documents.ts'
+export * from './repositories/domains.ts'
+export * from './repositories/folders.ts'
+export * from './repositories/form-entries.ts'
+export * from './repositories/form-workflows.ts'
+export * from './repositories/languages.ts'
+export * from './repositories/log-searches.ts'
+export * from './repositories/members.ts'
+export * from './repositories/nodes.ts'
+export * from './repositories/notifications.ts'
+export * from './repositories/public-access.ts'
+export * from './repositories/redirects.ts'
+export * from './repositories/references.ts'
+export * from './repositories/tags.ts'
+export * from './repositories/templates.ts'
+export * from './repositories/transfer-runs.ts'
+export * from './repositories/user-data.ts'
+export * from './repositories/users.ts'
+export * from './schema/assistant.ts'
+export * from './schema/built-in-content-types.ts'
+export * from './schema/built-in-media-types.ts'
+export * from './schema/built-in-member-types.ts'
+export * from './schema/bundle-package.ts'
+export * from './schema/bundles-rename.ts'
+export * from './schema/change-report.ts'
+export * from './schema/client-id-prefix.ts'
+export * from './schema/content.ts'
+export * from './schema/content-seed.ts'
+export * from './schema/created-packages.ts'
+export * from './schema/elements.ts'
+export * from './schema/form-permission-prefix.ts'
+export * from './schema/group-permissions.ts'
+export * from './schema/identity.ts'
+export * from './schema/log-viewer.ts'
+export * from './schema/member-property-type.ts'
+export * from './schema/members.ts'
+export * from './schema/plan.ts'
+export * from './schema/public-access.ts'
+export * from './schema/recycle-bin.ts'
+export * from './schema/rich-text-ui.ts'
+export * from './schema/seed.ts'
+export * from './schema/since-version.ts'
+export * from './schema/transfer-run-package.ts'
+export * from './schema/transfer-runs.ts'
+export * from './schema/upgrade-report.ts'
+export * from './schema/users-localisation.ts'
+export * from './schema/values.ts'
+export * from './schema-ops.ts'
+export * from './schema-state.ts'

package/src/locks.ts

@@ -0,0 +1,103 @@
+/**
+ * Named write locks around content-tree mutation. Umbraco takes a row lock per
+ * lock id; SQLite has a single writer, so an in-process queue is both sufficient
+ * and necessary, while Postgres uses advisory locks.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { Db } from './database.ts'
+
+/** Mirrors Umbraco's Constants.Locks. */
+export const Locks = {
+  Servers: -331,
+  ContentTypes: -332,
+  ContentTree: -333,
+  MediaTree: -334,
+  MemberTree: -335,
+  MediaTypes: -336,
+  MemberTypes: -337,
+  Domains: -338,
+  KeyValues: -339,
+  Languages: -340,
+  ScheduledPublishing: -341,
+  /** Ours: schema sync and schema-state transitions. */
+  Schema: -342,
+} as const
+
+export type LockId = (typeof Locks)[keyof typeof Locks]
+
+export interface LockManager {
+  /** Runs `fn` while holding the named lock. Re-entrant within one chain. */
+  withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T>
+}
+
+/**
+ * The locks the current async chain holds. A holder is emptied on release, so
+ * work the holder left running in the background does not inherit the lock.
+ */
+const held = new AsyncLocalStorage<Set<LockId>>()
+
+/** Runs `fn` directly when this chain already holds `id`; otherwise takes it. */
+async function reentrant<T>(
+  id: LockId,
+  fn: () => Promise<T>,
+  acquire: (run: () => Promise<T>) => Promise<T>,
+): Promise<T> {
+  const current = held.getStore()
+  if (current?.has(id)) return fn()
+  return acquire(async () => {
+    const holding = new Set(current)
+    holding.add(id)
+    try {
+      return await held.run(holding, fn)
+    } finally {
+      holding.clear()
+    }
+  })
+}
+
+class SqliteLockManager implements LockManager {
+  #queues = new Map<number, Promise<unknown>>()
+
+  withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
+    return reentrant(id, fn, (run) => this.#acquire(id, run))
+  }
+
+  async #acquire<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
+    const previous = this.#queues.get(id) ?? Promise.resolve()
+    let release!: () => void
+    const gate = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    this.#queues.set(
+      id,
+      previous.then(() => gate),
+    )
+    await previous
+    try {
+      return await fn()
+    } finally {
+      release()
+      if (this.#queues.get(id) === gate) this.#queues.delete(id)
+    }
+  }
+}
+
+class PostgresLockManager implements LockManager {
+  #db: Db
+  constructor(db: Db) {
+    this.#db = db
+  }
+
+  withLock<T>(id: LockId, fn: () => Promise<T>): Promise<T> {
+    return reentrant(id, fn, (run) =>
+      this.#db.transaction(async (tx) => {
+        await tx.exec('SELECT pg_advisory_xact_lock(?)', [id])
+        return run()
+      }),
+    )
+  }
+}
+
+export function createLockManager(db: Db): LockManager {
+  return db.dialect.name === 'postgres' ? new PostgresLockManager(db) : new SqliteLockManager()
+}