@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

package/src/db/queries/event-consumer.ts

@@ -0,0 +1,170 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+/** Serialise against consumer-bootstrap INSERTs during event retention prune. */
+export async function lockEventConsumersShareMode(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe(`LOCK TABLE "kumiko_event_consumers" IN SHARE MODE`);
+}
+
+export async function insertConsumerIfAbsent(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "status") VALUES ($1, $2, 'idle')
+     ON CONFLICT ("name", "instance_id") DO NOTHING`,
+    [name, instanceId],
+  );
+}
+
+export async function selectConsumerForUpdateSkipLocked(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE SKIP LOCKED`,
+    [name, instanceId],
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
+}
+
+export async function markConsumerProcessing(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET "status" = 'processing', "updated_at" = now()
+     WHERE "name" = $1 AND "instance_id" = $2`,
+    [name, instanceId],
+  );
+}
+
+export type ConsumerDeliveryOutcome = {
+  readonly cursor: bigint;
+  readonly attempts: number;
+  readonly lastError: string | null;
+  readonly deadLettered: boolean;
+};
+
+export async function updateConsumerDeliveryOutcome(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+  outcome: ConsumerDeliveryOutcome,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET
+       "last_processed_event_id" = $1,
+       "attempts" = $2,
+       "status" = $3,
+       "last_error" = $4,
+       "updated_at" = now()
+     WHERE "name" = $5 AND "instance_id" = $6`,
+    [
+      outcome.cursor,
+      outcome.attempts,
+      outcome.deadLettered ? "dead" : "idle",
+      outcome.lastError,
+      name,
+      instanceId,
+    ],
+  );
+}
+
+export async function updateConsumerStatusReturning(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+  status: "idle" | "disabled",
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET "status" = $1, "attempts" = 0, "last_error" = NULL, "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3
+     RETURNING *`,
+    [status, name, instanceId],
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
+}
+
+export async function advanceConsumerPastEventReturning(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+  eventId: bigint,
+): Promise<Record<string, unknown> | undefined> {
+  const rows = (await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET
+       "last_processed_event_id" = $1,
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3
+     RETURNING *`,
+    [eventId, name, instanceId],
+  )) as ReadonlyArray<Record<string, unknown>>;
+  return rows[0];
+}
+
+export async function resetConsumerForMspRebuild(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "last_processed_event_id", "status")
+     VALUES ($1, $2, 0, 'idle')
+     ON CONFLICT ("name", "instance_id") DO UPDATE SET
+       "last_processed_event_id" = 0,
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "updated_at" = now()`,
+    [name, instanceId],
+  );
+}
+
+export async function selectConsumerForUpdate(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE`,
+    [name, instanceId],
+  );
+}
+
+export async function updateConsumerRebuildCursor(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+  lastProcessedEventId: bigint,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET
+       "last_processed_event_id" = $1,
+       "status" = 'idle',
+       "attempts" = 0,
+       "last_error" = NULL,
+       "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3`,
+    [lastProcessedEventId, name, instanceId],
+  );
+}
+
+export async function markConsumerRebuildFailed(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+  errorMessage: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET "status" = 'dead', "last_error" = $1, "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3`,
+    [errorMessage, name, instanceId],
+  );
+}

package/src/db/queries/event-store-admin.ts

