@manablox/db 0.1.0 → 0.2.0

package/src/schema/content.ts

@@ -0,0 +1,133 @@
+import type { ContentStatus } from '@manablox/core';
+import { sql } from 'drizzle-orm';
+import {
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  unique,
+  uniqueIndex,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import { ltree, tsvector } from '../columns.js';
+import { spaces } from './spaces.js';
+
+/** Shared column set for `contents` and its published projection. */
+const contentColumns = {
+  id: uuid().primaryKey().defaultRandom(),
+  spaceId: uuid()
+    .notNull()
+    .references(() => spaces.id, { onDelete: 'cascade' }),
+  typeId: uuid().notNull(),
+  locale: text().notNull(),
+  /** Shared by all translations of one logical document. */
+  localizationId: uuid().notNull(),
+  parentId: uuid(),
+  title: text().notNull(),
+  slug: text().notNull(),
+  /** Materialised ancestor path, root first, ending in this node's own id. */
+  path: ltree().notNull(),
+  /** Routable URL path. NULL when the content type has no slug — such a node is a
+   * structural container, not a page, so it must not occupy a permalink of its own. */
+  permalink: text(),
+  /**
+   * Accumulated permalink prefix: every ancestor segment plus this node's own, with
+   * slug-less levels skipped. Descendants derive from this rather than from `permalink`,
+   * which is NULL for a slug-less node and would otherwise truncate the chain.
+   */
+  permalinkPath: text().notNull().default(''),
+  /**
+   * This node's own contribution to its descendants' permalinks: the slug when the
+   * content type has one, NULL when it does not.
+   *
+   * Denormalised deliberately, so permalink recomputation is a single recursive CTE that
+   * needs no knowledge of the type registry.
+   */
+  permalinkSegment: text(),
+  status: text().$type<ContentStatus>().notNull().default('draft'),
+  position: integer().notNull().default(0),
+  fields: jsonb().$type<Record<string, unknown>>().notNull().default(sql`'{}'::jsonb`),
+  /** Concatenated contributions from each field type's `search()`. */
+  searchText: text().notNull().default(''),
+  /** Optimistic-lock counter; a write with a stale version is rejected. */
+  version: integer().notNull().default(1),
+  createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  createdBy: uuid(),
+  updatedBy: uuid(),
+  publishedAt: timestamp({ withTimezone: true }),
+};
+
+export const contents = pgTable(
+  'contents',
+  {
+    ...contentColumns,
+    search: tsvector().generatedAlwaysAs(
+      sql`to_tsvector('simple', coalesce(title, '') || ' ' || coalesce(search_text, ''))`,
+    ),
+  },
+  (table) => [
+    index('contents_path_gist_idx').using('gist', table.path),
+    index('contents_parent_idx').on(table.parentId),
+    index('contents_space_type_idx').on(table.spaceId, table.typeId),
+    index('contents_localization_idx').on(table.localizationId),
+    index('contents_status_idx').on(table.spaceId, table.status),
+    index('contents_fields_gin_idx').using('gin', sql`${table.fields} jsonb_path_ops`),
+    index('contents_search_gin_idx').using('gin', table.search),
+    // NULLS NOT DISTINCT so two root-level siblings cannot share a slug — with the
+    // default NULLS DISTINCT, every `parent_id IS NULL` row is unique by definition and
+    // the constraint would never fire at the top of the tree.
+    unique('contents_sibling_slug_key')
+      .on(table.spaceId, table.parentId, table.locale, table.slug)
+      .nullsNotDistinct(),
+    uniqueIndex('contents_permalink_key')
+      .on(table.spaceId, table.locale, table.permalink)
+      .where(sql`permalink is not null`),
+  ],
+);
+
+/**
+ * The delivery projection. Written transactionally on publish, read by the public
+ * GraphQL API. Mirrors `contents` so a row can be copied column-for-column.
+ */
+export const publishedContents = pgTable(
+  'published_contents',
+  {
+    ...contentColumns,
+    /** Version of `contents` this projection was made from. */
+    sourceVersion: integer().notNull().default(1),
+    search: tsvector().generatedAlwaysAs(
+      sql`to_tsvector('simple', coalesce(title, '') || ' ' || coalesce(search_text, ''))`,
+    ),
+  },
+  (table) => [
+    index('published_contents_path_gist_idx').using('gist', table.path),
+    index('published_contents_parent_idx').on(table.parentId),
+    index('published_contents_space_type_idx').on(table.spaceId, table.typeId),
+    index('published_contents_fields_gin_idx').using('gin', sql`${table.fields} jsonb_path_ops`),
+    index('published_contents_search_gin_idx').using('gin', table.search),
+    uniqueIndex('published_contents_permalink_key')
+      .on(table.spaceId, table.locale, table.permalink)
+      .where(sql`permalink is not null`),
+  ],
+);
+
+/** Full snapshot per save, so any edit can be rolled back. */
+export const contentVersions = pgTable(
+  'content_versions',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    contentId: uuid().notNull(),
+    version: integer().notNull(),
+    label: text(),
+    snapshot: jsonb().$type<Record<string, unknown>>().notNull(),
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+    createdBy: uuid(),
+  },
+  (table) => [
+    uniqueIndex('content_versions_content_version_key').on(table.contentId, table.version),
+    index('content_versions_content_idx').on(table.contentId, table.createdAt),
+  ],
+);

