pipework 0.251.0 → 0.252.1

package/src/test/crawl-fixture.ts

@@ -0,0 +1,157 @@
+import { createServer, type IncomingHttpHeaders, type IncomingMessage, type ServerResponse } from 'node:http'
+import { connect as netConnect, type AddressInfo, type Socket } from 'node:net'
+import { readFile, stat } from 'node:fs/promises'
+import { extname, join, normalize, sep } from 'node:path'
+import type { FetchTarget } from '../infra/fetch/index.js'
+
+const PUBLIC_ADDRESS = '93.184.216.34'
+
+const TYPES: Record<string, string> = {
+  '.html': 'text/html', '.htm': 'text/html', '.xhtml': 'application/xhtml+xml', '.txt': 'text/plain',
+  '.pdf': 'application/pdf', '.xml': 'application/xml', '.css': 'text/css', '.js': 'text/javascript',
+  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
+}
+
+/** What one path of a fixture site does instead of serving a file. */
+export interface CrawlFixtureRoute {
+  /** Answer with a redirect to this URL (status 302 unless `status` is given). */
+  readonly redirect?: string
+  /** Answer with this status and no body (with `redirect`: the redirect's status). */
+  readonly status?: number
+  /** Wait this long before answering. */
+  readonly delayMs?: number
+  /** Answer 200 with this many generated bytes, streamed and never on disk, without a Content-Length. */
+  readonly bytes?: number
+  /** Content type of the generated bytes; default `application/pdf`. */
+  readonly contentType?: string
+}
+
+export interface CrawlFixtureOptions {
+  /** The directory served as every host's site: `/` is `index.html`, `/robots.txt` is the file of that name. Files carry an ETag and Last-Modified, and an `If-None-Match` that matches is answered 304. */
+  readonly root: string
+  /** The names that resolve, each to a fake public address (or the address given); any other name does not resolve. */
+  readonly hosts: readonly string[] | Readonly<Record<string, string>>
+  /** Per-path behaviour, keyed by the URL's path (`/big.pdf`), or by host and path (`example.test/`) for one host only; the host form wins. */
+  readonly routes?: Readonly<Record<string, CrawlFixtureRoute>>
+}
+
+/** One request the fixture server received. */
+export interface CrawlFixtureRequest {
+  readonly method: string
+  /** The Host header without the port. */
+  readonly host: string
+  /** Path and query. */
+  readonly path: string
+  /** `Date.now()` when the request arrived. */
+  readonly at: number
+  readonly headers: IncomingHttpHeaders
+}
+
+export interface CrawlFixtureSite {
+  /** Pass as the `network` option of `crawl.create` (or `untrustedFetch.get`'s `resolve` and `connect`). */
+  readonly network: {
+    resolve: (hostname: string) => Promise<string[]>
+    connect: (target: FetchTarget) => Socket
+  }
+  /** Every request received, oldest first. */
+  readonly requests: CrawlFixtureRequest[]
+  close(): Promise<void>
+}
+
+function safePath(root: string, urlPath: string): string | null {
+  let decoded: string
+  try { decoded = decodeURIComponent(urlPath) } catch { return null }
+  const full = normalize(join(root, decoded))
+  const base = normalize(root)
+  return full === base || full.startsWith(base.endsWith(sep) ? base : base + sep) ? full : null
+}
+
+async function serveFile(root: string, pathname: string, req: IncomingMessage, res: ServerResponse): Promise<void> {
+  let file = safePath(root, pathname)
+  if (file === null) { res.statusCode = 400; res.end(); return }
+  try {
+    if ((await stat(file)).isDirectory()) file = join(file, 'index.html')
+    const info = await stat(file)
+    const etag = `"${info.size.toString(16)}-${Math.floor(info.mtimeMs).toString(16)}"`
+    res.setHeader('etag', etag)
+    res.setHeader('last-modified', info.mtime.toUTCString())
+    if (req.headers['if-none-match'] === etag) { res.statusCode = 304; res.end(); return }
+    const body = await readFile(file)
+    res.setHeader('content-type', TYPES[extname(file).toLowerCase()] ?? 'application/octet-stream')
+    res.end(body)
+  } catch {
+    res.statusCode = 404
+    res.setHeader('content-type', 'text/plain')
+    res.end('not found')
+  }
+}
+
+function streamBytes(res: ServerResponse, total: number, contentType: string): void {
+  res.setHeader('content-type', contentType)
+  const chunk = Buffer.alloc(64 * 1024, 0x25)
+  let sent = 0
+  let closed = false
+  res.on('close', () => { closed = true })
+  const pump = (): void => {
+    while (!closed && sent < total) {
+      const piece = sent + chunk.length <= total ? chunk : chunk.subarray(0, total - sent)
+      sent += piece.length
+      if (!res.write(piece)) { res.once('drain', pump); return }
+    }
+    if (!closed) res.end()
+  }
+  pump()
+}
+
+/**
+ * Serves a directory as a website on a local server, for testing a crawl with no outside fetch. `network` makes the
+ * hosts in `hosts` resolve to a fake public address and sends their connections to the local server, so the real
+ * address rules still run: a host not in `hosts` (such as `127.0.0.1`) is refused as it would be live. Use plain
+ * `http://<host>/` URLs; the port is the fixture's. Every request is recorded in `requests`.
+ */
+export async function crawlFixtureSite(options: CrawlFixtureOptions): Promise<CrawlFixtureSite> {
+  const addresses: Record<string, string> = Array.isArray(options.hosts)
+    ? Object.fromEntries((options.hosts as readonly string[]).map(h => [h, PUBLIC_ADDRESS]))
+    : { ...(options.hosts as Record<string, string>) }
+  const requests: CrawlFixtureRequest[] = []
+  const sockets = new Set<Socket>()
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', 'http://fixture.invalid')
+    const host = (req.headers.host ?? '').replace(/:\d+$/, '')
+    requests.push({ method: req.method ?? 'GET', host, path: url.pathname + url.search, at: Date.now(), headers: req.headers })
+    const route = options.routes?.[`${host}${url.pathname}`] ?? options.routes?.[url.pathname]
+    const respond = async (): Promise<void> => {
+      if (route?.redirect !== undefined) {
+        res.statusCode = route.status ?? 302
+        res.setHeader('location', route.redirect)
+        res.end()
+      } else if (route?.bytes !== undefined) {
+        streamBytes(res, route.bytes, route.contentType ?? 'application/pdf')
+      } else if (route?.status !== undefined) {
+        res.statusCode = route.status
+        res.end()
+      } else {
+        await serveFile(options.root, url.pathname, req, res)
+      }
+    }
+    if (route?.delayMs !== undefined) setTimeout(() => { void respond() }, route.delayMs)
+    else void respond()
+  })
+  server.on('connection', s => { sockets.add(s); s.on('close', () => sockets.delete(s)) })
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+  const port = (server.address() as AddressInfo).port
+  return {
+    network: {
+      resolve: (hostname) => {
+        const found = addresses[hostname]
+        return found === undefined ? Promise.reject(new Error('ENOTFOUND')) : Promise.resolve([found])
+      },
+      connect: () => netConnect(port, '127.0.0.1'),
+    },
+    requests,
+    close: async () => {
+      for (const s of sockets) s.destroy()
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    },
+  }
+}