@@ -0,0 +1,127 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+export type RawFirstEventInsertParams = {
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly tenantId: string;
+  readonly newVersion: number;
+  readonly type: string;
+  readonly eventVersion: number;
+  readonly payloadJson: string;
+  readonly metadataJson: string;
+  readonly createdAt: string;
+  readonly createdBy: string;
+};
+
+export async function insertRawFirstEvent(
+  db: AnyDb,
+  params: RawFirstEventInsertParams,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_events" (
+       aggregate_id, aggregate_type, tenant_id, version,
+       type, event_version, payload, metadata, created_at, created_by
+     )
+     VALUES ($1::uuid, $2, $3::uuid, $4, $5, $6, $7::jsonb, $8::jsonb, $9::timestamptz, $10)`,
+    [
+      params.aggregateId,
+      params.aggregateType,
+      params.tenantId,
+      params.newVersion,
+      params.type,
+      params.eventVersion,
+      params.payloadJson,
+      params.metadataJson,
+      params.createdAt,
+      params.createdBy,
+    ],
+  );
+}
+
+export type RawSubsequentEventInsertParams = RawFirstEventInsertParams & {
+  readonly expectedVersion: number;
+};
+
+export async function insertRawSubsequentEvent(
+  db: AnyDb,
+  params: RawSubsequentEventInsertParams,
+): Promise<boolean> {
+  const rows = (await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_events" (
+       aggregate_id, aggregate_type, tenant_id, version,
+       type, event_version, payload, metadata, created_at, created_by
+     )
+     SELECT $1::uuid, $2, $3::uuid, $4, $5, $6, $7::jsonb, $8::jsonb, $9::timestamptz, $10
+     WHERE EXISTS (
+       SELECT 1 FROM "kumiko_events"
+       WHERE aggregate_id = $1::uuid
+         AND version = $11
+         AND tenant_id = $3::uuid
+     )
+     RETURNING id`,
+    [
+      params.aggregateId,
+      params.aggregateType,
+      params.tenantId,
+      params.newVersion,
+      params.type,
+      params.eventVersion,
+      params.payloadJson,
+      params.metadataJson,
+      params.createdAt,
+      params.createdBy,
+      params.expectedVersion,
+    ],
+  )) as ReadonlyArray<{ id: string }>;
+  return rows.length > 0;
+}
+
+export async function insertRawEventBatch(
+  db: AnyDb,
+  sqlValues: string,
+  params: unknown[],
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_events" (
+       aggregate_id, aggregate_type, tenant_id, version,
+       type, event_version, payload, metadata, created_at, created_by
+     )
+     VALUES ${sqlValues}`,
+    params,
+  );
+}
+
+export async function eventPredecessorExists(
+  db: AnyDb,
+  aggregateId: string,
+  tenantId: string,
+  version: number,
+): Promise<boolean> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT EXISTS(
+       SELECT 1 FROM "kumiko_events"
+       WHERE aggregate_id = $1::uuid
+         AND tenant_id = $2::uuid
+         AND version = $3
+     ) AS present`,
+    [aggregateId, tenantId, version],
+  )) as ReadonlyArray<{ present: boolean }>;
+  return rows[0]?.present === true;
+}
+
+export async function findExistingEventVersion(
+  db: AnyDb,
+  sqlInClause: string,
+  params: unknown[],
+): Promise<{ aggregateId: string; version: number } | undefined> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT aggregate_id, version FROM "kumiko_events"
+     WHERE (tenant_id, aggregate_id, version) IN (${sqlInClause})
+     LIMIT 1`,
+    params,
+  )) as ReadonlyArray<{ aggregate_id: string; version: number }>;
+  const row = rows[0];
+  if (!row) return undefined;
+  return { aggregateId: row.aggregate_id, version: row.version };
+}

package/src/db/queries/event-store.ts

@@ -0,0 +1,155 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+/** NOTIFY on commit — wakes LISTEN subscribers (event-dispatcher). */
+export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void> {
+  await asRawClient(db).unsafe(`SELECT pg_notify($1, '')`, [channel]);
+}
+
+export type SubsequentEventInsertParams = {
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly tenantId: string;
+  readonly newVersion: number;
+  readonly type: string;
+  readonly eventVersion: number;
+  readonly payloadJson: string;
+  readonly metadataJson: string;
+  readonly createdBy: string;
+  readonly expectedVersion: number;
+};
+
+export type SubsequentEventInsertRow = {
+  readonly id: string | bigint;
+  readonly created_at: Date | string;
+};
+
+/** INSERT … SELECT … WHERE EXISTS predecessor — stays raw (typed builder can't express this). */
+export async function insertSubsequentEventRow(
+  db: AnyDb,
+  params: SubsequentEventInsertParams,
+): Promise<SubsequentEventInsertRow | undefined> {
+  const rows = (await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_events" (
+       aggregate_id, aggregate_type, tenant_id, version,
+       type, event_version, payload, metadata, created_by
+     )
+     SELECT $1::uuid, $2, $3::uuid, $4,
+            $5, $6, $7::jsonb,
+            $8::jsonb, $9
+     WHERE EXISTS (
+       SELECT 1 FROM "kumiko_events"
+       WHERE aggregate_id = $1::uuid
+         AND version = $10
+         AND tenant_id = $3::uuid
+     )
+     RETURNING id, created_at`,
+    [
+      params.aggregateId,
+      params.aggregateType,
+      params.tenantId,
+      params.newVersion,
+      params.type,
+      params.eventVersion,
+      params.payloadJson,
+      params.metadataJson,
+      params.createdBy,
+      params.expectedVersion,
+    ],
+  )) as ReadonlyArray<SubsequentEventInsertRow>;
+  return rows[0];
+}
+
+export async function selectStreamMaxVersion(
+  db: AnyDb,
+  aggregateId: string,
+  tenantId: string,
+): Promise<number> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "tenant_id" = $2`,
+    [aggregateId, tenantId],
+  )) as ReadonlyArray<{ v: number | null }>;
+  return rows[0]?.v ?? 0;
+}
+
+/** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
+export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string): Promise<number> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`,
+    [aggregateId],
+  )) as ReadonlyArray<{ v: number | null }>;
+  return rows[0]?.v ?? 0;
+}
+
+export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,
+  )) as ReadonlyArray<{ max: bigint | string | number | null }>;
+  const raw = rows[0]?.max;
+  if (typeof raw === "bigint") return raw;
+  if (raw === null || raw === undefined) return 0n;
+  return BigInt(raw);
+}
+
+/** Head event id for lag metrics — same aggregate as selectEventsHighWaterMark. */
+export async function selectEventsHeadId(db: AnyDb): Promise<bigint> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT COALESCE(MAX(id), 0)::bigint AS head FROM kumiko_events`,
+  )) as ReadonlyArray<{ head?: bigint | string | null }>;
+  const raw = rows[0]?.head;
+  if (typeof raw === "bigint") return raw;
+  return BigInt(raw ?? 0);
+}
+
+export async function selectNextEventIdAfter(db: AnyDb, afterId: bigint): Promise<bigint | null> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT "id" FROM "kumiko_events" WHERE "id" > $1 ORDER BY "id" ASC LIMIT 1`,
+    [afterId],
+  )) as ReadonlyArray<{ id: string | bigint }>;
+  const row = rows[0];
+  if (!row) return null;
+  return typeof row.id === "bigint" ? row.id : BigInt(row.id);
+}
+
+export type SaveSnapshotParams = {
+  readonly aggregateId: string;
+  readonly tenantId: string;
+  readonly aggregateType: string;
+  readonly version: number;
+  readonly stateJson: string;
+};
+
+export async function upsertSnapshot(db: AnyDb, params: SaveSnapshotParams): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_snapshots"
+       ("aggregate_id", "tenant_id", "aggregate_type", "version", "state")
+     VALUES ($1, $2, $3, $4, $5::jsonb)
+     ON CONFLICT ("aggregate_id", "version") DO UPDATE SET
+       "state" = $5::jsonb,
+       "aggregate_type" = $3,
+       "created_at" = now()`,
+    [params.aggregateId, params.tenantId, params.aggregateType, params.version, params.stateJson],
+  );
+}
+
+export type ArchiveStreamParams = {
+  readonly tenantId: string;
+  readonly aggregateId: string;
+  readonly aggregateType: string;
+  readonly archivedBy: string;
+  readonly reason: string | null;
+};
+
+export async function upsertArchivedStream(db: AnyDb, params: ArchiveStreamParams): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_archived_streams"
+       ("tenant_id", "aggregate_id", "aggregate_type", "archived_by", "reason")
+     VALUES ($1, $2, $3, $4, $5)
+     ON CONFLICT ("tenant_id", "aggregate_id") DO UPDATE SET
+       "archived_at" = now(),
+       "archived_by" = $4,
+       "aggregate_type" = $3,
+       "reason" = $5`,
+    [params.tenantId, params.aggregateId, params.aggregateType, params.archivedBy, params.reason],
+  );
+}