package/src/schema/index.ts

@@ -0,0 +1,38 @@
+/**
+ * The database schema, one file per entity. `drizzle.config.ts` points at this directory,
+ * and `relations.ts` ties the tables together so `db.query` can traverse them.
+ */
+export * from './assets.js';
+export * from './auth.js';
+export * from './content.js';
+export * from './content-types.js';
+export * from './menus.js';
+export * from './relations.js';
+export * from './spaces.js';
+export * from './webhooks.js';
+export * from './workflows.js';
+
+import type { assets, assetUsages, assetVariants } from './assets.js';
+import type { memberships, roles, users } from './auth.js';
+import type { contents, contentVersions } from './content.js';
+import type { contentTypes } from './content-types.js';
+import type { menuItems, menus } from './menus.js';
+import type { spaces } from './spaces.js';
+import type { pushSubscriptions, workflowRuns, workflows } from './workflows.js';
+
+export type SpaceRow = typeof spaces.$inferSelect;
+export type ContentRow = typeof contents.$inferSelect;
+export type ContentInsert = typeof contents.$inferInsert;
+export type ContentTypeRow = typeof contentTypes.$inferSelect;
+export type AssetRow = typeof assets.$inferSelect;
+export type AssetVariantRow = typeof assetVariants.$inferSelect;
+export type AssetUsageRow = typeof assetUsages.$inferSelect;
+export type UserRow = typeof users.$inferSelect;
+export type MembershipRow = typeof memberships.$inferSelect;
+export type RoleRow = typeof roles.$inferSelect;
+export type ContentVersionRow = typeof contentVersions.$inferSelect;
+export type MenuRow = typeof menus.$inferSelect;
+export type MenuItemRow = typeof menuItems.$inferSelect;
+export type WorkflowRow = typeof workflows.$inferSelect;
+export type WorkflowRunRow = typeof workflowRuns.$inferSelect;
+export type PushSubscriptionRow = typeof pushSubscriptions.$inferSelect;

package/src/schema/menus.ts

@@ -0,0 +1,61 @@
+import {
+  type AnyPgColumn,
+  index,
+  integer,
+  pgTable,
+  text,
+  timestamp,
+  unique,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import { spaces } from './spaces.js';
+
+/**
+ * A named navigation a site renders: "main", "footer", "legal". A document may sit in
+ * any number of them, which is why membership is a row here and not a flag on the
+ * document.
+ */
+export const menus = pgTable(
+  'menus',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    spaceId: uuid()
+      .notNull()
+      .references(() => spaces.id, { onDelete: 'cascade' }),
+    name: text().notNull(),
+    /** What the delivery API is asked for: `menu(name: "main")`. */
+    machineName: text().notNull(),
+    description: text(),
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [unique('menus_space_machine_name_key').on(table.spaceId, table.machineName)],
+);
+
+/**
+ * One entry of a menu, nested to any depth.
+ *
+ * A content entry points at the document's `localizationId` rather than at one row, so
+ * the same menu serves every locale: delivery resolves the translation for the locale
+ * it is asked for. A link entry has a `url` instead. Either may carry a `label`; for a
+ * content entry it overrides the document's title.
+ */
+export const menuItems = pgTable(
+  'menu_items',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    menuId: uuid()
+      .notNull()
+      .references(() => menus.id, { onDelete: 'cascade' }),
+    /** Cascades, so removing an entry takes its sub-entries with it. */
+    parentId: uuid().references((): AnyPgColumn => menuItems.id, { onDelete: 'cascade' }),
+    position: integer().notNull().default(0),
+    localizationId: uuid(),
+    label: text(),
+    url: text(),
+  },
+  (table) => [
+    index('menu_items_menu_idx').on(table.menuId, table.parentId, table.position),
+    index('menu_items_localization_idx').on(table.localizationId),
+  ],
+);