package/src/test/discover-fork.ts

@@ -0,0 +1,17 @@
+import type { Manifold } from '../core/pipework.js'
+import { discoverInstance } from '../core/config/discover.js'
+
+/**
+ * Load this test fork's manifold and consume `PIPEWORK_CONFIG`.
+ *
+ * The override has exactly one reader: this fork's discovery. It is unset once
+ * that read succeeds, so nothing a test spawns — another package's `pipework
+ * migrate`, a CLI under test — inherits it and migrates the wrong package
+ * against the wrong manifold. Discovery failing leaves it set: the variable is
+ * part of the diagnosis.
+ */
+export async function discoverForTestFork(): Promise<Manifold> {
+  const instance = await discoverInstance()
+  delete process.env['PIPEWORK_CONFIG']
+  return instance
+}

package/src/test/fingerprint.ts

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto'
+import { readdirSync, readFileSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import type { Blueprint } from '../core/config/schema.js'
+import type { ResolvedDatabase } from '../core/config/index.js'
+import { VERSION } from '../core/runtime/broker.js'
+
+// The template is keyed by its CONTENT, not by the run that happened to build
+// it. Every input that changes what ends up inside a template database is
+// folded into one hash, and that hash becomes the template's name — so a
+// migration edit does not invalidate a template, it simply asks for a
+// different one, and the stale one is reaped because nobody asks for it again.
+//
+// Content keying is what lets a template outlive the process that built it:
+// a vitest run with `pool: 'forks'` + `isolate: true` gives every test file a
+// fresh process, and a per-process key (pid, run nonce) meant every one of them
+// replayed the whole migration stack. Issue #340.
+
+/** Bump when pipework changes the SHAPE of what it puts in a template. */
+const TEMPLATE_FORMAT_VERSION = 2
+
+/**
+ * Everything that determines a template's contents. Serialized and hashed;
+ * anything omitted here is something two runs may disagree about while still
+ * sharing a template, so omissions are the way stale reuse happens.
+ */
+export interface TemplateInputs {
+  /** Which configured database this template stands in for. */
+  readonly databaseName: string
+  /**
+   * The role that builds — and therefore owns — the template.
+   *
+   * `CREATE DATABASE ... WITH TEMPLATE` requires ownership of the template, so
+   * a template is only shareable among processes connecting as the same role.
+   * Keying on the owner means a second role builds its own rather than failing
+   * to clone, or worse, trying to drop a database it does not own.
+   */
+  readonly owner: string
+  /**
+   * The role the template's migrations run as, when `testOwnerUrl` names one.
+   *
+   * It decides who OWNS every migrated object, which decides what a
+   * `SECURITY DEFINER` function made by a migration can read. Omitted entirely
+   * when unconfigured, so a template built without the field keeps its name.
+   */
+  readonly migrationOwner?: string
+  readonly extensions: readonly string[]
+  readonly migrationTable: string
+  /** Hash of the migrations folder's contents, or `null` when unmigrated. */
+  readonly migrations: string | null
+  /** Framework-table provisioning depends on these blueprint sections. */
+  readonly trace: unknown
+  readonly audit: unknown
+  /** Framework tables ride the default database only. */
+  readonly isDefaultDatabase: boolean
+  /** Trace/audit day partitions are provisioned relative to the current day. */
+  readonly partitionDay: string
+  /** Internal definitions and emitted DDL travel with the pipework version. */
+  readonly pipeworkVersion: string
+  readonly formatVersion: number
+}
+
+/**
+ * Hash a migrations folder's contents: every file's path relative to the folder
+ * and its bytes, in a stable order. Path names are included so a rename is a
+ * change; a missing or unreadable folder hashes as absent.
+ */
+export function hashMigrationsFolder(folder: string): string | null {
+  const files: string[] = []
+  const walk = (dir: string): void => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) walk(full)
+      else if (entry.isFile()) files.push(full)
+    }
+  }
+  walk(folder)
+  if (files.length === 0) return null
+
+  const hash = createHash('sha256')
+  for (const file of files) {
+    // Normalize the separator so the same tree hashes alike on any platform.
+    hash.update(relative(folder, file).split(sep).join('/'))
+    hash.update('\0')
+    hash.update(readFileSync(file))
+    hash.update('\0')
+  }
+  return hash.digest('hex')
+}
+
+/**
+ * Collect the content inputs for one configured database's template.
+ *
+ * `partitionDay` is the current UTC date. Trace and audit partitions are
+ * created per day with a lead window, so a template built yesterday is missing
+ * today's partitions — keying on the day makes that invalidation automatic
+ * instead of a stale-data bug that only shows up after midnight.
+ */
+export function templateInputs(
+  databaseName: string,
+  dbConfig: ResolvedDatabase,
+  blueprint: Blueprint,
+  isDefaultDatabase: boolean,
+  today: Date,
+): TemplateInputs {
+  return {
+    databaseName,
+    owner: new URL(dbConfig.url).username,
+    ...(dbConfig.testOwnerUrl !== undefined ? { migrationOwner: new URL(dbConfig.testOwnerUrl).username } : {}),
+    extensions: [...dbConfig.extensions].sort(),
+    migrationTable: dbConfig.migrationTable,
+    migrations: dbConfig.migrations === undefined ? null : hashMigrationsFolder(dbConfig.migrations),
+    trace: blueprint.trace ?? null,
+    audit: blueprint.audit ?? null,
+    isDefaultDatabase,
+    partitionDay: today.toISOString().slice(0, 10),
+    pipeworkVersion: VERSION,
+    formatVersion: TEMPLATE_FORMAT_VERSION,
+  }
+}
+
+/**
+ * The template's content fingerprint: 16 lowercase hex chars. Deliberately
+ * wider than the 12-char per-run nonce so a template name can never be mistaken
+ * for a run-owned database name.
+ */
+export function templateFingerprint(inputs: TemplateInputs): string {
+  return createHash('sha256').update(JSON.stringify(inputs)).digest('hex').slice(0, 16)
+}