package/src/db/queries/projection-rebuild.ts

@@ -0,0 +1,59 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+export async function markProjectionRebuilding(db: AnyDb, projectionName: string): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_projections" ("name", "status") VALUES ($1, 'rebuilding')
+     ON CONFLICT ("name") DO UPDATE SET
+       "status" = 'rebuilding',
+       "last_error" = NULL,
+       "updated_at" = now()`,
+    [projectionName],
+  );
+}
+
+export async function selectEventsForProjectionRebuild(
+  db: AnyDb,
+  aggregateTypes: readonly string[],
+  eventTypes: readonly string[],
+): Promise<ReadonlyArray<Record<string, unknown>>> {
+  return (await asRawClient(db).unsafe(
+    `SELECT * FROM "kumiko_events"
+     WHERE "aggregate_type" = ANY($1::text[])
+       AND "type" = ANY($2::text[])
+     ORDER BY "id" ASC`,
+    [aggregateTypes, eventTypes],
+  )) as ReadonlyArray<Record<string, unknown>>;
+}
+
+export async function finalizeProjectionRebuild(
+  db: AnyDb,
+  projectionName: string,
+  lastProcessedEventId: bigint,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_projections" SET
+       "last_processed_event_id" = $1,
+       "status" = 'idle',
+       "last_rebuild_at" = now(),
+       "last_error" = NULL,
+       "updated_at" = now()
+     WHERE "name" = $2`,
+    [lastProcessedEventId, projectionName],
+  );
+}
+
+export async function markProjectionRebuildFailed(
+  db: AnyDb,
+  projectionName: string,
+  errorMessage: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `INSERT INTO "kumiko_projections" ("name", "status", "last_error") VALUES ($1, 'failed', $2)
+     ON CONFLICT ("name") DO UPDATE SET
+       "status" = 'failed',
+       "last_error" = $2,
+       "updated_at" = now()`,
+    [projectionName, errorMessage],
+  );
+}

