@bevel-software/platform-core-backend 0.20.0 → 0.21.0

package/src/modules/auth/account-admission.ts

@@ -0,0 +1,44 @@
+/**
+ * Whether a NEW account may be provisioned on this deployment, asked before
+ * the row is inserted. The one seam a host that sells seats needs: core
+ * admits everyone, and a cloud overlay answers from its plan without
+ * forking any sign-in path.
+ *
+ * Asked only for an address with no account yet. An existing user's sign-in
+ * is never a provisioning, so a refusal can never lock out someone who is
+ * already in.
+ */
+export type AccountProvisionReason =
+  /** A first sign-in through single sign-on, which provisions on its own. */
+  | 'sso'
+  /** An admin creating an account from the app. */
+  | 'admin-create'
+  /** The deployment owner's first password sign-in, which creates their row. */
+  | 'bootstrap'
+  /** A verified identity from an embedding surface that needs a row without a session. */
+  | 'embed';
+
+export type AccountAdmissionVerdict = { ok: true } | { ok: false; message: string };
+
+export interface IAccountAdmission {
+  canProvision(email: string, reason: AccountProvisionReason): Promise<AccountAdmissionVerdict>;
+}
+
+/** Core's default: every account is admitted. */
+export const admitEveryone: IAccountAdmission = {
+  canProvision: async () => ({ ok: true }),
+};
+
+/**
+ * The port said no. Carries the port's own words, which the routes surface
+ * to the person or admin who asked, and a 403: the identity was fine, the
+ * deployment has no place for it.
+ */
+export class AccountAdmissionRefusedError extends Error {
+  readonly status = 403;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'AccountAdmissionRefusedError';
+  }
+}

package/src/modules/auth/account.routes.ts

@@ -6,6 +6,7 @@ import { printable } from '../../shared/printable.js';
 const log = logger('accounts');
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { AuthService } from './auth.service.js';
+import { AccountAdmissionRefusedError } from './account-admission.js';
 import { erasedAccountId, type IAccountErasureService } from './account-erasure.service.js';
 import type { IAdminAccessService } from '../admin/admin.interface.js';
 import type { UserAccessRemovalService } from '../access/user-access-removal.service.js';
@@ -64,7 +65,9 @@ export function createAccountRoutes(
       res.status(201).json(user);
     } catch (error) {
       const msg = error instanceof Error ? error.message : 'Unknown error';
-      res.status(400).json({ error: msg });
+      // The deployment has no place for the account (a seat limit, say): the
+      // port's own words, as a refusal rather than a malformed request.
+      res.status(error instanceof AccountAdmissionRefusedError ? 403 : 400).json({ error: msg });
     }
   });
 

package/src/modules/auth/auth.service.ts

@@ -1,10 +1,15 @@
 import jwt from 'jsonwebtoken';
 import { eq } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
-import type { CoreConfig } from '../../core-config.js';
 import { users } from '../database/schema.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