package/src/test/globals.d.ts

@@ -0,0 +1,7 @@
+import type { DB } from '../data/db/index.js'
+
+declare global {
+  var db: DB
+}
+
+export {}

package/src/test/index.ts

@@ -0,0 +1,19 @@
+export { setupTestDatabases, teardownTestDatabases, getTestDatabase, getTestDatabases, type TestDatabase, type SetupOptions } from './setup.js'
+export { flushPendingDrops, TEST_DROP_LOG_PREFIX, TEST_REAP_LOG_PREFIX } from './setup.js'
+export {
+  SetupStalled,
+  logSlowPhases,
+  SETUP_PROGRESS_LOG_PREFIX,
+  type SetupPhase,
+  type SetupProgress,
+  type SetupProgressListener,
+} from './progress.js'
+export { armTestWatch, TEST_WATCH_LOG_PREFIX, type TestWatchTarget } from './watch.js'
+export { beginTestIsolation, endTestIsolation, type TestContext, type TestDatabaseConnections } from './plugin.js'
+export { setupPipeworkTests, useTestDb, useSetupDb, useTestInstance, useTestClient, type UseTestClientOptions, closeSetupConnections, SetupConnectionCloseError, teardownAfterAll, withFlow, type WithFlowOptions } from './vitest.js'
+export { mockAuth, asTenant } from './auth.js'
+export { withContext, withJobContext, type WithContextOptions } from './context.js'
+export { pipework as vitestPlugin, type PipeworkVitestOptions } from './vitest-plugin.js'
+export { resolveVitestConfig, resolveVitestModules } from './vitest-workspace.js'
+export { tap, type ManagedConnection, type ConnectOptions } from '../data/db/pool.js'
+export { crawlFixtureSite, type CrawlFixtureOptions, type CrawlFixtureRoute, type CrawlFixtureRequest, type CrawlFixtureSite } from './crawl-fixture.js'

