@sanoma-ai/workflows 0.11.11 → 0.11.13

package/src/identity-provisioning.ts

@@ -1,5 +1,8 @@
-import { Pool, type PoolClient } from "pg";
+import { and, desc, eq, sql } from "drizzle-orm";
+import { Pool } from "pg";
 import type { IdentityEnrollment } from "./cloud-identity.ts";
+import { type Db, databaseOn, pgCode } from "./db.ts";
+import { identityCredentials, identityDeployments } from "./db/identity.ts";
 
 export type DeploymentIdentity = Omit<IdentityEnrollment, "generation">;
 export interface EnrollIdentity extends IdentityEnrollment {
@@ -44,17 +47,18 @@ export function configuredIdentityProvisioning(
     throw new IdentityProvisioningError("invalid");
   }
   const connectionString = url.href;
-  let pool: Pool | undefined;
+  let db: (Db & { $client: Pool }) | undefined;
   let closed = false;
   let closing: Promise<void> | undefined;
   const store = postgresIdentityProvisioning(async () => {
     if (closed) throw new IdentityProvisioningError("unavailable");
-    if (!pool) {
-      pool = new Pool({ connectionString, max: 5, connectionTimeoutMillis: 10_000, query_timeout: 15_000 });
+    if (!db) {
+      const pool = new Pool({ connectionString, max: 5, connectionTimeoutMillis: 10_000, query_timeout: 15_000 });
       pool.on("error", () => {});
+      db = databaseOn(pool);
     }
     // The control plane needs enrollment writes, never schema or database administration.
-    const { rows } = await pool.query<{ allowed: boolean }>(`SELECT
+    const { rows } = await db.execute<{ allowed: boolean }>(sql`SELECT
       NOT EXISTS (SELECT FROM pg_roles WHERE rolname=current_user AND (rolsuper OR rolcreatedb OR rolcreaterole OR rolbypassrls))
       AND has_schema_privilege('sanoma_identity','USAGE') AND NOT has_schema_privilege('sanoma_identity','CREATE')
       AND has_table_privilege('sanoma_identity.deployments','SELECT')
@@ -66,13 +70,13 @@ export function configuredIdentityProvisioning(
       AND NOT has_table_privilege('sanoma_identity.deployments','DELETE,TRUNCATE,REFERENCES,TRIGGER')
       AND NOT has_table_privilege('sanoma_identity.credentials','DELETE,TRUNCATE,REFERENCES,TRIGGER') AS allowed`);
     if (!rows[0]?.allowed) fail("invalid");
-    return pool;
+    return db;
   }, config);
   return {
     store,
     close() {
       closed = true;
-      return (closing ??= pool?.end() ?? Promise.resolve());
+      return (closing ??= db?.$client.end() ?? Promise.resolve());
     },
   };
 }
@@ -130,7 +134,7 @@ const deadlineOf = (value: string) => {
 
 /** Caller owns a dedicated writer pool; never give this pool to the broker or company code. */
 export function postgresIdentityProvisioning(
-  database: () => Promise<Pick<Pool, "connect">>,
+  database: () => Promise<Db>,
   options: { maxValidityMs: number },
 ): IdentityProvisioning {
   const maximum = options.maxValidityMs;
@@ -138,38 +142,46 @@ export function postgresIdentityProvisioning(
   async function transaction(
     input: DeploymentIdentity,
     create: boolean,
-    run: (db: PoolClient, enabled: boolean, now: number) => Promise<void>,
+    run: (tx: Db, enabled: boolean, now: number) => Promise<void>,
   ) {
     checkIdentity(input);
-    let db: PoolClient | undefined;
     try {
-      db = await (await database()).connect();
-      await db.query("BEGIN");
-      if (create)
-        await db.query(
-          `INSERT INTO sanoma_identity.deployments (id, company, environment, service_account)
-          VALUES ($1,$2,$3,$4) ON CONFLICT (id) DO NOTHING`,
-          [input.deployment, input.company, input.environment, input.serviceAccount],
+      await (
+        await database()
+      ).transaction(async (tx) => {
+        if (create)
+          await tx
+            .insert(identityDeployments)
+            .values({
+              id: input.deployment,
+              company: input.company,
+              environment: input.environment,
+              serviceAccount: input.serviceAccount,
+            })
+            .onConflictDoNothing({ target: identityDeployments.id });
+        // Every writer takes the deployment row lock: enrollment cannot race revocation/retirement.
+        const [row] = await tx
+          .select({
+            deployment: identityDeployments.id,
+            company: identityDeployments.company,
+            environment: identityDeployments.environment,
+            serviceAccount: identityDeployments.serviceAccount,
+            enabled: identityDeployments.enabled,
+          })
+          .from(identityDeployments)
+          .where(eq(identityDeployments.id, input.deployment))
+          .for("update");
+        if (!row || !sameIdentity(row, input)) fail("conflict");
+        const clock = await tx.execute<{ now: number }>(
+          sql`SELECT (extract(epoch FROM clock_timestamp()) * 1000)::float8 AS now`,
         );
-      // Every writer takes the deployment row lock: enrollment cannot race revocation/retirement.
-      const { rows } = await db.query<DeploymentIdentity & { enabled: boolean }>(
-        `SELECT id AS deployment, company, environment, service_account AS "serviceAccount", enabled
-          FROM sanoma_identity.deployments WHERE id=$1 FOR UPDATE`,
-        [input.deployment],
-      );
-      const row = rows[0];
-      if (!row || !sameIdentity(row, input)) fail("conflict");
-      const clock = await db.query<{ now: Date }>("SELECT clock_timestamp() AS now");
-      await run(db, row.enabled, clock.rows[0]!.now.getTime());
-      await db.query("COMMIT");
+        await run(tx, row.enabled, clock.rows[0]!.now);
+      });
     } catch (error) {
-      await db?.query("ROLLBACK").catch(() => {});
       const code = identityProvisioningCode(error);
       if (code) throw new IdentityProvisioningError(code);
-      if ((error as { code?: string })?.code === "23505") throw new IdentityProvisioningError("conflict");
+      if (pgCode(error) === "23505") throw new IdentityProvisioningError("conflict");
       throw new IdentityProvisioningError("unavailable");
-    } finally {
-      db?.release();
     }
   }
   return {
@@ -177,48 +189,64 @@ export function postgresIdentityProvisioning(
       generationOf(input.generation);
       const until = deadlineOf(input.validUntil);
       if (!/^[0-9a-f]{64}$/.test(input.hash)) fail("invalid");
-      await transaction(input, true, async (db, enabled, now) => {
+      await transaction(input, true, async (tx, enabled, now) => {
         if (!enabled) fail("conflict");
         if (until <= now || until - now > maximum) fail("invalid");
-        const { rows } = await db.query<{ generation: string; hash: string; valid_until: Date; revoked: boolean }>(
-          `SELECT generation, hash, valid_until, revoked FROM sanoma_identity.credentials
-            WHERE deployment=$1 ORDER BY generation DESC`,
-          [input.deployment],
-        );
-        const existing = rows.find((r) => Number(r.generation) === input.generation);
+        const rows = await tx
+          .select({
+            generation: identityCredentials.generation,
+            hash: identityCredentials.hash,
+            validUntil: identityCredentials.validUntil,
+            revoked: identityCredentials.revoked,
+          })
+          .from(identityCredentials)
+          .where(eq(identityCredentials.deployment, input.deployment))
+          .orderBy(desc(identityCredentials.generation));
+        const existing = rows.find((r) => r.generation === input.generation);
         if (existing) {
           // An exact retry is safe. Never extend a retired generation or revive a revoked one.
-          if (existing.hash !== input.hash || existing.revoked || existing.valid_until.getTime() !== until)
+          if (existing.hash !== input.hash || existing.revoked || existing.validUntil.getTime() !== until)
             fail("conflict");
           return;
         }
-        if (rows[0] && Number(rows[0].generation) >= input.generation) fail("conflict");
-        await db.query(
-          `INSERT INTO sanoma_identity.credentials (hash, deployment, generation, valid_until)
-            VALUES ($1,$2,$3,$4)`,
-          [input.hash, input.deployment, input.generation, new Date(until)],
-        );
+        if (rows[0] && rows[0].generation >= input.generation) fail("conflict");
+        await tx.insert(identityCredentials).values({
+          hash: input.hash,
+          deployment: input.deployment,
+          generation: input.generation,
+          validUntil: new Date(until),
+        });
       });
     },
     async retire(input) {
       generationOf(input.generation);
       const until = deadlineOf(input.validUntil);
-      await transaction(input, false, async (db) => {
+      await transaction(input, false, async (tx) => {
         // Retirement only shortens access. The predicate protects the schema's finite interval.
-        const result = await db.query(
-          `UPDATE sanoma_identity.credentials SET
-            revoked=revoked OR $3::timestamptz <= clock_timestamp(),
-            valid_until=CASE WHEN $3::timestamptz > valid_from THEN LEAST(valid_until,$3::timestamptz) ELSE valid_until END
-            WHERE deployment=$1 AND generation=$2`,
-          [input.deployment, input.generation, new Date(until)],
-        );
-        if (!result.rowCount) fail("conflict");
+        const deadline = sql`${new Date(until).toISOString()}::timestamptz`;
+        const updated = await tx
+          .update(identityCredentials)
+          .set({
+            revoked: sql`${identityCredentials.revoked} OR ${deadline} <= clock_timestamp()`,
+            validUntil: sql`CASE WHEN ${deadline} > ${identityCredentials.validFrom} THEN LEAST(${identityCredentials.validUntil}, ${deadline}) ELSE ${identityCredentials.validUntil} END`,
+          })
+          .where(
+            and(
+              eq(identityCredentials.deployment, input.deployment),
+              eq(identityCredentials.generation, input.generation),
+            ),
+          )
+          .returning({ hash: identityCredentials.hash });
+        if (!updated.length) fail("conflict");
       });
     },
     async revoke(input) {
-      await transaction(input, false, async (db) => {
+      await transaction(input, false, async (tx) => {
         // Terminal for this deployment id. A new enrollment cannot silently re-enable it.
-        await db.query("UPDATE sanoma_identity.deployments SET enabled=false WHERE id=$1", [input.deployment]);
+        await tx
+          .update(identityDeployments)
+          .set({ enabled: false })
+          .where(eq(identityDeployments.id, input.deployment));
       });
     },
   };

package/src/identity-service.ts

@@ -1,7 +1,10 @@
 import { createServer } from "node:http";
 import type { AddressInfo } from "node:net";
+import { sql } from "drizzle-orm";
 import { Pool } from "pg";
 import { NodeRequest, sendNodeResponse } from "srvx/node";
+import { type Db, databaseOn } from "./db.ts";
+import { identityAuditEvents } from "./db/identity.ts";
 import {
   identityBroker,
   postgresIdentityEnrollments,
@@ -54,8 +57,8 @@ const poolFor = (connectionString: string) => {
   return pool;
 };
 
-async function checkRoles(reader: Pool, audit: Pool): Promise<void> {
-  const read = await reader.query<{ allowed: boolean }>(`SELECT
+async function checkRoles(reader: Db, audit: Db): Promise<void> {
+  const read = await reader.execute<{ allowed: boolean }>(sql`SELECT
     has_schema_privilege('sanoma_identity', 'USAGE') AND
     NOT has_schema_privilege('sanoma_identity', 'CREATE') AND
     NOT EXISTS (SELECT FROM pg_roles WHERE rolname = current_user AND (rolsuper OR rolcreaterole OR rolcreatedb OR rolbypassrls)) AND
@@ -63,7 +66,7 @@ async function checkRoles(reader: Pool, audit: Pool): Promise<void> {
     has_table_privilege('sanoma_identity.credentials', 'SELECT') AND
     NOT has_table_privilege('sanoma_identity.deployments', 'INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER') AND
     NOT has_table_privilege('sanoma_identity.credentials', 'INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER') AS allowed`);
-  const write = await audit.query<{ allowed: boolean }>(`SELECT
+  const write = await audit.execute<{ allowed: boolean }>(sql`SELECT
     has_schema_privilege('sanoma_identity', 'USAGE') AND
     NOT has_schema_privilege('sanoma_identity', 'CREATE') AND
     NOT EXISTS (SELECT FROM pg_roles WHERE rolname = current_user AND (rolsuper OR rolcreaterole OR rolcreatedb OR rolbypassrls)) AND
@@ -94,26 +97,23 @@ export async function startIdentityService(options: IdentityServiceOptions): Pro
     let active = 0;
     reader = poolFor(options.enrollmentDatabaseUrl);
     audit = poolFor(options.auditDatabaseUrl);
-    await checkRoles(reader, audit);
+    const readerDb = databaseOn(reader);
+    const auditDb = databaseOn(audit);
+    await checkRoles(readerDb, auditDb);
     const record = async (event: IdentityAudit) => {
       const e = event.enrollment;
       // Fixed columns only: no tokens, hashes, headers or arbitrary caller fields.
-      await audit!.query(
-        `INSERT INTO sanoma_identity.audit_events
-        (result, deployment, company, environment, service_account, generation, expires_at)
-        VALUES ($1,$2,$3,$4,$5,$6,$7)`,
-        [
-          event.result,
-          e?.deployment ?? null,
-          e?.company ?? null,
-          e?.environment ?? null,
-          e?.serviceAccount ?? null,
-          e?.generation ?? null,
-          event.expiresAt === undefined ? null : new Date(event.expiresAt),
-        ],
-      );
+      await auditDb.insert(identityAuditEvents).values({
+        result: event.result,
+        deployment: e?.deployment,
+        company: e?.company,
+        environment: e?.environment,
+        serviceAccount: e?.serviceAccount,
+        generation: e?.generation,
+        expiresAt: event.expiresAt === undefined ? null : new Date(event.expiresAt),
+      });
     };
-    const enrollments = postgresIdentityEnrollments(async () => reader!);
+    const enrollments = postgresIdentityEnrollments(async () => readerDb);
     const handle =
       options.mode.type === "runtime"
         ? identityBroker({ enrollments, issue: attachedGoogleTokenIssuer(), audit: record })

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   type Connector,
   type ConnectorSetup,
   type ConnectorVendor,
+  type DatabasePreparation,
   type Driver,
   type DriverEnv,
   type DriverFn,
@@ -212,6 +213,8 @@ export {
   deriveHosts,
   type HostFacts,
   hostFacts,
+  type HostRootFacts,
+  hostRootFacts,
   DEPLOY_KEY_TITLE,
   DEPLOY_KEY_TYPE,
   GITHUB_APP,

package/src/kms-secrets.ts

@@ -1,7 +1,9 @@
 import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:crypto";
 import type { protos } from "@google-cloud/kms";
 import crc32c from "crc-32/crc32c.js";
+import { and, eq, sql } from "drizzle-orm";
 import type { Db } from "./db.ts";
+import { kmsSecrets } from "./db/kms.ts";
 import { cloudIdentityAuth } from "./cloud-identity.ts";
 import {
   SecretStoreError,
@@ -58,7 +60,7 @@ export interface KmsPostgresOptions {
   database?: () => Promise<Db>;
 }
 
-interface Envelope {
+export interface Envelope {
   format: "sanoma-gcp-kms-v1";
   key: string;
   keyVersion: string;
@@ -67,12 +69,17 @@ interface Envelope {
   ciphertext: string;
   tag: string;
 }
-interface Row {
-  version: string;
-  envelope: Envelope;
-  updated_by: string;
-  updated_at: Date;
-}
+const columns = {
+  version: kmsSecrets.version,
+  envelope: kmsSecrets.envelope,
+  updatedBy: kmsSecrets.updatedBy,
+  updatedAt: kmsSecrets.updatedAt,
+};
+type Row = Pick<typeof kmsSecrets.$inferSelect, keyof typeof columns>;
+const at = (company: string, address: SecretAddress) =>
+  and(eq(kmsSecrets.company, company), eq(kmsSecrets.namespace, address.namespace), eq(kmsSecrets.path, address.path));
+/** The row of `version`, compared as text: an expected version that is no uuid matches nothing. */
+const versionIs = (version: string) => sql`${kmsSecrets.version}::text = ${version}`;
 const FORMAT = "sanoma-gcp-kms-v1";
 const MAX_BYTES = 65_536;
 const capabilities = Object.freeze({
@@ -245,7 +252,8 @@ export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore | Sec
     }
   };
   const open = async (address: SecretAddress, row: Row): Promise<SecretValue> => {
-    const e = row.envelope;
+    // A JSON `null` is a jsonb value the column takes: an envelope written by hand, not one of ours.
+    const e = row.envelope as Envelope | null;
     if (!e || e.format !== FORMAT || !keys.has(e.key) || !versionOf(e.keyVersion, e.key))
       throw new SecretStoreError("invalid_value");
     const nonce = bytes(e.nonce, 12),
@@ -280,8 +288,8 @@ export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore | Sec
         return {
           value: plaintext.toString("utf8"),
           version: row.version,
-          updatedBy: row.updated_by,
-          updatedAt: row.updated_at.toISOString(),
+          updatedBy: row.updatedBy,
+          updatedAt: row.updatedAt.toISOString(),
         };
       } finally {
         plaintext.fill(0);
@@ -300,33 +308,35 @@ export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore | Sec
           value = randomUUID();
         const envelope = await seal(address, value, version);
         const db = await database();
-        const scope = [company, namespace, address.path, version];
+        const exact = and(at(company, address), eq(kmsSecrets.version, version));
         let removed = false;
         try {
-          const created = await db.query(
-            "INSERT INTO sanoma_kms.secrets(company,namespace,path,version,envelope,updated_by) VALUES($1,$2,$3,$4,$5,'validation') ON CONFLICT(company,namespace,path) DO NOTHING RETURNING version",
-            [...scope, JSON.stringify(envelope)],
-          );
-          if (created.rowCount !== 1) throw new SecretStoreError("conflict");
-          const updated = await db.query(
-            "UPDATE sanoma_kms.secrets SET envelope=$5,version=$4,updated_by='validation',updated_at=now() WHERE company=$1 AND namespace=$2 AND path=$3 AND version=$4 RETURNING version",
-            [...scope, JSON.stringify(envelope)],
-          );
-          if (updated.rowCount !== 1) throw new SecretStoreError("unavailable");
-          const stored = await db.query<Row>(
-            "SELECT version,envelope,updated_by,updated_at FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3 AND version=$4",
-            scope,
-          );
-          if (!stored.rows[0] || (await open(address, stored.rows[0])).value !== value)
-            throw new SecretStoreError("invalid_value");
+          const created = await db
+            .insert(kmsSecrets)
+            .values({
+              company,
+              namespace: address.namespace,
+              path: address.path,
+              version,
+              envelope,
+              updatedBy: "validation",
+            })
+            .onConflictDoNothing()
+            .returning({ version: kmsSecrets.version });
+          if (created.length !== 1) throw new SecretStoreError("conflict");
+          const updated = await db
+            .update(kmsSecrets)
+            .set({ envelope, version, updatedBy: "validation" })
+            .where(exact)
+            .returning({ version: kmsSecrets.version });
+          if (updated.length !== 1) throw new SecretStoreError("unavailable");
+          const [stored] = await db.select(columns).from(kmsSecrets).where(exact);
+          if (!stored || (await open(address, stored)).value !== value) throw new SecretStoreError("invalid_value");
         } finally {
           // Also clean up a committed INSERT whose response was lost. The random address and
           // exact version prevent one concurrent probe from deleting another probe or a secret.
-          const cleanup = await db.query(
-            "DELETE FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3 AND version=$4",
-            scope,
-          );
-          removed = cleanup.rowCount === 1;
+          const cleanup = await db.delete(kmsSecrets).where(exact).returning({ version: kmsSecrets.version });
+          removed = cleanup.length === 1;
         }
         if (!removed) throw new SecretStoreError("unavailable");
         // Own-key usability only. Cross-company authorization requires live IAM proof with another existing key.
@@ -334,13 +344,8 @@ export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore | Sec
     read: (address) =>
       safe(async () => {
         context(address, "read");
-        const { rows } = await (
-          await database()
-        ).query<Row>(
-          "SELECT version,envelope,updated_by,updated_at FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3",
-          [company, address.namespace, address.path],
-        );
-        return rows[0] && open(address, rows[0]);
+        const [row] = await (await database()).select(columns).from(kmsSecrets).where(at(company, address));
+        return row && open(address, row);
       }),
     write: (address, value, { expectedVersion, by }) =>
       safe(async () => {
@@ -348,30 +353,33 @@ export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore | Sec
         if (!nonempty(by)) throw new SecretStoreError("invalid_value");
         const version = randomUUID(),
           envelope = await seal(address, value, version);
-        const args = [company, address.namespace, address.path, version, JSON.stringify(envelope), by];
-        const sql =
+        const db = await database();
+        const [row] =
           expectedVersion === null
-            ? "INSERT INTO sanoma_kms.secrets(company,namespace,path,version,envelope,updated_by) VALUES($1,$2,$3,$4,$5,$6) ON CONFLICT(company,namespace,path) DO NOTHING RETURNING version,envelope,updated_by,updated_at"
-            : "UPDATE sanoma_kms.secrets SET version=$4,envelope=$5,updated_by=$6,updated_at=now() WHERE company=$1 AND namespace=$2 AND path=$3 AND version::text=$7 RETURNING version,envelope,updated_by,updated_at";
-        const { rows } = await (
-          await database()
-        ).query<Row>(sql, expectedVersion === null ? args : [...args, expectedVersion]);
-        if (!rows[0]) throw new SecretStoreError("conflict");
+            ? await db
+                .insert(kmsSecrets)
+                .values({ company, namespace: address.namespace, path: address.path, version, envelope, updatedBy: by })
+                .onConflictDoNothing()
+                .returning({ updatedAt: kmsSecrets.updatedAt })
+            : await db
+                .update(kmsSecrets)
+                .set({ version, envelope, updatedBy: by })
+                .where(and(at(company, address), versionIs(expectedVersion)))
+                .returning({ updatedAt: kmsSecrets.updatedAt });
+        if (!row) throw new SecretStoreError("conflict");
         // Return the caller's value, never make a second decrypt after a successful commit.
-        return { value, version, updatedBy: by, updatedAt: rows[0].updated_at.toISOString() };
+        return { value, version, updatedBy: by, updatedAt: row.updatedAt.toISOString() };
       }),
     delete: (address, { expectedVersion }) =>
       safe(async () => {
         context(address, expectedVersion);
-        const { rowCount } = await (
+        const deleted = await (
           await database()
-        ).query("DELETE FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3 AND version::text=$4", [
-          company,
-          address.namespace,
-          address.path,
-          expectedVersion,
-        ]);
-        if (!rowCount) throw new SecretStoreError("conflict");
+        )
+          .delete(kmsSecrets)
+          .where(and(at(company, address), versionIs(expectedVersion)))
+          .returning({ version: kmsSecrets.version });
+        if (!deleted.length) throw new SecretStoreError("conflict");
       }),
   };
 }

package/src/ledger.ts

@@ -3,9 +3,11 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { eq, sql } from "drizzle-orm";
 import { setTimeout as delay } from "node:timers/promises";
 import { isDeepStrictEqual } from "node:util";
-import { type Db, LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
+import { type Db, lazyDb, pgCode } from "./db.ts";
+import { ledger } from "./db/company.ts";
 import type { Approver, Principal } from "./define.ts";
 import { type ErrorInfo, isFinal, keepCode } from "./errors.ts";
 import { shown, warn } from "./log.ts";
@@ -372,29 +374,31 @@ const DATA_EXCEPTION = /^22/;
  * Keeps records in the `sanoma_ledger` table of the database at `databaseUrl`, beside DBOS's
  * tables: the default store, which the worker, the app and the client share through Postgres.
  * The database and the table are made on first use when they are not there (`prepareDatabase`).
- * The pool is opened on first use and ended by `close()`, after which the store refuses use.
+ * Its connections are opened on first use and ended by `close()`, after which the store refuses use.
  */
 export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Promise<void> } {
-  const pool = lazyPool(databaseUrl, "ledger");
+  const store = lazyDb(databaseUrl, "ledger");
 
   return {
     async append(record) {
-      const conn = await pool.db();
-      if (await insertRecord(conn, record)) return;
+      const db = await store.db();
+      if (await insertRecord(db, record)) return;
       // Another write of the id was first: the record it stored stands.
-      const { rows } = await conn.query<{ record: LedgerRecord }>(`SELECT record FROM ${TABLE} WHERE id = $1`, [
-        record.id,
-      ]);
-      if (rows[0]) warnIfDifferent(rows[0].record, lineOf(record));
+      const [stored] = await db.select({ record: ledger.record }).from(ledger).where(eq(ledger.id, record.id));
+      if (stored) warnIfDifferent(stored.record, lineOf(record));
     },
     async read(runId) {
-      const { rows } = await (
-        await pool.db()
-      ).query<{ record: LedgerRecord }>(`SELECT record FROM ${TABLE} WHERE run_id = $1 ORDER BY seq, n`, [runId]);
+      const rows = await (
+        await store.db()
+      )
+        .select({ record: ledger.record })
+        .from(ledger)
+        .where(eq(ledger.runId, runId))
+        .orderBy(ledger.seq, ledger.n);
       // In seq order, as the other stores read; two records of one seq in write order.
       return rows.map((r) => r.record);
     },
-    close: pool.close,
+    close: store.close,
   };
 }
 
@@ -404,18 +408,19 @@ export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Pr
  * (`SanomaClient.call`) inside the transaction that saves its record.
  */
 export async function insertRecord(db: Db, record: LedgerRecord): Promise<boolean> {
+  // The record's JSON, written once, as `jsonlLedger` writes it: what can't be JSON is refused as it refuses it.
   const inserted = await db
-    .query(
-      `INSERT INTO ${TABLE} (id, run_id, seq, record) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (id) DO NOTHING RETURNING n`,
-      [record.id, record.runId, record.seq, lineOf(record)],
-    )
+    .insert(ledger)
+    .values({ id: record.id, runId: record.runId, seq: record.seq, record: sql`${serialize(record)}::jsonb` })
+    .onConflictDoNothing({ target: ledger.id })
+    .returning({ n: ledger.n })
     .catch((err: unknown) => {
       if (DATA_EXCEPTION.test(pgCode(err))) {
         throw final(`Ledger record ${record.id} can't be stored: ${errorMessage(err)}`, err);
       }
       throw err;
     });
-  return inserted.rows.length > 0;
+  return inserted.length > 0;
 }
 
 /** Keeps records in memory, for tests. */

package/src/op.ts

@@ -1,3 +1,4 @@
+import type { Pool } from "pg";
 import type { Principal } from "./define.ts";
 import type { Authentication, CallAuthentication } from "./authentication.ts";
 import type { ConnectionSnapshot } from "./connection.ts";
@@ -336,9 +337,15 @@ export interface ConnectorSetup {
   fake?: () => Fake<any, any>;
   /** The connector's steps for Gherkin tests (`defineSteps`): a config's scenarios and the connector's own features can use them. */
   steps?: Steps;
+  /**
+   * Makes the connector's tables on the company's database (a login's): by the worker at its
+   * start, after the runtime's own tables, on the database's direct URL (`DatabasePreparation`);
+   * idempotent. The app never makes them: a login opened before they are there refuses.
+   */
+  prepare?: DatabasePreparation;
   /**
    * Makes the connector's login half for one public site: once per site, by the app, when it
-   * starts; a login that needs tables migrates them here (serialized, idempotent).
+   * starts, on the tables `prepare` made.
    */
   login?: (context: LoginContext) => LoginHalf | Promise<LoginHalf>;
   /**
@@ -370,6 +377,14 @@ export interface LoginIdentity {
   github?: string;
 }
 
+/**
+ * Makes what a connector keeps on the company's database (`ConnectorSetup.prepare`): run by the
+ * worker at its start, once the runtime's own tables are there, with the database's direct URL,
+ * never through a pooler (an advisory lock is one connection's); idempotent, and safe for two
+ * workers at once.
+ */
+export type DatabasePreparation = (databaseUrl: string) => Promise<void>;
+
 /** How a login half lets a person in: an email code, GitHub, an invite link, an email and a password. */
 export type LoginMethod = "code" | "github" | "invite" | "password";
 
@@ -386,8 +401,14 @@ export interface SocialClients {
  * public site, once per site; for the staff login, once, with `staff`.
  */
 export interface LoginContext {
-  /** The company's database (`resolved.databaseUrl`), where a login like Better Auth keeps its users. */
-  databaseUrl: string;
+  /**
+   * The company's database, as the app's client reaches it (`SanomaClient.pool`): the pool a login
+   * like Better Auth keeps its users on, once the database is prepared. On Node it is the app's
+   * one pool for as long as the app runs; on a Worker it is the request's own, ended with the
+   * response. A login keeps one instance per pool and nothing else across requests, since the
+   * next request may bring another pool.
+   */
+  database(): Promise<Pool>;
   /**
    * A 32-byte key derived from the deployment's `SANOMA_SIGNING_KEY` for this login (HKDF-SHA256,
    * purpose `login <connector>`), hex; a login signs its cookies with it and never asks a person for a secret.
@@ -454,8 +475,10 @@ export function sameOrigin(request: Request): boolean {
 /**
  * A connector's login half: how a public site tells who a visitor is, and, made with
  * `LoginContext.staff`, how the app's staff sign in. The app makes one with `login(context)` once
- * per public site (and once for staff), when it starts; a login that keeps tables in the database
- * migrates them itself there, serialized and idempotent. It answers the provider's subject and
+ * per public site (and once for staff), when it starts, which opens nothing: a login reaches the
+ * database through `context.database` as requests come, and a login that keeps tables there has
+ * its connector's `prepare` make them, which the worker runs, and only checks for them. It
+ * answers the provider's subject and
  * what it verified; the app makes the principal from it (`visitor:<connector>:<subject>`, in
  * `visitors`, or the declared person the identity matches), so a connector never sets groups. A
  * visitor's address, for rate limits, is the `CLIENT_IP_HEADER` header.
@@ -484,7 +507,6 @@ export interface LoginHalf {
    * signs them in with it, using it up.
    */
   invitation?(token: string): Promise<{ email: string; path: string } | undefined>;
-  close?(): Promise<void>;
 }
 
 /** How long an invite lasts: 24 hours. */