akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/service/predefinedAdaptor/database.adaptor.ts

@@ -2,15 +2,18 @@ import { Database } from "bun:sqlite";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { getEnv, type PromiseOrObject } from "akanjs/base";
+import type { Client as LibsqlClient } from "@libsql/client";
+import type { PromiseOrObject } from "akanjs/base";
 import type { ConstantModel } from "akanjs/constant";
 import type { DatabaseModel, DocumentSchema, SchemaOf } from "akanjs/document";
+import type { Sql } from "postgres";
 import { adapt } from "../adapt";
 import { ScheduleAdaptorRole } from "./role.adaptor";
 import {
   DEFAULT_TOKENIZER,
   OPTIMIZE_CRON,
   OPTIMIZE_CRON_KEY,
+  PostgresSearchEngine,
   parseSearchEnabled,
   RETRY_INTERVAL_KEY,
   RETRY_INTERVAL_MS,
@@ -21,25 +24,27 @@ import { BunSqliteClient } from "./sql/driver/bunSqlite";
 import { LibsqlAkanClient } from "./sql/driver/libsql";
 import { PostgresAkanClient } from "./sql/driver/postgres";
 import { PendingStoreEnsures } from "./sql/PendingStoreEnsures";
+import { PostgresInsightSession } from "./sql/PostgresInsightSession";
 import { SqlDocumentStore } from "./sql/SqlDocumentStore";
-import type {
-  DatabaseAdaptor,
-  LibsqlDatabaseConfig,
-  PostgresDatabaseConfig,
-  SearchConfig,
-  SqliteDatabaseConfig,
-  SqliteEnv,
-  TransactionContext,
+import { SqliteInsightSession } from "./sql/SqliteInsightSession";
+import {
+  BASE_COLUMNS,
+  type ConcurrentIndexBuild,
+  type DatabaseAdaptor,
+  type InsightSession,
+  type LibsqlDatabaseConfig,
+  type PostgresDatabaseConfig,
+  type SearchConfig,
+  type SqliteDatabaseConfig,
+  type SqliteEnv,
+  type TransactionContext,
 } from "./sql/types";
-import { resolveDefaultSqliteFile } from "./sqlitePath";
+import { quoteIdent } from "./sql/values";
+import { defaultSqliteFile } from "./sqlitePath";
 
 export { PostgresDialect } from "./sql/dialect/postgres";
 export { SqliteDialect } from "./sql/dialect/sqlite";
 export { SqlDocumentStore } from "./sql/SqlDocumentStore";
-/**
- * The three SQL databases an app can mount, and nothing else. The layer underneath them — drivers, dialects,
- * the query and update compilers, and the document store they all share — lives in .
- */
 export type {
   AkanSqlClient,
   AkanSqlStatement,
@@ -47,38 +52,36 @@ export type {
   DatabaseConfig,
   DocumentDatabaseOwner,
   DocumentStore,
+  InsightSession,
   LibsqlDatabaseConfig,
   PostgresDatabaseConfig,
   SearchConfig,
+  SqlDialect,
   SqliteDatabaseConfig,
   SqlResultRows,
 } from "./sql/types";
 
+const searchConfigOf = (env: SqliteEnv): Required<SearchConfig> => ({
+  enabled: env.database?.search?.enabled ?? parseSearchEnabled(process.env.AKAN_SEARCH_ENABLED),
+  tokenizer: env.database?.search?.tokenizer ?? process.env.AKAN_SEARCH_TOKENIZER ?? DEFAULT_TOKENIZER,
+});
+
 export class SqliteDatabase
   extends adapt("sqliteDatabase", ({ env, plug }) => ({
     scheduler: plug(ScheduleAdaptorRole),
     config: env((env: SqliteEnv) => {
-      const defaultFile = () => {
-        const { appName, environment, operationMode } = getEnv();
-        return resolveDefaultSqliteFile({
-          appName,
-          fileName: `${appName}-${environment}.db`,
-          isProduction: process.env.NODE_ENV === "production",
-          operationMode,
-          workspaceRoot: env.workspaceRoot,
-        });
-      };
       return {
         journalMode: "WAL",
         busyTimeoutMs: 5000,
         synchronous: "NORMAL",
         foreignKeys: true,
         ...env.database?.sqlite,
-        filePath: env.database?.sqlite?.filePath ?? process.env.SQLITE_DATABASE_PATH ?? defaultFile(),
-        search: {
-          enabled: env.database?.search?.enabled ?? parseSearchEnabled(process.env.AKAN_SEARCH_ENABLED),
-          tokenizer: env.database?.search?.tokenizer ?? process.env.AKAN_SEARCH_TOKENIZER ?? DEFAULT_TOKENIZER,
-        },
+        
+        filePath:
+          process.env.SQLITE_DATABASE_PATH ??
+          env.database?.sqlite?.filePath ??
+          defaultSqliteFile("", env.workspaceRoot),
+        search: searchConfigOf(env),
       } satisfies Required<
         Pick<SqliteDatabaseConfig, "filePath" | "journalMode" | "busyTimeoutMs" | "synchronous" | "foreignKeys">
       > &
@@ -94,10 +97,14 @@ export class SqliteDatabase
   #ensures = new PendingStoreEnsures();
   #searchIndex!: SearchIndex;
 
+  #open: { context: TransactionContext; done: Promise<void> } | null = null;
+  #queue: Promise<void> = Promise.resolve();
+
   override async onInit() {
-    await mkdir(path.dirname(this.config.filePath), { recursive: true });
+    
+    await mkdir(path.dirname(path.resolve(this.config.filePath)), { recursive: true });
     this.#db = new Database(this.config.filePath, { strict: true, create: true });
-    this.#client = new BunSqliteClient(this.#db);
+    this.#client = new BunSqliteClient(this.#db, () => this.#writeTurn());
     this.#db.run(`PRAGMA journal_mode = ${this.config.journalMode ?? "WAL"}`);
     this.#db.run(`PRAGMA busy_timeout = ${this.config.busyTimeoutMs ?? 5000}`);
     this.#db.run(`PRAGMA synchronous = ${this.config.synchronous ?? "NORMAL"}`);
@@ -133,6 +140,19 @@ export class SqliteDatabase
     return this.#searchIndex;
   }
 
+  async openInsight(): Promise<InsightSession> {
+    const main = this.#db.query(`SELECT "file" FROM pragma_database_list WHERE "name" = 'main'`).get() as {
+      file: string;
+    } | null;
+    return main?.file
+      ? SqliteInsightSession.open(main.file)
+      : await SqliteInsightSession.openSnapshot(this.#db.serialize());
+  }
+
+  stores() {
+    return [...this.#stores.values()];
+  }
+
   getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf) {
     const existing = this.#stores.get(database.refName);
     if (existing) return existing;
@@ -148,8 +168,8 @@ export class SqliteDatabase
   }
 
   async setMeta(key: string, value: string) {
-    this.#db
-      .query(
+    await this.#client
+      .prepare(
         `INSERT INTO "_akan_meta" ("key", "value", "updatedAt") VALUES (?, ?, ?) ON CONFLICT("key") DO UPDATE SET "value" = excluded."value", "updatedAt" = excluded."updatedAt"`,
       )
       .run(key, value, Date.now());
@@ -158,19 +178,40 @@ export class SqliteDatabase
   async transaction<T>(fn: () => PromiseOrObject<T>): Promise<T> {
     const active = this.#transaction.getStore();
     if (active) return await fn();
-    const context: TransactionContext = { afterCommit: [] };
-    return await this.#transaction.run(context, async () => {
-      this.#db.run("BEGIN IMMEDIATE");
-      try {
-        const result = await fn();
-        this.#db.run("COMMIT");
-        for (const hook of context.afterCommit) await hook();
-        return result;
-      } catch (err) {
-        this.#db.run("ROLLBACK");
-        throw err;
-      }
+    const previous = this.#queue;
+    let release!: () => void;
+    const done = new Promise<void>((resolve) => {
+      release = resolve;
     });
+    this.#queue = done;
+    await previous;
+    const context: TransactionContext = { afterCommit: [] };
+    this.#open = { context, done };
+    let result: T;
+    try {
+      result = await this.#transaction.run(context, async () => {
+        this.#db.run("BEGIN IMMEDIATE");
+        try {
+          const value = await fn();
+          this.#db.run("COMMIT");
+          return value;
+        } catch (err) {
+          if (this.#db.inTransaction) this.#db.run("ROLLBACK");
+          throw err;
+        }
+      });
+    } finally {
+      this.#open = null;
+      release();
+    }
+    for (const hook of context.afterCommit) await hook();
+    return result;
+  }
+
+  #writeTurn() {
+    const open = this.#open;
+    if (!open || this.#transaction.getStore() === open.context) return null;
+    return open.done;
   }
 
   async afterCommit(fn: () => PromiseOrObject<void>) {
@@ -192,43 +233,35 @@ export class LibsqlDatabase
   extends adapt("libsqlDatabase", ({ env, plug }) => ({
     scheduler: plug(ScheduleAdaptorRole),
     config: env((env: SqliteEnv) => {
-      const defaultFile = () => {
-        const { appName, environment, operationMode } = getEnv();
-        return resolveDefaultSqliteFile({
-          appName,
-          fileName: `${appName}-${environment}.db`,
-          isProduction: process.env.NODE_ENV === "production",
-          operationMode,
-          workspaceRoot: env.workspaceRoot,
-        });
-      };
       return {
         url:
-          env.database?.libsql?.url ??
           process.env.LIBSQL_URL ??
           process.env.LIBSQL_URI ??
-          `file:${env.database?.sqlite?.filePath ?? process.env.SQLITE_DATABASE_PATH ?? defaultFile()}`,
-        authToken: env.database?.libsql?.authToken ?? process.env.LIBSQL_AUTH_TOKEN,
-        search: {
-          enabled: env.database?.search?.enabled ?? parseSearchEnabled(process.env.AKAN_SEARCH_ENABLED),
-          tokenizer: env.database?.search?.tokenizer ?? process.env.AKAN_SEARCH_TOKENIZER ?? DEFAULT_TOKENIZER,
-        },
+          env.database?.libsql?.url ??
+          `file:${process.env.SQLITE_DATABASE_PATH ?? env.database?.sqlite?.filePath ?? defaultSqliteFile("", env.workspaceRoot)}`,
+        authToken: process.env.LIBSQL_AUTH_TOKEN ?? env.database?.libsql?.authToken,
+        search: searchConfigOf(env),
       } satisfies LibsqlDatabaseConfig & { search: Required<SearchConfig> };
     }),
   }))
   implements DatabaseAdaptor
 {
+  #libsql!: LibsqlClient;
   #client!: LibsqlAkanClient;
   #stores = new Map<string, SqlDocumentStore>();
-  #transaction = new AsyncLocalStorage<TransactionContext>();
+  #transaction = new AsyncLocalStorage<TransactionContext & { client: LibsqlAkanClient }>();
   #ensures = new PendingStoreEnsures();
   #searchIndex!: SearchIndex;
 
+  #open: { context: TransactionContext; done: Promise<void> } | null = null;
+  #queue: Promise<void> = Promise.resolve();
+
   override async onInit() {
     const url = this.config.url ?? "file:local.db";
-    if (url.startsWith("file:")) await mkdir(path.dirname(url.slice(5)), { recursive: true });
+    if (url.startsWith("file:")) await mkdir(path.dirname(path.resolve(url.slice(5))), { recursive: true });
     const { createClient } = await import("@libsql/client");
-    this.#client = new LibsqlAkanClient(createClient({ url, authToken: this.config.authToken }));
+    this.#libsql = createClient({ url, authToken: this.config.authToken });
+    this.#client = new LibsqlAkanClient(this.#libsql, () => this.#writeTurn());
     await this.#client.execute(
       `CREATE TABLE IF NOT EXISTS "_akan_meta" ("key" TEXT PRIMARY KEY NOT NULL, "value" TEXT NOT NULL, "updatedAt" INTEGER NOT NULL)`,
     );
@@ -250,13 +283,23 @@ export class LibsqlDatabase
   }
 
   getConnection() {
-    return this.#client;
+    return this.#transaction.getStore()?.client ?? this.#client;
   }
 
   getSearchIndex() {
     return this.#searchIndex;
   }
 
+  async openInsight(): Promise<InsightSession> {
+    throw new Error(
+      "An insight query needs the sqlite or postgres database: libsql has no connection that can leave `_doc` out.",
+    );
+  }
+
+  stores() {
+    return [...this.#stores.values()];
+  }
+
   getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf) {
     const existing = this.#stores.get(database.refName);
     if (existing) return existing;
@@ -267,12 +310,13 @@ export class LibsqlDatabase
   }
 
   async getMeta(key: string) {
-    return (await this.#client.prepare(`SELECT "value" FROM "_akan_meta" WHERE "key" = ?`).get<{ value: string }>(key))
-      ?.value;
+    return (
+      await this.getConnection().prepare(`SELECT "value" FROM "_akan_meta" WHERE "key" = ?`).get<{ value: string }>(key)
+    )?.value;
   }
 
   async setMeta(key: string, value: string) {
-    await this.#client
+    await this.getConnection()
       .prepare(
         `INSERT INTO "_akan_meta" ("key", "value", "updatedAt") VALUES (?, ?, ?) ON CONFLICT("key") DO UPDATE SET "value" = excluded."value", "updatedAt" = excluded."updatedAt"`,
       )
@@ -282,19 +326,42 @@ export class LibsqlDatabase
   async transaction<T>(fn: () => PromiseOrObject<T>): Promise<T> {
     const active = this.#transaction.getStore();
     if (active) return await fn();
+    const previous = this.#queue;
+    let release!: () => void;
+    const done = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    this.#queue = done;
+    await previous;
     const context: TransactionContext = { afterCommit: [] };
-    return await this.#transaction.run(context, async () => {
-      await this.#client.execute("BEGIN IMMEDIATE");
+    this.#open = { context, done };
+    let result: T;
+    try {
+      const transaction = await this.#libsql.transaction("write");
       try {
-        const result = await fn();
-        await this.#client.execute("COMMIT");
-        for (const hook of context.afterCommit) await hook();
-        return result;
+        result = await this.#transaction.run(
+          { ...context, client: new LibsqlAkanClient(transaction) },
+          async () => await fn(),
+        );
+        await transaction.commit();
       } catch (err) {
-        await this.#client.execute("ROLLBACK");
+        if (!transaction.closed) await transaction.rollback();
         throw err;
+      } finally {
+        transaction.close();
       }
-    });
+    } finally {
+      this.#open = null;
+      release();
+    }
+    for (const hook of context.afterCommit) await hook();
+    return result;
+  }
+
+  #writeTurn() {
+    const open = this.#open;
+    if (!open || this.#transaction.getStore()?.afterCommit === open.context.afterCommit) return null;
+    return open.done;
   }
 
   async afterCommit(fn: () => PromiseOrObject<void>) {
@@ -305,53 +372,175 @@ export class LibsqlDatabase
 }
 
 export class PostgresDatabase
-  extends adapt("postgresDatabase", ({ env }) => ({
+  extends adapt("postgresDatabase", ({ env, plug }) => ({
+    scheduler: plug(ScheduleAdaptorRole),
     config: env((env: SqliteEnv) => {
       return {
-        url: env.database?.postgres?.url ?? process.env.POSTGRES_URL ?? process.env.POSTGRES_URI,
-        host: env.database?.postgres?.host ?? process.env.POSTGRES_HOST ?? "localhost",
-        port: env.database?.postgres?.port ?? Number(process.env.POSTGRES_PORT ?? 5432),
-        database: env.database?.postgres?.database ?? process.env.POSTGRES_DATABASE ?? "akan",
-        user: env.database?.postgres?.user ?? process.env.POSTGRES_USER ?? "akan",
-        password: env.database?.postgres?.password ?? process.env.POSTGRES_PASSWORD ?? "akan",
-      } satisfies PostgresDatabaseConfig;
+        
+        url: process.env.POSTGRES_URL ?? process.env.POSTGRES_URI ?? env.database?.postgres?.url,
+        host: process.env.POSTGRES_HOST ?? env.database?.postgres?.host ?? "localhost",
+        port: process.env.POSTGRES_PORT ? Number(process.env.POSTGRES_PORT) : (env.database?.postgres?.port ?? 5432),
+        database:
+          process.env.POSTGRES_DATABASE ?? process.env.POSTGRES_DB ?? env.database?.postgres?.database ?? "akan",
+        user: process.env.POSTGRES_USER ?? env.database?.postgres?.user ?? "akan",
+        password: process.env.POSTGRES_PASSWORD ?? env.database?.postgres?.password ?? "akan",
+        insightUrl: process.env.POSTGRES_INSIGHT_URL ?? env.database?.postgres?.insightUrl,
+        search: searchConfigOf(env),
+      } satisfies PostgresDatabaseConfig & { search: Required<SearchConfig> };
     }),
   }))
   implements DatabaseAdaptor
 {
+  #sql!: Sql;
   #client!: PostgresAkanClient;
   #stores = new Map<string, SqlDocumentStore>();
-  #transaction = new AsyncLocalStorage<TransactionContext>();
+  #transaction = new AsyncLocalStorage<TransactionContext & { client: PostgresAkanClient }>();
   #ensures = new PendingStoreEnsures();
+  #schemaTurn: Promise<void> = Promise.resolve();
+  #schema = "public";
+  #insightRole: string | null = null;
+  #searchIndex!: SearchIndex;
 
   override async onInit() {
     const { default: postgres } = await import("postgres");
-    const sql = this.config.url
-      ? postgres(this.config.url)
+    const options = this.#clientOptions();
+    this.#sql = this.config.url
+      ? postgres(this.config.url, options)
       : postgres({
           host: this.config.host,
           port: this.config.port,
           database: this.config.database,
           username: this.config.user,
           password: this.config.password,
+          ...options,
         });
-    this.#client = new PostgresAkanClient(sql);
-    await this.#client.execute(
-      `CREATE TABLE IF NOT EXISTS "_akan_meta" ("key" TEXT PRIMARY KEY NOT NULL, "value" TEXT NOT NULL, "updatedAt" BIGINT NOT NULL)`,
+    this.#client = new PostgresAkanClient(this.#sql);
+    this.#schema =
+      (await this.#client.prepare(`SELECT current_schema() AS "schema"`).get<{ schema: string | null }>())?.schema ??
+      this.#schema;
+    this.#insightRole = await this.#resolveInsightRole();
+    await this.lockSchema(async () => {
+      await this.getConnection().execute(
+        `CREATE TABLE IF NOT EXISTS "_akan_meta" ("key" TEXT PRIMARY KEY NOT NULL, "value" TEXT NOT NULL, "updatedAt" BIGINT NOT NULL)`,
+      );
+      await this.getConnection().execute(PostgresDialect.schemaSetup());
+      await this.#grantInsightSchema();
+    });
+    this.#searchIndex = new SearchIndex(
+      this,
+      this.config.search,
+      new PostgresSearchEngine(this, { tokenizer: this.config.search.tokenizer, schema: this.#schema }),
     );
+    await this.#searchIndex.ensureSchema();
+    this.scheduler.registerInterval(RETRY_INTERVAL_KEY, RETRY_INTERVAL_MS, async () => {
+      await this.#searchIndex.retryPending();
+    });
+  }
+
+  #clientOptions() {
+    return {
+      types: {
+        jsonb: {
+          to: 3802,
+          from: [3802],
+          serialize: (value: unknown) => (typeof value === "string" ? value : JSON.stringify(value)),
+          parse: (raw: string) => raw,
+        },
+        bigint: {
+          to: 20,
+          from: [20],
+          serialize: (value: number) => String(value),
+          parse: (raw: string) => Number(raw),
+        },
+        numeric: {
+          to: 1700,
+          from: [1700],
+          serialize: (value: number) => String(value),
+          parse: (raw: string) => Number(raw),
+        },
+      },
+      onnotice: (notice: { message?: string }) => this.logger.debug(`postgres: ${notice.message ?? ""}`),
+    };
+  }
+
+  async #resolveInsightRole() {
+    if (!this.config.insightUrl) return null;
+    let role: string;
+    try {
+      role = decodeURIComponent(new URL(this.config.insightUrl).username);
+    } catch {
+      role = "";
+    }
+    if (!role) {
+      this.logger.warn("POSTGRES_INSIGHT_URL names no user; no table grants it anything, so insight queries fail");
+      return null;
+    }
+    const found = await this.#client.prepare(`SELECT 1 AS "found" FROM pg_roles WHERE rolname = $1`).get(role);
+    if (!found) this.logger.warn(`POSTGRES_INSIGHT_URL names role "${role}", which does not exist`);
+    return found ? role : null;
+  }
+
+  async #grantInsightSchema() {
+    if (!this.#insightRole) return;
+    const schema = await this.getConnection()
+      .prepare(
+        `SELECT has_schema_privilege($1, n.oid, 'USAGE') AS "granted", pg_has_role(current_user, n.nspowner, 'USAGE') AS "owned" FROM pg_namespace n WHERE n.nspname = $2`,
+      )
+      .get<{ granted: boolean; owned: boolean }>(this.#insightRole, this.#schema);
+    if (!schema || schema.granted) return;
+    if (!schema.owned) {
+      this.logger.warn(
+        `Insight role "${this.#insightRole}" has no USAGE on schema "${this.#schema}", and this role cannot grant it`,
+      );
+      return;
+    }
+    await this.getConnection().execute(
+      `GRANT USAGE ON SCHEMA ${quoteIdent(this.#schema)} TO ${quoteIdent(this.#insightRole)}`,
+    );
+  }
+
+  async grantInsight(table: string) {
+    if (!this.#insightRole) return;
+    const columns = [...BASE_COLUMNS];
+    const granted = await this.getConnection()
+      .prepare(
+        `SELECT bool_and(has_column_privilege($1, to_regclass($2), c, 'SELECT')) AS "granted" FROM unnest($3::text[]) AS c`,
+      )
+      .get<{ granted: boolean | null }>(this.#insightRole, quoteIdent(table), columns);
+    if (granted?.granted) return;
+    await this.getConnection().execute(
+      `GRANT SELECT (${columns.map(quoteIdent).join(", ")}) ON ${quoteIdent(table)} TO ${quoteIdent(this.#insightRole)}`,
+    );
+  }
+
+  async openInsight(): Promise<InsightSession> {
+    if (!this.config.insightUrl)
+      throw new Error(
+        "An insight query on Postgres reads as a login role that can read base columns and nothing else. Create one (`CREATE ROLE <name> LOGIN PASSWORD '…'`, with no other role granted to it) and set POSTGRES_INSIGHT_URL to log in as it; each model table grants it its base columns at boot.",
+      );
+    return await PostgresInsightSession.open({
+      url: this.config.insightUrl,
+      schema: this.#schema,
+      options: this.#clientOptions(),
+    });
   }
 
   override async onDestroy() {
+    this.scheduler.unregisterInterval(RETRY_INTERVAL_KEY);
     await this.#ensures.settle();
     await this.#client?.close();
   }
 
   getConnection() {
-    return this.#client;
+    return this.#transaction.getStore()?.client ?? this.#client;
   }
 
   getSearchIndex() {
-    return null;
+    return this.#searchIndex;
+  }
+
+  stores() {
+    return [...this.#stores.values()];
   }
 
   getStore(constant: ConstantModel, database: DatabaseModel, schema: SchemaOf) {
@@ -364,12 +553,15 @@ export class PostgresDatabase
   }
 
   async getMeta(key: string) {
-    return (await this.#client.prepare(`SELECT "value" FROM "_akan_meta" WHERE "key" = $1`).get<{ value: string }>(key))
-      ?.value;
+    return (
+      await this.getConnection()
+        .prepare(`SELECT "value" FROM "_akan_meta" WHERE "key" = $1`)
+        .get<{ value: string }>(key)
+    )?.value;
   }
 
   async setMeta(key: string, value: string) {
-    await this.#client
+    await this.getConnection()
       .prepare(
         `INSERT INTO "_akan_meta" ("key", "value", "updatedAt") VALUES ($1, $2, $3) ON CONFLICT("key") DO UPDATE SET "value" = excluded."value", "updatedAt" = excluded."updatedAt"`,
       )
@@ -380,18 +572,15 @@ export class PostgresDatabase
     const active = this.#transaction.getStore();
     if (active) return await fn();
     const context: TransactionContext = { afterCommit: [] };
-    return await this.#transaction.run(context, async () => {
-      await this.#client.execute("BEGIN");
-      try {
-        const result = await fn();
-        await this.#client.execute("COMMIT");
-        for (const hook of context.afterCommit) await hook();
-        return result;
-      } catch (err) {
-        await this.#client.execute("ROLLBACK");
-        throw err;
-      }
-    });
+    const result = (await this.#sql.begin(
+      async (transaction) =>
+        await this.#transaction.run(
+          { ...context, client: new PostgresAkanClient(transaction) },
+          async () => await fn(),
+        ),
+    )) as T;
+    for (const hook of context.afterCommit) await hook();
+    return result;
   }
 
   async afterCommit(fn: () => PromiseOrObject<void>) {
@@ -399,4 +588,73 @@ export class PostgresDatabase
     if (!active) return await fn();
     active.afterCommit.push(fn);
   }
+
+  async lockSchema<T>(fn: () => Promise<T>): Promise<T> {
+    const turn = this.#schemaTurn.then(
+      async () =>
+        await this.transaction(async () => {
+          await this.getConnection().execute(
+            `SELECT pg_advisory_xact_lock(hashtext('akan:schema:' || current_schema()))`,
+          );
+          return await fn();
+        }),
+    );
+    this.#schemaTurn = turn.then(
+      () => undefined,
+      () => undefined,
+    );
+    return await turn;
+  }
+
+  async hasTable(table: string) {
+    const row = await this.getConnection()
+      .prepare(`SELECT to_regclass($1) IS NOT NULL AS "exists"`)
+      .get<{ exists: boolean }>(quoteIdent(table));
+    return !!row?.exists;
+  }
+
+  async hasValidIndex(name: string) {
+    const row = await this.getConnection()
+      .prepare(`SELECT indisvalid AS "valid" FROM pg_index WHERE indexrelid = to_regclass($1)`)
+      .get<{ valid: boolean }>(quoteIdent(name));
+    return !!row?.valid;
+  }
+
+  async buildIndexConcurrently({ name, next, create, replace }: ConcurrentIndexBuild) {
+    const reserved = await this.#sql.reserve();
+    const key = `akan:index:${name}`;
+    const valid = async (index: string) =>
+      (
+        await reserved.unsafe(`SELECT indisvalid AS "valid" FROM pg_index WHERE indexrelid = to_regclass($1)`, [
+          quoteIdent(index),
+        ])
+      ).at(0)?.valid as boolean | undefined;
+    try {
+      await reserved.unsafe(`SELECT pg_advisory_lock(hashtext(current_schema() || $1))`, [key]);
+      try {
+        if (!replace) {
+          const state = await valid(name);
+          if (state) return;
+          if (state === false) await reserved.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS ${quoteIdent(name)}`);
+          await reserved.unsafe(create(name));
+          return;
+        }
+        
+        await reserved.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS ${quoteIdent(next)}`);
+        try {
+          await reserved.unsafe(create(next));
+        } catch (error) {
+          await reserved.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS ${quoteIdent(next)}`);
+          throw error;
+        }
+        await reserved.unsafe(
+          `DROP INDEX IF EXISTS ${quoteIdent(name)}; ALTER INDEX ${quoteIdent(next)} RENAME TO ${quoteIdent(name)}`,
+        );
+      } finally {
+        await reserved.unsafe(`SELECT pg_advisory_unlock(hashtext(current_schema() || $1))`, [key]);
+      }
+    } finally {
+      reserved.release();
+    }
+  }
 }