package/src/test/namespace.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+// The clone-per-test database namespace, scoped to ONE project.
+//
+// pipework is consumed by many projects that may share a Postgres cluster. A
+// hardcoded `pipework_test_` / `pipework_app_` prefix made every consumer's
+// per-run test databases AND runtime roles collide in a single namespace: one
+// project's reaper dropped another's databases, clones ended up owned by a
+// foreign role, and `CREATE` on the cloned `public` schema was denied because
+// the connecting role was not the owner. Scoping both prefixes per project
+// isolates them — and isolates the reaper, so it only ever touches its own.
+//
+// Resolution order:
+//   1. PIPEWORK_TEST_NAMESPACE — explicit override (CI, or a shared cluster
+//      whose default namespace is already polluted by legacy runs).
+//   2. the consumer's package.json `name` — the natural per-project identifier.
+//   3. `pipework` — fallback when neither is available.
+
+let cached: string | null = null
+
+/**
+ * Pure namespace resolution: pick the first non-empty source, then sanitize to
+ * a valid Postgres identifier prefix. Exported for direct testing — the impure
+ * {@link projectNamespace} wraps it with the actual env + package.json sources.
+ */
+export function resolveNamespace(envOverride: string | undefined, pkgName: string | undefined): string {
+  const raw = envOverride !== undefined && envOverride.trim() !== '' ? envOverride
+    : pkgName !== undefined && pkgName.trim() !== '' ? pkgName
+    : 'pipework'
+  // Postgres identifiers are lowercase, alphanumeric + underscore, and must
+  // start with a letter. Collapse every other run of characters to one
+  // underscore so `@scope/name` and `scope-name` map to distinct, stable,
+  // legal tokens; prefix `p_` if the result would not start with a letter.
+  const token = raw.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+  return /^[a-z]/.test(token) ? token : `p_${token}`
+}
+
+/** This project's namespace token, resolved once per process. */
+export function projectNamespace(): string {
+  if (cached !== null) return cached
+  let pkgName: string | undefined
+  try {
+    pkgName = (JSON.parse(readFileSync(join(process.cwd(), 'package.json'), 'utf-8')) as { name?: string }).name
+  } catch {
+    // No readable package.json (e.g. a bare test harness) — fall back below.
+  }
+  cached = resolveNamespace(process.env['PIPEWORK_TEST_NAMESPACE'], pkgName)
+  return cached
+}
+
+/** Prefix for this project's per-run test databases: `<project>_test_`. */
+export function testDbPrefix(): string {
+  return `${projectNamespace()}_test_`
+}
+
+/** Prefix for this project's per-run runtime (app) roles: `<project>_app_`. */
+export function appRolePrefix(): string {
+  return `${projectNamespace()}_app_`
+}
+
+/**
+ * Prefix for this project's shared, content-keyed templates: `<project>_tmpl_`.
+ *
+ * Templates sit in their own prefix rather than under `testDbPrefix()` because
+ * they have a different lifecycle and a different reaping rule: a per-run clone
+ * dies with its run, a template deliberately outlives every run that uses it
+ * and is dropped only once no run wants it. Separate prefixes keep the reaper's
+ * two passes from having to tell the names apart by shape. Issue #340.
+ */
+export function templateDbPrefix(): string {
+  return `${projectNamespace()}_tmpl_`
+}
+
+/**
+ * `LIKE` pattern matching every per-run test database of THIS project, with the
+ * prefix underscores escaped so they match literally. The reaper uses it to
+ * scope its sweep to its own namespace and never another project's databases.
+ */
+export function testDbLikePattern(): string {
+  return `${testDbPrefix().replace(/_/g, '\\_')}%`
+}
+
+/** `LIKE` pattern matching every shared template of THIS project. */
+export function templateDbLikePattern(): string {
+  return `${templateDbPrefix().replace(/_/g, '\\_')}%`
+}