package/src/db/queries/raw-sql.ts

@@ -0,0 +1,15 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+/** Escape hatch for caller-built SQL (ownership clauses, entity list queries). */
+export async function executeRawQuery<T = Record<string, unknown>>(
+  db: AnyDb,
+  sqlText: string,
+  params: readonly unknown[] = [],
+): Promise<readonly T[]> {
+  return (await asRawClient(db).unsafe(sqlText, params)) as readonly T[];
+}
+
+export async function pingDatabase(db: AnyDb): Promise<void> {
+  await asRawClient(db).unsafe("SELECT 1");
+}

package/src/db/queries/schema-drift.ts

@@ -0,0 +1,35 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+export type AppliedMigrationRow = {
+  readonly hash: string;
+  readonly created_at: bigint | number | null;
+};
+
+export type DbColumnInfoRow = {
+  readonly column_name: string;
+  readonly data_type: string;
+  readonly is_nullable: "YES" | "NO";
+};
+
+/** tableRef must be `drizzle.__drizzle_migrations` or `public.__drizzle_migrations`. */
+export async function selectAppliedMigrations(
+  db: AnyDb,
+  tableRef: "drizzle.__drizzle_migrations" | "public.__drizzle_migrations",
+): Promise<readonly AppliedMigrationRow[]> {
+  return (await asRawClient(db).unsafe(
+    `SELECT hash, created_at FROM ${tableRef} ORDER BY id`,
+  )) as readonly AppliedMigrationRow[];
+}
+
+export async function selectPublicTableColumns(
+  db: AnyDb,
+  tableName: string,
+): Promise<readonly DbColumnInfoRow[]> {
+  return (await asRawClient(db).unsafe(
+    `SELECT column_name, data_type, is_nullable
+     FROM information_schema.columns
+     WHERE table_schema = 'public' AND table_name = $1`,
+    [tableName],
+  )) as readonly DbColumnInfoRow[];
+}

package/src/db/queries/seed-context.ts