package/src/schema/relations.ts

@@ -0,0 +1,64 @@
+import { relations } from 'drizzle-orm';
+import { assets, assetUsages, assetVariants } from './assets.js';
+import { memberships, roles, sessions, users } from './auth.js';
+import { contents, contentVersions } from './content.js';
+import { contentTypes } from './content-types.js';
+import { menuItems, menus } from './menus.js';
+import { spaces } from './spaces.js';
+
+export const spacesRelations = relations(spaces, ({ many }) => ({
+  contents: many(contents),
+  contentTypes: many(contentTypes),
+  assets: many(assets),
+  memberships: many(memberships),
+  menus: many(menus),
+  roles: many(roles),
+}));
+
+export const contentsRelations = relations(contents, ({ one, many }) => ({
+  space: one(spaces, { fields: [contents.spaceId], references: [spaces.id] }),
+  parent: one(contents, {
+    fields: [contents.parentId],
+    references: [contents.id],
+    relationName: 'tree',
+  }),
+  children: many(contents, { relationName: 'tree' }),
+  versions: many(contentVersions),
+}));
+
+export const assetsRelations = relations(assets, ({ one, many }) => ({
+  space: one(spaces, { fields: [assets.spaceId], references: [spaces.id] }),
+  variants: many(assetVariants),
+}));
+
+export const assetVariantsRelations = relations(assetVariants, ({ one }) => ({
+  asset: one(assets, { fields: [assetVariants.assetId], references: [assets.id] }),
+}));
+
+export const assetUsagesRelations = relations(assetUsages, ({ one }) => ({
+  asset: one(assets, { fields: [assetUsages.assetId], references: [assets.id] }),
+  content: one(contents, { fields: [assetUsages.contentId], references: [contents.id] }),
+}));
+
+export const usersRelations = relations(users, ({ many }) => ({
+  sessions: many(sessions),
+  memberships: many(memberships),
+}));
+
+export const membershipsRelations = relations(memberships, ({ one }) => ({
+  user: one(users, { fields: [memberships.userId], references: [users.id] }),
+  space: one(spaces, { fields: [memberships.spaceId], references: [spaces.id] }),
+}));
+
+export const menusRelations = relations(menus, ({ one, many }) => ({
+  space: one(spaces, { fields: [menus.spaceId], references: [spaces.id] }),
+  items: many(menuItems),
+}));
+
+export const menuItemsRelations = relations(menuItems, ({ one }) => ({
+  menu: one(menus, { fields: [menuItems.menuId], references: [menus.id] }),
+}));
+
+export const rolesRelations = relations(roles, ({ one }) => ({
+  space: one(spaces, { fields: [roles.spaceId], references: [spaces.id] }),
+}));

package/src/schema/spaces.ts

@@ -0,0 +1,20 @@
+import { sql } from 'drizzle-orm';
+import { jsonb, pgTable, text, timestamp, uniqueIndex, uuid } from 'drizzle-orm/pg-core';
+
+export const spaces = pgTable(
+  'spaces',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    name: text().notNull(),
+    machineName: text().notNull(),
+    description: text(),
+    /** Public origin of the space's frontend — used by the visual editor iframe. */
+    url: text().notNull(),
+    defaultLocale: text().notNull().default('en'),
+    locales: jsonb().$type<string[]>().notNull().default(sql`'["en"]'::jsonb`),
+    settings: jsonb().$type<Record<string, unknown>>().notNull().default(sql`'{}'::jsonb`),
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [uniqueIndex('spaces_machine_name_key').on(table.machineName)],
+);

package/src/schema/webhooks.ts