package/src/test/plugin.ts

@@ -0,0 +1,189 @@
+import postgres from 'postgres'
+import { drizzle, type PostgresJsDatabase } from '../data/query/postgres-js/index.js'
+import { sql } from '../data/query/index.js'
+import type { Manifold } from '../core/pipework.js'
+import { getTestDatabase, type TestDatabase } from './setup.js'
+import { createTestContext as createCtx } from '../request/context/create.js'
+import { runInContext } from '../request/context/store.js'
+import type { Flow } from '../request/context/types.js'
+import { randomUUID } from 'node:crypto'
+import { createDebugFn, isObserverOnly } from '../data/db/instrumentation.js'
+import { createStatementWatch } from '../data/db/query-watch.js'
+import { markObservedConnection } from '../data/query/postgres-js/driver-error-boundary.js'
+import type { ResolvedObservability } from '../core/config/load.js'
+import { collapseTransactionsToSavepoints } from './savepoints.js'
+import { splitLargeInserts } from '../data/db/insert-split.js'
+import { settleTraceWritesBounded } from '../trace/runtime/pending-writes.js'
+import { createSystemHandle } from './system-channel.js'
+import { armTestWatch } from './watch.js'
+
+export interface TestDatabaseConnections {
+  [name: string]: PostgresJsDatabase
+}
+
+export interface TestContext {
+  id: string
+  db: TestDatabaseConnections
+}
+
+interface ActiveTestConnection {
+  client: postgres.Sql
+  closeWatch?: () => Promise<void>
+  drizzle: PostgresJsDatabase
+  /** Same connection and transaction, statements sent with the test-only cross-tenant policy open. Set when the database has `rls`. */
+  system?: PostgresJsDatabase
+  /** A handle for one named door on the same connection; set when the database has `rls`. */
+  door?: (name: string) => PostgresJsDatabase
+}
+
+const contextConnections = new Map<string, Map<string, ActiveTestConnection>>()
+const contextWatches = new Map<string, () => void>()
+
+/** The slice of vitest's `task` the watch needs: `fullName` and the resolved `timeout`. */
+export interface WatchedTask {
+  fullName: string
+  timeout: number
+}
+
+export async function beginTestIsolation(instance: Manifold, task?: WatchedTask): Promise<TestContext> {
+  const dbConnections: TestDatabaseConnections = {}
+  const contextId = randomUUID()
+  const connections = new Map<string, ActiveTestConnection>()
+
+  for (const [name] of instance.config.databases()) {
+    const testDb = getTestDatabase(name)
+    if (!testDb) {
+      throw new Error(`[pipework] Test database not set up for "${name}". Did setupTestDatabases() run?`)
+    }
+
+    const conn = await createIsolatedConnection(
+      testDb, connections, name, instance.config.observability, instance.config.database(name).rls !== undefined,
+    )
+    dbConnections[name] = conn
+
+    instance.pool.override(name, {
+      name,
+      client: connections.get(name)!.client,
+      drizzle: conn,
+      ...(connections.get(name)!.system !== undefined ? { system: connections.get(name)!.system! } : {}),
+      ...(connections.get(name)!.door !== undefined ? { door: connections.get(name)!.door! } : {}),
+      connectionIds() {
+        return Promise.reject(new Error(
+          '[pipework] connectionIds() is not available inside a test isolation context: the test connection is one transaction-pinned connection.\n' +
+          '  Fix: call connectionIds() on a pool opened with instance.pool.getOrCreate() or tap(), outside test isolation.',
+        ))
+      },
+      async close() { /* test harness manages lifecycle */ },
+    })
+  }
+
+  contextConnections.set(contextId, connections)
+  if (task !== undefined) {
+    const databases = [...connections.keys()].flatMap(n => {
+      const d = getTestDatabase(n)
+      return d ? [{ database: d.database, url: d.url }] : []
+    })
+    contextWatches.set(contextId, armTestWatch({ name: task.fullName, timeoutMs: task.timeout, databases }))
+  }
+  instance.isolation.markBegin()
+  return { id: contextId, db: dbConnections }
+}
+
+export async function endTestIsolation(instance: Manifold, ctx: TestContext): Promise<void> {
+  contextWatches.get(ctx.id)?.()
+  contextWatches.delete(ctx.id)
+  await settleTraceWritesBounded()
+  instance.pool.clearOverrides()
+
+  const connections = contextConnections.get(ctx.id)
+  if (!connections) {
+    instance.isolation.markEnd()
+    return
+  }
+
+  for (const [, conn] of connections) {
+    try {
+      await conn.drizzle.execute(sql.raw('ROLLBACK'))
+    } catch {
+      // Transaction may already be aborted
+    }
+    try {
+      await conn.client.end()
+    } catch {
+      // Connection may already be closed
+    }
+    await conn.closeWatch?.().catch(() => {})
+  }
+
+  contextConnections.delete(ctx.id)
+  instance.isolation.markEnd()
+}
+
+async function createIsolatedConnection(
+  testDb: TestDatabase,
+  connections: Map<string, ActiveTestConnection>,
+  name: string,
+  observability: ResolvedObservability,
+  withSystem: boolean,
+): Promise<PostgresJsDatabase> {
+  const debug = createDebugFn(observability)
+  const client = postgres(testDb.url, { max: 1, onnotice: () => {}, ...(debug ? { debug } : {}) })
+  if (isObserverOnly(observability)) markObservedConnection(client)
+  const watch = createStatementWatch({ database: name, url: testDb.url, slowQueryMs: observability.slowQueryMs, inFlightQueryMs: observability.inFlightQueryMs })
+  const db = drizzle(client, { statementWatch: watch.watch })
+
+  await db.execute(sql.raw('BEGIN'))
+  const join = collapseTransactionsToSavepoints(db, client)
+  splitLargeInserts(db)
+  let system: PostgresJsDatabase | undefined
+  let door: ((name: string) => PostgresJsDatabase) | undefined
+  if (withSystem) {
+    system = createSystemHandle(client)
+    join(system)
+    door = (doorName) => {
+      const handle = createSystemHandle(client, doorName)
+      join(handle)
+      return handle
+    }
+  }
+
+  connections.set(name, { client, closeWatch: watch.close, drizzle: db, ...(system !== undefined ? { system } : {}), ...(door !== undefined ? { door } : {}) })
+  return db
+}
+
+export function createTestContext(instance: Manifold, testConnections: TestContext, auth?: unknown, tenant?: string | null): Flow {
+  const ctx = createCtx(instance, randomUUID(), { auth, tenant })
+  for (const [name, drizzleDb] of Object.entries(testConnections.db)) {
+    ctx.transactions.set(name, { drizzle: drizzleDb, nonce: ctx._nonce, tenant: ctx.tenant })
+  }
+  return ctx
+}
+
+export async function propagateTestSessionVars(
+  instance: Manifold,
+  testConnections: TestContext,
+  tenant: string,
+): Promise<void> {
+  for (const [name, db] of Object.entries(testConnections.db)) {
+    const dbConfig = instance.config.database(name)
+    if (dbConfig.rls !== undefined) {
+      await db.execute(sql`SELECT set_config(${dbConfig.rls.sessionVar}, ${tenant}, true)`)
+    }
+  }
+}
+
+export function createSetupConnection(
+  testDb: TestDatabase,
+  observability?: ResolvedObservability,
+): { drizzle: PostgresJsDatabase; close: () => Promise<void> } {
+  const debug = observability ? createDebugFn(observability) : undefined
+  const client = postgres(testDb.url, { max: 1, onnotice: () => {}, ...(debug ? { debug } : {}) })
+  if (observability && isObserverOnly(observability)) markObservedConnection(client)
+  const watch = observability
+    ? createStatementWatch({ database: 'setup', url: testDb.url, slowQueryMs: observability.slowQueryMs, inFlightQueryMs: observability.inFlightQueryMs })
+    : undefined
+  const db = splitLargeInserts(drizzle(client, watch ? { statementWatch: watch.watch } : {}))
+  return { drizzle: db, close: async () => { await watch?.close(); await client.end() } }
+}
+
+export { runInContext }