@@ -0,0 +1,58 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+export type SeedUserRow = {
+  readonly id: string;
+  readonly email: string;
+  readonly tenantId: string;
+};
+
+export type SeedMembershipDbRow = {
+  readonly user_id: string;
+  readonly tenant_id: string;
+  readonly stream_tenant_id: string;
+  readonly roles: string;
+};
+
+export type SeedTenantDbRow = {
+  readonly id: string;
+  readonly name: string;
+  readonly tenant_key: string;
+};
+
+export async function selectUserByEmail(db: AnyDb, email: string): Promise<SeedUserRow | null> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT id::text AS id, email, tenant_id::text AS tenant_id
+     FROM read_users
+     WHERE email = $1
+     LIMIT 1`,
+    [email],
+  )) as readonly { id: string; email: string; tenant_id: string }[];
+  const row = rows[0];
+  if (!row) return null;
+  return { id: row.id, email: row.email, tenantId: row.tenant_id };
+}
+
+export async function selectMembershipsOfUser(
+  db: AnyDb,
+  userId: string,
+): Promise<readonly SeedMembershipDbRow[]> {
+  return (await asRawClient(db).unsafe(
+    `SELECT m.user_id::text AS user_id,
+            m.tenant_id::text AS tenant_id,
+            e.tenant_id::text AS stream_tenant_id,
+            m.roles
+     FROM read_tenant_memberships m
+     JOIN kumiko_events e ON e.aggregate_id = m.id AND e.version = 1
+     WHERE m.user_id = $1`,
+    [userId],
+  )) as readonly SeedMembershipDbRow[];
+}
+
+export async function selectAllTenants(db: AnyDb): Promise<readonly SeedTenantDbRow[]> {
+  return (await asRawClient(db).unsafe(
+    `SELECT id::text AS id, name, tenant_key
+     FROM read_tenants
+     ORDER BY inserted_at`,
+  )) as readonly SeedTenantDbRow[];
+}

package/src/db/queries/table-ops.ts

@@ -0,0 +1,11 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+/** Double-quote + escape — Postgres identifier rules. */
+export function quoteTableIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+export async function truncateTable(db: AnyDb, tableName: string): Promise<void> {
+  await asRawClient(db).unsafe(`TRUNCATE TABLE ${quoteTableIdent(tableName)}`);
+}

package/src/db/queries/test-stack.ts

@@ -0,0 +1,56 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+import { quoteTableIdent } from "./table-ops";
+
+export async function executeDdlStatement(db: AnyDb, sqlText: string): Promise<void> {
+  await asRawClient(db).unsafe(sqlText);
+}
+
+export async function alterTableAddColumn(
+  db: AnyDb,
+  tableName: string,
+  columnName: string,
+  columnType: string,
+  defaultClause: string,
+  notNull: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `ALTER TABLE ${quoteTableIdent(tableName)} ADD COLUMN ${quoteTableIdent(columnName)} ${columnType}${defaultClause}${notNull}`,
+  );
+}
+
+export async function createIndexIfNotExists(
+  db: AnyDb,
+  indexKind: "UNIQUE INDEX" | "INDEX",
+  indexName: string,
+  tableName: string,
+  columnList: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})`,
+  );
+}
+
+export async function truncateTablesRestartIdentity(
+  db: AnyDb,
+  tableNames: readonly string[],
+): Promise<void> {
+  const quoted = tableNames.map((name) => quoteTableIdent(name)).join(", ");
+  await asRawClient(db).unsafe(`TRUNCATE ${quoted} RESTART IDENTITY CASCADE`);
+}
+
+export async function databaseExists(db: AnyDb, dbName: string): Promise<boolean> {
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT EXISTS (SELECT 1 FROM pg_database WHERE datname = $1) AS exists`,
+    [dbName],
+  )) as readonly { exists?: boolean }[];
+  return rows[0]?.exists === true;
+}
+
+export async function createDatabase(db: AnyDb, dbName: string): Promise<void> {
+  await asRawClient(db).unsafe(`CREATE DATABASE ${quoteTableIdent(dbName)}`);
+}
+
+export async function dropDatabaseIfExists(db: AnyDb, dbName: string): Promise<void> {
+  await asRawClient(db).unsafe(`DROP DATABASE IF EXISTS ${quoteTableIdent(dbName)}`);
+}