@@ -0,0 +1,46 @@
+import { sql } from 'drizzle-orm';
+import {
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uuid,
+} from 'drizzle-orm/pg-core';
+import { spaces } from './spaces.js';
+
+export const webhooks = pgTable(
+  'webhooks',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    spaceId: uuid()
+      .notNull()
+      .references(() => spaces.id, { onDelete: 'cascade' }),
+    name: text().notNull(),
+    url: text().notNull(),
+    secret: text(),
+    events: jsonb().$type<string[]>().notNull().default(sql`'[]'::jsonb`),
+    enabled: boolean().notNull().default(true),
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index('webhooks_space_idx').on(table.spaceId)],
+);
+
+export const webhookDeliveries = pgTable(
+  'webhook_deliveries',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    webhookId: uuid()
+      .notNull()
+      .references(() => webhooks.id, { onDelete: 'cascade' }),
+    event: text().notNull(),
+    payload: jsonb().$type<Record<string, unknown>>().notNull(),
+    status: integer(),
+    error: text(),
+    attempt: integer().notNull().default(1),
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index('webhook_deliveries_webhook_idx').on(table.webhookId, table.createdAt)],
+);

package/src/schema/workflows.ts

@@ -0,0 +1,92 @@
+import type {
+  WorkflowCursor,
+  WorkflowRunContext,
+  WorkflowRunStatus,
+  WorkflowStep,
+  WorkflowStepLog,
+  WorkflowTrigger,
+} from '@manablox/core';
+import { sql } from 'drizzle-orm';
+import { boolean, index, jsonb, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+import { users } from './auth.js';
+import { spaces } from './spaces.js';
+
+/**
+ * A workflow: something that happens when content changes, or on a schedule. The
+ * trigger and the steps are documents rather than rows — a workflow is edited and saved
+ * as one thing, and a step type added later needs no migration.
+ */
+export const workflows = pgTable(
+  'workflows',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    spaceId: uuid()
+      .notNull()
+      .references(() => spaces.id, { onDelete: 'cascade' }),
+    name: text().notNull(),
+    description: text(),
+    enabled: boolean().notNull().default(false),
+    trigger: jsonb().$type<WorkflowTrigger>().notNull(),
+    steps: jsonb().$type<WorkflowStep[]>().notNull().default(sql`'[]'::jsonb`),
+    /**
+     * The minute a scheduled workflow was last claimed for, so two processes ticking at
+     * once start one run between them rather than one each.
+     */
+    lastScheduledAt: timestamp({ withTimezone: true }),
+    lastRunAt: timestamp({ withTimezone: true }),
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index('workflows_space_idx').on(table.spaceId, table.enabled)],
+);
+
+/**
+ * One execution of a workflow, with everything needed to continue it after a pause: the
+ * context the templates read, the index of the next step and the log so far.
+ */
+export const workflowRuns = pgTable(
+  'workflow_runs',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    workflowId: uuid()
+      .notNull()
+      .references(() => workflows.id, { onDelete: 'cascade' }),
+    spaceId: uuid()
+      .notNull()
+      .references(() => spaces.id, { onDelete: 'cascade' }),
+    /** The event name, or `schedule` / `manual`. */
+    trigger: text().notNull(),
+    status: text().$type<WorkflowRunStatus>().notNull().default('queued'),
+    context: jsonb().$type<WorkflowRunContext>().notNull(),
+    /** Where to continue; a paused run resumes here. See `WorkflowCursor`. */
+    cursor: jsonb().$type<WorkflowCursor>().notNull().default(sql`'[]'::jsonb`),
+    log: jsonb().$type<WorkflowStepLog[]>().notNull().default(sql`'[]'::jsonb`),
+    error: text(),
+    /** Set while `waiting`: when the scheduler should pick the run up again. */
+    resumeAt: timestamp({ withTimezone: true }),
+    startedAt: timestamp({ withTimezone: true }),
+    finishedAt: timestamp({ withTimezone: true }),
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index('workflow_runs_workflow_idx').on(table.workflowId, table.createdAt),
+    index('workflow_runs_resume_idx').on(table.status, table.resumeAt),
+  ],
+);
+
+/** A browser a user allowed push notifications in; one row per device. */
+export const pushSubscriptions = pgTable(
+  'push_subscriptions',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    userId: uuid()
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    endpoint: text().notNull().unique('push_subscriptions_endpoint_key'),
+    keys: jsonb().$type<{ p256dh: string; auth: string }>().notNull(),
+    userAgent: text(),
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+    lastUsedAt: timestamp({ withTimezone: true }),
+  },
+  (table) => [index('push_subscriptions_user_idx').on(table.userId)],
+);

package/{test/helpers.ts → src/testing-fixtures.ts}