+import {
+  AccountAdmissionRefusedError,
+  admitEveryone,
+  type AccountProvisionReason,
+  type IAccountAdmission,
+} from './account-admission.js';
 import {
   hashPassword,
   verifyPassword,
@@ -84,8 +89,31 @@ export class AuthService {
   constructor(
     private readonly db: Database,
     private readonly config: AuthConfig,
+    /**
+     * Whether a new account may be provisioned — see `account-admission.ts`.
+     * Core admits everyone; a host that sells seats answers from its plan.
+     */
+    private readonly admission: IAccountAdmission = admitEveryone,
   ) {}
 
+  /**
+   * Ask the admission port before an account is CREATED: an address that
+   * already has a row is never asked about, so a refusal cannot lock an
+   * existing user out. The default port is not asked at all, which also
+   * spares the lookup.
+   */
+  private async assertAdmitted(normalizedEmail: string, reason: AccountProvisionReason): Promise<void> {
+    if (this.admission === admitEveryone) return;
+    const [existing] = await this.db
+      .select({ id: users.id })
+      .from(users)
+      .where(eq(users.email, normalizedEmail))
+      .limit(1);
+    if (existing) return;
+    const verdict = await this.admission.canProvision(normalizedEmail, reason);
+    if (!verdict.ok) throw new AccountAdmissionRefusedError(verdict.message);
+  }
+
   /**
    * Password login. Two credential sources, in order:
    *
@@ -155,6 +183,7 @@ export class AuthService {
         throw new Error('Invalid credentials');
       }
       const defaultName = normalizedEmail.split('@')[0] || normalizedEmail;
+      await this.assertAdmitted(normalizedEmail, 'bootstrap');
       const admin = await this.upsertUserByEmail(normalizedEmail, defaultName);
       return { token: this.signToken(admin.id, admin.email), user: this.toClientUser(admin) };
     }
@@ -187,6 +216,7 @@ export class AuthService {
       throw new Error('Sign-in returned an invalid email');
     }
     this.assertAllowedDomain(normalizedEmail);
+    await this.assertAdmitted(normalizedEmail, 'sso');
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
     const user = await this.upsertUserByEmail(normalizedEmail, displayName);
     return { token: this.signToken(user.id, user.email), user: this.toClientUser(user) };
@@ -221,6 +251,7 @@ export class AuthService {
       throw new Error(ENV_ADMIN_PASSWORD_REFUSAL);
     }
     this.assertPasswordPolicy(password);
+    await this.assertAdmitted(normalizedEmail, 'admin-create');
     const suppliedName = (name ?? '').trim();
     const displayName = suppliedName || normalizedEmail.split('@')[0] || normalizedEmail;
     const passwordHash = await hashPassword(password);
@@ -382,6 +413,7 @@ export class AuthService {
   ): Promise<{ id: string; email: string; name: string } | null> {
     const normalizedEmail = canonicalEmail(email ?? '');
     if (!EMAIL_REGEX.test(normalizedEmail)) return null;
+    await this.assertAdmitted(normalizedEmail, 'embed');
     const displayName = (name ?? '').trim() || normalizedEmail.split('@')[0] || normalizedEmail;
     const user = await this.upsertUserByEmail(normalizedEmail, displayName);
     return { id: user.id, email: user.email, name: user.name };

package/src/modules/auth/oidc-auth-provider.ts

@@ -7,6 +7,7 @@ import type { AuthProviderPlugin } from './auth.routes.js';
 import { AUTH_COOKIE_MAX_AGE_S } from './auth.routes.js';
 import { AUTH_COOKIE_NAME } from './auth.middleware.js';
 import type { AuthService } from './auth.service.js';
+import { AccountAdmissionRefusedError } from './account-admission.js';
 import { normalizeIssuerUrl } from '../settings/oidc-check.js';
 
 // Short-lived CSRF state + PKCE verifier for the OAuth round-trip: set before
@@ -319,6 +320,14 @@ export class OidcAuthProvider implements AuthProviderPlugin {
         });
         res.redirect(`${publicFrontendUrl}/auth/oidc/callback#token=${encodeURIComponent(token)}`);
       } catch (error) {
+        // A refused provisioning is not a failed sign-in: the identity was
+        // verified, the deployment has no seat for it. Named so the login
+        // screen can say so instead of "try again".
+        if (error instanceof AccountAdmissionRefusedError) {
+          log.warn('OIDC sign-in refused by the account admission port:', { detail: error.message });
+          fail('admission');
+          return;
+        }
         log.error('OIDC callback error:', { err: error });
         fail('auth');
       }

package/src/modules/connection-probe/connection-probe.service.ts

@@ -399,6 +399,12 @@ export class ConnectionProbeService implements IConnectionProbeService {
   constructor(
     private readonly toolManualService: IToolManualService,
     private readonly secretsVault: ISecretsVaultService,
+    /**
+     * The scope this knowledge base's vault was registered under with the
+     * UTCP variable loader, so a probe's client resolves the caller's secrets
+     * from it — see `secrets-variable-loader.ts`. Default: the single one.
+     */
+    private readonly secretsScope?: string,
   ) {}
 
   async probe(userId: string, userEmail: string, slug: string): Promise<ProbeVerdict | null> {
@@ -556,7 +562,7 @@ export class ConnectionProbeService implements IConnectionProbeService {
       // loader, which is exactly the credential under test.
       const config = new UtcpClientConfigSerializer().validateDict({
         variables: {},
-        load_variables_from: [bevelSecretsLoaderConfig(userId)],
+        load_variables_from: [bevelSecretsLoaderConfig(userId, this.secretsScope)],
       });
       // No late-settle owner: a client that arrives after the deadline has no
       // manual registered and therefore no session, and neither

package/src/modules/database/__tests__/advisory-lock.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { AdvisoryLock, withAdvisoryLock } from '../advisory-lock.js';
+import { AdvisoryLock, advisoryLockKey, withAdvisoryLock } from '../advisory-lock.js';
 import type { Database } from '../connection.js';
 
 /**
@@ -145,3 +145,25 @@ describe('withAdvisoryLock', () => {
     expect(clients[0].releasedWith).toBeInstanceOf(Error);
   });
 });
+
+describe('advisoryLockKey', () => {
+  it('keeps the ids a single-tenant deployment always used when no tenant is named', () => {
+    expect(advisoryLockKey(AdvisoryLock.Migrations)).toBe(AdvisoryLock.Migrations);
+    expect(advisoryLockKey(AdvisoryLock.CommitWorker, '')).toBe(AdvisoryLock.CommitWorker);
+  });
+
+  it('gives each tenant its own key for each lock, stable across calls and inside int4', () => {
+    const a = advisoryLockKey(AdvisoryLock.CommitWorker, 't_acme');
+    const b = advisoryLockKey(AdvisoryLock.CommitWorker, 't_globex');
+    expect(a).toBe(advisoryLockKey(AdvisoryLock.CommitWorker, 't_acme'));
+    expect(a).not.toBe(b);
+    expect(a).not.toBe(AdvisoryLock.CommitWorker);
+    // The two locks of one tenant stay two locks.
+    expect(advisoryLockKey(AdvisoryLock.Migrations, 't_acme')).not.toBe(a);
+    for (const key of [a, b]) {
+      expect(Number.isInteger(key)).toBe(true);
+      expect(key).toBeGreaterThanOrEqual(-(2 ** 31));
+      expect(key).toBeLessThanOrEqual(2 ** 31 - 1);
+    }
+  });
+});

package/src/modules/database/__tests__/connection.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  DEFAULT_DB_SCHEMA,
+  assertSchemaName,
+  assertSearchPath,
+  closeDb,
+  createDb,
+  dbSchemaOf,
+  getDb,
+  type Database,
+} from '../connection.js';
+
+/**
+ * Pools here are never connected: `pg.Pool` opens nothing until a query is
+ * asked of it, so what a handle was built with — the schema its connections
+ * will search, whether two asks share one pool — is observable without a
+ * database, and that is what these cases pin.
+ */
+const URL = 'postgresql://u:p@127.0.0.1:1/never';
+
+const searchPath = (db: Database): string | undefined =>
+  (db.$client.options as { options?: string }).options;
+
+const opened: Database[] = [];
+afterEach(async () => {
+  await Promise.all(opened.splice(0).map((db) => closeDb(db)));
+});
+
+describe('schema per knowledge base', () => {
+  it('searches the schema it was built for, and leaves the default schema to the server', () => {
+    const acme = createDb(URL, { schema: 'acme' });
+    const plain = createDb(URL);
+    opened.push(acme, plain);
+    expect(searchPath(acme)).toBe('-c search_path=acme');
+    expect(dbSchemaOf(acme)).toBe('acme');
+    // Nothing set: an operator's own `search_path` stays in force.
+    expect(searchPath(plain)).toBeUndefined();
+    expect(dbSchemaOf(plain)).toBe(DEFAULT_DB_SCHEMA);
+  });
+
+  it('refuses a schema name that is not a plain lowercase identifier', () => {
+    for (const bad of ['Acme', 'a-b', 'a b', '1abc', 'public; drop schema x', '', 'a'.repeat(64)]) {
+      expect(() => assertSchemaName(bad), bad).toThrow(/schema name/);
+      expect(() => createDb(URL, { schema: bad }), bad).toThrow(/schema name/);
+    }
+    expect(assertSchemaName('t_acme_2')).toBe('t_acme_2');
+  });
+
+  it('refuses the names Postgres and drizzle already own', () => {
+    for (const reserved of ['pg_catalog', 'pg_toast', 'pg_x', 'information_schema', 'drizzle']) {
+      expect(() => assertSchemaName(reserved), reserved).toThrow(/reserved/);
+    }
+    // The default schema is a valid name here: a single-tenant deployment
+    // lives on it. A tenant source refuses it for a tenant, not this guard.
+    expect(assertSchemaName(DEFAULT_DB_SCHEMA)).toBe(DEFAULT_DB_SCHEMA);
+  });
+});
+
+describe('assertSearchPath', () => {
+  const answering = (schema: string | null) => ({
+    execute: async () => ({ rows: [{ schema }] }) as never,
+  });
+
+  it('passes when the server searches the configured schema first', async () => {
+    await expect(assertSearchPath(answering('t_acme'), 't_acme')).resolves.toBeUndefined();
+  });
+
+  it('refuses a connection whose schema a pooler dropped, naming both schemas and the cause', async () => {
+    // What a transaction-mode pooler leaves behind: the startup parameter
+    // never reached the server, so `public` is searched first.
+    await expect(assertSearchPath(answering('public'), 't_acme')).rejects.toThrow(
+      /search "public" first, not the configured schema "t_acme".*transaction-mode pooler/,
+    );
+    await expect(assertSearchPath(answering(null), 't_acme')).rejects.toThrow(/\(none\)/);
+  });
+});
+
+describe('getDb', () => {
+  it('shares one pool per (url, schema) and keeps different schemas apart', () => {
+    const a1 = getDb(URL, { schema: 'acme' });
+    const a2 = getDb(URL, { schema: 'acme' });
+    const b = getDb(URL, { schema: 'globex' });
+    const plain = getDb(URL);
+    opened.push(a1, b, plain);
+    expect(a2).toBe(a1);
+    expect(b).not.toBe(a1);
+    expect(plain).not.toBe(a1);
+    expect(getDb(URL, { schema: DEFAULT_DB_SCHEMA })).toBe(plain);
+  });
+
+  it('opens a fresh pool after the cached one was closed', async () => {
+    const first = getDb(URL, { schema: 'closing' });
+    await closeDb(first);
+    const second = getDb(URL, { schema: 'closing' });
+    opened.push(second);
+    expect(second).not.toBe(first);
+  });
+});

package/src/modules/database/__tests__/migrations-unqualified.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { coreMigrationsDir } from '../../../assets.js';
+
+/**
+ * A knowledge base hosted beside others lives in a schema of its own, found
+ * through `search_path`. A migration that spells `public.` runs against the
+ * wrong schema there — creating the table in `public`, or guarding on a
+ * constraint that lives elsewhere — and the tenant that runs it is the first
+ * to find out. So no migration may name a schema: this reads every file the
+ * runner would, so the rule cannot be forgotten by the next one.
+ */
+describe('core migrations', () => {
+  it('never qualify a table with a schema', async () => {
+    const dir = coreMigrationsDir();
+    const files = (await fs.readdir(dir)).filter((name) => name.endsWith('.sql')).sort();
+    expect(files.length).toBeGreaterThan(0);
+    const offenders: string[] = [];
+    for (const name of files) {
+      const text = await fs.readFile(path.join(dir, name), 'utf8');
+      text.split('\n').forEach((line, i) => {
+        // Bare (`public.users`) and quoted (`"public"."users"`) alike: the
+        // quoted spelling is what drizzle generates, and it is what a live
+        // two-tenant run found still pointing every tenant's foreign keys at
+        // a `public.users` that does not exist there.
+        if (/\bpublic"?\./.test(line)) offenders.push(`${name}:${i + 1}: ${line.trim()}`);
+      });
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/modules/database/advisory-lock.ts

@@ -1,3 +1,4 @@
+import { crc32 } from 'node:zlib';
 import pg from 'pg';
 import type { Database } from './connection.js';
 
@@ -84,6 +85,23 @@ export const AdvisoryLock = {
 
 export type AdvisoryLockId = (typeof AdvisoryLock)[keyof typeof AdvisoryLock];
 
+/**
+ * The second integer of a lock: the lock id, folded with the knowledge base
+ * it belongs to. A process serving several knowledge bases from one database
+ * runs several commit workers and several migration runs, and each must
+ * exclude only its own kind: the migrations lock of tenant A has nothing to
+ * say to tenant B's. An empty `tenantKey` is the single-tenant deployment
+ * and keeps the ids that were always used, so a redeploy's outgoing process
+ * on the older build still contends for the same lock.
+ *
+ * `crc32` for a stable 32-bit spread of the key; XOR keeps every value
+ * inside `int4`. Two tenants whose keys collide serialise against each other
+ * and nothing worse: an over-locking, never an under-locking.
+ */
+export function advisoryLockKey(lock: AdvisoryLockId, tenantKey = ''): number {
+  return tenantKey ? lock ^ crc32(tenantKey) : lock;
+}
+
 /** How long to wait for the lock before giving up and failing the boot. */
 const DEFAULT_WAIT_MS = 60_000;
 
@@ -138,9 +156,10 @@ export async function withAdvisoryLock<T>(
   db: Database,
   lock: AdvisoryLockId,
   fn: () => Promise<T>,
-  opts: { waitMs?: number } = {},
+  opts: { waitMs?: number; tenantKey?: string } = {},
 ): Promise<T> {
   const waitMs = opts.waitMs ?? DEFAULT_WAIT_MS;
+  const key = advisoryLockKey(lock, opts.tenantKey);
   const client = await db.$client.connect();
   // A statement that did not answer in time is STILL RUNNING on this
   // connection — `bounded` gives up waiting, it cannot take the statement
@@ -170,7 +189,7 @@ export async function withAdvisoryLock<T>(
       // parameter. `true` makes the setting transaction-local, so the
       // `rollback` below reverts it.
       await onWire(client.query("select set_config('lock_timeout', $1, true)", [String(waitMs)]), 'setting lock_timeout');
-      await client.query('select pg_advisory_xact_lock($1, $2)', [LOCK_NAMESPACE, lock]);
+      await client.query('select pg_advisory_xact_lock($1, $2)', [LOCK_NAMESPACE, key]);
     } catch (err) {
       if (isLockTimeout(err)) {
         throw new Error(
@@ -215,6 +234,8 @@ export interface LeaseClient {
 }
 
 export interface AdvisoryLeaseOptions {
+  /** The knowledge base this lease belongs to — see {@link advisoryLockKey}. Empty: the single-tenant ids. */
+  tenantKey?: string;
   /** How the lease opens its connection. Default: a `pg.Client` on the pool's connection string. */
   connect?: () => Promise<LeaseClient>;
   /** Bound on the connect and on each query, so an unreachable or half-dead database fails rather than waits. Default 10s. */
@@ -290,7 +311,7 @@ export class AdvisoryLease {
     try {
       const { rows } = await client.query('select pg_try_advisory_lock($1, $2) as held', [
         LOCK_NAMESPACE,
-        this.lock,
+        advisoryLockKey(this.lock, this.opts.tenantKey),
       ]);
       if (rows[0]?.held !== true) {
         await client.end().catch(() => undefined);
@@ -315,7 +336,10 @@ export class AdvisoryLease {
     this.heldFlag = false;
     if (!client) return;
     try {
-      await client.query('select pg_advisory_unlock($1, $2)', [LOCK_NAMESPACE, this.lock]);
+      await client.query('select pg_advisory_unlock($1, $2)', [
+        LOCK_NAMESPACE,
+        advisoryLockKey(this.lock, this.opts.tenantKey),
+      ]);
     } catch {
       // Ending the session below releases the lock regardless.
     } finally {

package/src/modules/database/connection.ts

@@ -1,23 +1,153 @@
+import { sql } from 'drizzle-orm';
 import { drizzle } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './schema.js';
 
-let db: ReturnType<typeof drizzle<typeof schema>> | null = null;
+/**
+ * One database, one schema per knowledge base.
+ *
+ * A single-tenant deployment keeps `public`, exactly as before this option
+ * existed: no `search_path` is set for it, so an operator's own default
+ * (`"$user", public`) is honoured, and the migration ledger stays where
+ * drizzle put it. A knowledge base hosted beside others gets a schema of its
+ * own: every connection of its pool starts with `search_path` pointing at it,
+ * so the unqualified table names the schema module and the migrations use
+ * resolve there and nowhere else. Isolation is then a Postgres object, and a
+ * tenant leaves as `pg_dump -n <schema>`.
+ */
+export const DEFAULT_DB_SCHEMA = 'public';
 
-export function getDb(databaseUrl: string) {
+/**
+ * A schema name this module will put into `search_path`: a plain lowercase
+ * identifier, at most Postgres's 63 characters. Validated rather than quoted,
+ * because the name also travels into `CREATE SCHEMA` and a `pg_dump`
+ * invocation, and a name that needs quoting in one of them is a name that
+ * will be spelled wrong in another.
+ */
+export function assertSchemaName(name: string): string {
+  if (!/^[a-z][a-z0-9_]{0,62}$/.test(name)) {
+    throw new Error(
+      `Database schema name must be a lowercase identifier ([a-z][a-z0-9_]*, at most 63 characters); got "${name}"`,
+    );
+  }
+  // Names Postgres or drizzle already own. `pg_*` would fail at CREATE
+  // SCHEMA anyway; `information_schema` would not, and `drizzle` is where a
+  // deployment on the default schema keeps its migration ledger, so a
+  // knowledge base placed there would share that ledger's home.
+  if (name.startsWith('pg_') || name === 'information_schema' || name === 'drizzle') {
+    throw new Error(`Database schema name "${name}" is reserved`);
+  }
+  return name;
+}
+
+/**
+ * Prove that this handle's connections really search `schema` first, by
+ * asking the server. The schema is set as a startup parameter, and a
+ * transaction- or statement-mode pooler in front of the database (PgBouncer
+ * in those modes, RDS Proxy) either refuses that parameter or resets it
+ * between transactions; every unqualified table name would then resolve to
+ * `public`, and tenants would read each other's rows without a single
+ * error. So a graph refuses to come up on a handle that lost its schema,
+ * which is the failure an operator can see. Only session pooling is
+ * supported in front of a process that serves several knowledge bases.
+ */
+export async function assertSearchPath(db: Pick<Database, 'execute'>, schema: string): Promise<void> {
+  const result = await db.execute(sql`select current_schema() as schema`);
+  const current = (result.rows[0] as { schema?: string } | undefined)?.schema ?? null;
+  if (current !== schema) {
+    throw new Error(
+      `Database connections search "${current ?? '(none)'}" first, not the configured schema "${schema}". ` +
+        'A transaction-mode pooler in front of Postgres drops the search_path startup parameter; ' +
+        'use session pooling, or connect directly.',
+    );
+  }
+}
+
+export interface DbOptions {
+  /** The schema the pool's connections search first. Default {@link DEFAULT_DB_SCHEMA}. */
+  schema?: string;
+  /**
+   * Connections the pool may hold. `pg`'s default (10) suits a process that
+   * serves one knowledge base; a process serving many keeps each pool small,
+   * since the database's `max_connections` is shared by all of them.
+   */
+  max?: number;
+  /** How long an idle connection is kept before the pool closes it. Default: `pg`'s. */
+  idleTimeoutMillis?: number;
+}
+
+/**
+ * A bounded handshake: `pg` waits forever by default for a NEW connection to
+ * come up, so a database that accepts the socket and never finishes the
+ * handshake would hold a boot (the migration lock is the first thing that
+ * asks) with nothing to say and nothing for the restart policy to see. Half
+ * a minute is generous for a handshake and short enough for a failed boot to
+ * be visible. It bounds only that: a checkout queued behind a saturated pool,
+ * or a query on a connection that stopped answering, is the caller's to
+ * bound — the advisory lock does.
+ */
+const CONNECT_TIMEOUT_MS = 30_000;
+
+/**
+ * A NEW pool on `databaseUrl`, searching `opts.schema` first. Not cached:
+ * the caller owns it and ends it with {@link closeDb}. The composition root
+ * of a process that serves one knowledge base goes through {@link getDb}
+ * instead, which caches.
+ */
+export function createDb(databaseUrl: string, opts: DbOptions = {}) {
+  const dbSchema = assertSchemaName(opts.schema ?? DEFAULT_DB_SCHEMA);
+  const pool = new pg.Pool({
+    connectionString: databaseUrl,
+    connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
+    max: opts.max,
+    idleTimeoutMillis: opts.idleTimeoutMillis,
+    // A startup parameter, applied by the server to every connection this
+    // pool opens — not a `SET` run after connecting, which a pooled
+    // connection could outlive. The default schema sets nothing, so an
+    // operator's own `search_path` stays in force there.
+    ...(dbSchema === DEFAULT_DB_SCHEMA ? {} : { options: `-c search_path=${dbSchema}` }),
+  });
+  const db = drizzle(pool, { schema });
+  schemas.set(db, dbSchema);
+  return db;
+}
+
+export type Database = ReturnType<typeof createDb>;
+
+/** The schema a database handle searches first — for the callers that name it in DDL. */
+export function dbSchemaOf(db: Pick<Database, '$client'>): string {
+  return schemas.get(db as Database) ?? DEFAULT_DB_SCHEMA;
+}
+
+const schemas = new WeakMap<Database, string>();
+const cache = new Map<string, Database>();
+
+const cacheKey = (databaseUrl: string, dbSchema: string) => `${dbSchema}\u0000${databaseUrl}`;
+
+/**
+ * The process's pool on `databaseUrl` for `opts.schema`, created on first
+ * use and shared afterwards. One per (url, schema): two handles on the same
+ * schema would be two pools competing for the same connection budget.
+ */
+export function getDb(databaseUrl: string, opts: DbOptions = {}): Database {
+  const dbSchema = assertSchemaName(opts.schema ?? DEFAULT_DB_SCHEMA);
+  const key = cacheKey(databaseUrl, dbSchema);
+  let db = cache.get(key);
   if (!db) {
-    // A bounded handshake: `pg` waits forever by default for a NEW connection
-    // to come up, so a database that accepts the socket and never finishes
-    // the handshake would hold a boot (the migration lock is the first thing
-    // that asks) with nothing to say and nothing for the restart policy to
-    // see. Half a minute is generous for a handshake and short enough for a
-    // failed boot to be visible. It bounds only that: a checkout queued
-    // behind a saturated pool, or a query on a connection that stopped
-    // answering, is the caller's to bound — the advisory lock does.
-    const pool = new pg.Pool({ connectionString: databaseUrl, connectionTimeoutMillis: 30_000 });
-    db = drizzle(pool, { schema });
+    db = createDb(databaseUrl, opts);
+    cache.set(key, db);
   }
   return db;
 }
 
-export type Database = ReturnType<typeof getDb>;
+/**
+ * End a handle's pool and forget it, so a later {@link getDb} for the same
+ * schema opens a fresh one rather than handing out a pool that was ended.
+ * The last step of stopping a knowledge base's graph.
+ */
+export async function closeDb(db: Pick<Database, '$client'>): Promise<void> {
+  for (const [key, cached] of cache) {
+    if (cached === db) cache.delete(key);
+  }
+  await db.$client.end();
+}