@@ -1,5 +1,8 @@
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+/**
+ * Fixtures for a repository-level test: two plain field types, a `page` and a `folder`
+ * content type, a migrated database with one space, and a node maker. Shared through
+ * `@manablox/db/testing` so a suite in another package can start from the same world.
+ */
 import {
   type ContentTypeDefinition,
   ContentTypeRegistry,
@@ -8,24 +11,9 @@ import {
   FieldTypeRegistry,
   type StandardSchemaV1,
 } from '@manablox/core';
-import { migrate } from 'drizzle-orm/postgres-js/migrator';
-import postgres from 'postgres';
-import { applyBootstrapSql } from '../src/bootstrap.js';
-import { createDatabase, type DatabaseHandle } from '../src/client.js';
-import { createRepositories, type Repositories } from '../src/repositories/index.js';
-
-const MIGRATIONS = resolve(dirname(fileURLToPath(import.meta.url)), '../migrations');
-/**
- * Only ever connected to in order to `create database`: every test file works in its own
- * fresh database and drops it again, so this points at a Postgres *server*, not at data
- * the tests touch. That is why falling back to `DATABASE_URL` is safe — it means the
- * suite runs wherever the app itself runs (a container, CI, the host) without a second
- * variable that has to be kept in step. `TEST_DATABASE_URL` still overrides it.
- */
-const ADMIN_URL =
-  process.env.TEST_DATABASE_URL ??
-  process.env.DATABASE_URL ??
-  'postgres://manablox:manablox@localhost:5432/manablox';
+import { createDatabase, type DatabaseHandle } from './client.js';
+import { createRepositories, type Repositories } from './repositories/index.js';
+import { createTestDatabase } from './testing.js';
 
 const anySchema = <T>(): StandardSchemaV1<unknown, T> => ({
   '~standard': { version: 1, vendor: 'test', validate: (value) => ({ value: value as T }) },
@@ -56,8 +44,10 @@ export const numberField = defineFieldType({
   admin: { input: 'number' },
 });
 
-export interface TestContext {
+export interface RepositoryTestContext {
   handle: DatabaseHandle;
+  /** Every statement sent to Postgres, so a test can assert what a call cost. */
+  queries: string[];
   repos: Repositories;
   registry: ContentTypeRegistry;
   types: { page: ContentTypeDefinition; folder: ContentTypeDefinition };
@@ -66,16 +56,13 @@ export interface TestContext {
 }
 
 /** Spins up an isolated database per suite, migrated from the real migration files. */
-export async function createTestContext(name: string): Promise<TestContext> {
-  const dbName = `manablox_test_${name}_${Date.now().toString(36)}`;
-  const admin = postgres(ADMIN_URL, { max: 1 });
-  await admin.unsafe(`create database "${dbName}"`);
-  await admin.end();
-
-  const url = ADMIN_URL.replace(/\/[^/]*$/, `/${dbName}`);
-  const handle = createDatabase({ url, max: 4 });
-  await applyBootstrapSql(handle.sql);
-  await migrate(handle.db, { migrationsFolder: MIGRATIONS });
+export async function createRepositoryContext(name: string): Promise<RepositoryTestContext> {
+  const database = await createTestDatabase(name);
+  const queries: string[] = [];
+  const handle = createDatabase(
+    { url: database.url, max: 4 },
+    { onQuery: (query) => queries.push(query) },
+  );
 
   const fieldTypes = new FieldTypeRegistry();
   fieldTypes.register(stringField);
@@ -108,22 +95,21 @@ export async function createTestContext(name: string): Promise<TestContext> {
 
   return {
     handle,
+    queries,
     repos,
     registry,
     types: { page, folder },
     spaceId: space.id,
     close: async () => {
       await handle.close();
-      const cleanup = postgres(ADMIN_URL, { max: 1 });
-      await cleanup.unsafe(`drop database if exists "${dbName}" with (force)`);
-      await cleanup.end();
+      await database.drop();
     },
   };
 }
 
 /** Convenience creator so tests read as tree shapes rather than field soup. */
 export async function makeNode(
-  ctx: TestContext,
+  ctx: RepositoryTestContext,
   options: {
     title: string;
     slug: string;

package/src/testing.ts

@@ -0,0 +1,105 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { migrate } from 'drizzle-orm/postgres-js/migrator';
+import postgres from 'postgres';
+import { applyBootstrapSql } from './bootstrap.js';
+import { createDatabase } from './client.js';
+
+const MIGRATIONS = resolve(dirname(fileURLToPath(import.meta.url)), '../migrations');
+
+/**
+ * Only ever connected to in order to `create database`: every test file works in its own
+ * fresh database and drops it again, so this points at a Postgres *server*, not at data
+ * the tests touch. That is why falling back to `DATABASE_URL` is safe — it means the
+ * suite runs wherever the app itself runs (a container, CI, the host) without a second
+ * variable that has to be kept in step. `TEST_DATABASE_URL` still overrides it.
+ */
+export const TEST_ADMIN_URL =
+  process.env.TEST_DATABASE_URL ??
+  process.env.DATABASE_URL ??
+  'postgres://manablox:manablox@localhost:5432/manablox';
+
+/** A fingerprint of the migration files, so a schema change gets a fresh template. */
+function migrationsFingerprint(): string {
+  const hash = createHash('sha1');
+  for (const file of readdirSync(MIGRATIONS).sort()) {
+    if (file.endsWith('.sql')) hash.update(readFileSync(join(MIGRATIONS, file)));
+  }
+  return hash.digest('hex').slice(0, 10);
+}
+
+const TEMPLATE = `manablox_test_template_${migrationsFingerprint()}`;
+
+/**
+ * Makes sure the migrated template exists, once per server.
+ *
+ * Migrating takes a second or two; `create database … template …` takes milliseconds,
+ * so every suite clones the template instead of migrating from scratch. Suites run in
+ * parallel across processes, so the check-and-create is serialised on a session-level
+ * advisory lock — the second process finds the template already there.
+ */
+async function ensureTemplate(admin: postgres.Sql): Promise<void> {
+  await admin.unsafe(`select pg_advisory_lock(hashtext('${TEMPLATE}'))`);
+  try {
+    const [row] = await admin.unsafe(
+      `select 1 as found from pg_database where datname = '${TEMPLATE}'`,
+    );
+    if (row) return;
+
+    await admin.unsafe(`create database "${TEMPLATE}"`);
+    const handle = createDatabase({ url: withDatabase(TEST_ADMIN_URL, TEMPLATE), max: 1 });
+    try {
+      await applyBootstrapSql(handle.sql);
+      await migrate(handle.db, { migrationsFolder: MIGRATIONS });
+    } finally {
+      await handle.close();
+    }
+  } finally {
+    await admin.unsafe(`select pg_advisory_unlock(hashtext('${TEMPLATE}'))`);
+  }
+}
+
+export function withDatabase(url: string, name: string): string {
+  return url.replace(/\/[^/?]*(\?.*)?$/, `/${name}$1`);
+}
+
+export interface TestDatabase {
+  name: string;
+  url: string;
+  /** Drops the database. Safe to call once every connection to it is closed. */
+  drop: () => Promise<void>;
+}
+
+/**
+ * A fresh, migrated database for one test suite, cloned from the template.
+ *
+ * `prefix` names the suite in `pg_database`, which is what you grep for when a run was
+ * interrupted and left a database behind.
+ */
+export async function createTestDatabase(prefix: string): Promise<TestDatabase> {
+  const name = `manablox_test_${prefix}_${Date.now().toString(36)}_${process.pid.toString(36)}`;
+  const admin = postgres(TEST_ADMIN_URL, { max: 1 });
+  try {
+    await ensureTemplate(admin);
+    await admin.unsafe(`create database "${name}" template "${TEMPLATE}"`);
+  } finally {
+    await admin.end();
+  }
+
+  return {
+    name,
+    url: withDatabase(TEST_ADMIN_URL, name),
+    drop: async () => {
+      const cleanup = postgres(TEST_ADMIN_URL, { max: 1 });
+      try {
+        await cleanup.unsafe(`drop database if exists "${name}" with (force)`);
+      } finally {
+        await cleanup.end();
+      }
+    },
+  };
+}
+
+export * from './testing-fixtures.js';

package/test/asset-usage.test.ts

@@ -1,12 +1,12 @@
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
-import { createTestContext, makeNode, type TestContext } from './helpers.js';
+import { createRepositoryContext, makeNode, type RepositoryTestContext } from '../src/testing.js';
 
-let ctx: TestContext;
+let ctx: RepositoryTestContext;
 let assetA: string;
 let assetB: string;
 
 beforeAll(async () => {
-  ctx = await createTestContext('asset_usage');
+  ctx = await createRepositoryContext('asset_usage');
   assetA = (await createAsset('a.jpg')).id;
   assetB = (await createAsset('b.jpg')).id;
 });