pipework 0.290.0 → 0.292.0

package/src/data/db/namespace.ts

@@ -11,7 +11,7 @@ import { bulkSet } from './bulk-set.js'
 import { values } from './values.js'
 import { rows } from './rows.js'
 import { fn } from './function-source.js'
-import { update, insert, remove, upsert } from '../write/index.js'
+import { update, updateEach, insert, remove, upsert } from '../write/index.js'
 
 import { aliasedRelation, aliasedTable, aliasedTableColumn, getTableColumns, getTableName, getViewName, getViewSelectedFields, isTable, createMany, createOne, relations } from '../query/index.js'
 
@@ -88,7 +88,7 @@ export const pipe = Object.assign(getDb, {
   /** A typed rowset from parallel array parameters, one parameter per column whatever the row count, as a source for `.from()` and joins — `pipe.rows({ g: 'text', id: 'int' }, { g: [...], id: [...] })` renders `unnest($1::text[], $2::int[]) AS rows(g, id)`. For composite-key matches that would otherwise be a union or a JS-side tuple match. */
   rows,
 
-  /** A set-returning SQL function as a typed source for `.from()` and joins — `pipe.fn('schema.f', { args: [field.uuid()], columns: { path: field.text() } })`. Arguments are bound and cast to their declared types. */
+  /** A set-returning SQL function as a typed source for `.from()` and joins — `pipe.fn('schema.f', { args: [field.uuid()], columns: { path: field.text() } })`. Arguments are bound and cast to their declared types. With a `body` (one LANGUAGE sql SELECT, `volatility`, `rows`) pipework creates the function and migrates it, under rules that keep it inlinable; check it with `expectFunctionRead` from `pipework/test`. */
   fn,
 
   /** Field builders for domain definitions — uuid(), text(), integer(), etc. */
@@ -102,7 +102,9 @@ export const pipe = Object.assign(getDb, {
 
   /** Pipework-owned UPDATE builder — the only consumer-facing way to update pipework-managed tables (Q8). */
   update,
-  /** Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8). A list of any size is split into statements under Postgres's parameter limit, in one transaction. */
+  /** One UPDATE for many keys, returning how many rows each key updated (in input order); refuses, naming the key, when a key does not match exactly one row — `pipe.updateEach(t, { keys: { id: 'uuid', n: 'int' }, data: { id, n }, where: k => eq(t.id, k.id), set: k => ({ n: k.n }) })`. In the caller's transaction, audited as `pipe.update`. */
+  updateEach,
+  /** Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8). A list of any size is split into statements under Postgres's parameter limit, in one transaction; `.batch(rows)` sends every row as one statement instead, arrays and NULLs included. */
   insert,
   /** Pipework-owned DELETE builder — the only consumer-facing way to delete from pipework-managed tables (Q8). */
   delete: remove,

package/src/data/db/rows.ts

@@ -49,7 +49,7 @@ function quote(name: string): string {
 // One column as a Postgres array literal, sent as a single text parameter and cast to `T[]`. postgres.js
 // serialises a JS array only for the few element types it knows (text, int, uuid ...), so a `timestamptz[]`
 // parameter would throw; a literal string is parsed by Postgres for any type.
-function arrayLiteral(cells: readonly unknown[]): string {
+export function arrayLiteral(cells: readonly unknown[]): string {
   const item = (v: unknown): string => {
     if (v === null || v === undefined) return 'NULL'
     const text = v instanceof Date ? v.toISOString()

package/src/data/migrate/diff.ts

@@ -1,3 +1,4 @@
+import type { FunctionDefinition } from '../db/function-definition.js'
 import type {
   PwSnapshot,
   PwTableSnapshot,
@@ -10,6 +11,8 @@ import type {
 } from './snapshot.js'
 
 export type DiffOp =
+  | { type: 'create_function'; fn: FunctionDefinition }
+  | { type: 'drop_function'; fn: FunctionDefinition }
   | { type: 'create_table'; table: PwTableSnapshot }
   | { type: 'drop_table'; table: PwTableSnapshot }
   | { type: 'add_column'; tableName: string; tableSchema: string; column: PwColumnSnapshot }
@@ -39,11 +42,16 @@ export type DiffOp =
 
 /** The wire name of the table an op acts on, across all `DiffOp` shapes. */
 export function diffOpTableName(op: DiffOp): string {
+  if (op.type === 'create_function' || op.type === 'drop_function') return ''
   return op.type === 'create_table' || op.type === 'drop_table' ? op.table.name : op.tableName
 }
 
 export function diffSnapshots(prev: PwSnapshot, cur: PwSnapshot): DiffOp[] {
   const ops: DiffOp[] = []
+  const functionOps = diffFunctions(prev.functions ?? {}, cur.functions ?? {})
+
+  // Function drops come first: a function that reads a table must be gone before the table or a column it reads is.
+  ops.push(...functionOps.filter(op => op.type === 'drop_function'))
 
   const prevKeys = new Set(Object.keys(prev.tables))
   const curKeys = new Set(Object.keys(cur.tables))
@@ -93,6 +101,43 @@ export function diffSnapshots(prev: PwSnapshot, cur: PwSnapshot): DiffOp[] {
     diffAddConstraints(prevTable, curTable, ops)
   }
 
+  // Function creates come last: a LANGUAGE sql body is checked when the function is created, so every table,
+  // column and index it names must exist by then.
+  ops.push(...functionOps.filter(op => op.type === 'create_function'))
+
+  return ops
+}
+
+/** What a function returns, without its ROWS estimate (which CREATE OR REPLACE can change). */
+function shape(fn: FunctionDefinition): unknown {
+  return fn.returns.kind === 'table' ? { columns: fn.returns.columns } : fn.returns
+}
+
+/**
+ * A function is identified by `schema.name(argtypes)`. A new key is created; a key with a changed body, volatility
+ * or ROWS is replaced in place; a changed result shape cannot be replaced (Postgres refuses to change a return
+ * type), so it is dropped and created; a key that is gone is dropped. A changed argument list is a different key,
+ * so the old signature is dropped and the new one created.
+ */
+function diffFunctions(
+  prev: Record<string, FunctionDefinition>,
+  cur: Record<string, FunctionDefinition>,
+): DiffOp[] {
+  const ops: DiffOp[] = []
+  for (const [key, old] of Object.entries(prev)) {
+    const now = cur[key]
+    if (now === undefined || JSON.stringify(shape(now)) !== JSON.stringify(shape(old))) {
+      ops.push({ type: 'drop_function', fn: old })
+    }
+  }
+  for (const [key, now] of Object.entries(cur)) {
+    const old = prev[key]
+    if (old === undefined) {
+      ops.push({ type: 'create_function', fn: now })
+    } else if (JSON.stringify(old) !== JSON.stringify(now)) {
+      ops.push({ type: 'create_function', fn: now })
+    }
+  }
   return ops
 }
 

package/src/data/migrate/history.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { EMPTY_SNAPSHOT, type PwSnapshot, type PwTableSnapshot, type PwPartitionSnapshot } from './snapshot.js'
 import type { DoorSnapshot } from './door-generate.js'
+import type { FunctionDefinition } from '../db/function-definition.js'
 
 export interface MigrationEntry {
   tag: string
@@ -29,6 +30,7 @@ export interface SnapshotDelta {
   version: 'pw1-delta'
   tables: Record<string, TableDelta | null>
   doors?: Record<string, DoorSnapshot | null>
+  functions?: Record<string, FunctionDefinition | null>
 }
 
 const MAP_KEYS = ['columns', 'indexes', 'foreignKeys', 'checks', 'uniqueConstraints', 'compositePrimaryKeys'] as const
@@ -148,6 +150,10 @@ export function snapshotDelta(prev: PwSnapshot, next: PwSnapshot): SnapshotDelta
     const doors = diffMap<DoorSnapshot>(prev.doors ?? {}, next.doors ?? {})
     if (Object.keys(doors).length > 0) delta.doors = doors
   }
+  if (next.functions !== undefined || prev.functions !== undefined) {
+    const functions = diffMap<FunctionDefinition>(prev.functions ?? {}, next.functions ?? {})
+    if (Object.keys(functions).length > 0) delta.functions = functions
+  }
   return delta
 }
 
@@ -185,6 +191,9 @@ export function applyDelta(snap: PwSnapshot, delta: SnapshotDelta): PwSnapshot {
   if (delta.doors !== undefined) {
     result.doors = applyMap<DoorSnapshot>(snap.doors ?? {}, delta.doors) as NonNullable<PwSnapshot['doors']>
   }
+  if (delta.functions !== undefined) {
+    result.functions = applyMap<FunctionDefinition>(snap.functions ?? {}, delta.functions)
+  }
   return result
 }
 

package/src/data/migrate/snapshot.ts

@@ -10,6 +10,7 @@ import { Column } from '../query/column.js'
 import type { IndexedColumn } from '../query/pg-core/columns/common.js'
 import { camelToSnake } from '../domain/naming.js'
 import type { DefineOptions } from '../domain/types.js'
+import { FUNCTION_DEFINITION, functionKey, type FunctionDefinition } from '../db/function-definition.js'
 
 export interface PwSnapshot {
   version: 'pw1'
@@ -18,6 +19,8 @@ export interface PwSnapshot {
   tables: Record<string, PwTableSnapshot>
   /** Cross-tenant read doors with a generated policy; absent in snapshots written before doors existed. */
   doors?: Record<string, { table: string; role: string; ops?: readonly ('select' | 'update' | 'delete')[] }>
+  /** Functions pipework defines (`pipe.fn` with a `body`), by `schema.name(argtypes)`; absent in snapshots written before functions existed. */
+  functions?: Record<string, FunctionDefinition>
 }
 
 export interface PwTableSnapshot {
@@ -166,8 +169,21 @@ export function buildSnapshot(
   prevId: string,
 ): PwSnapshot {
   const tables: Record<string, PwTableSnapshot> = {}
+  const functions: Record<string, FunctionDefinition> = {}
 
   for (const value of Object.values(imports)) {
+    const definition = typeof value === 'function' ? (value as { [FUNCTION_DEFINITION]?: FunctionDefinition })[FUNCTION_DEFINITION] : undefined
+    if (definition !== undefined) {
+      const key = functionKey(definition)
+      const seen = functions[key]
+      if (seen !== undefined && JSON.stringify(seen) !== JSON.stringify(definition)) {
+        throw new Error(
+          `[pipework] Two different definitions of the function ${key} are exported from the schema files.\n\n  Fix: define it once and import it where it is called.\n`,
+        )
+      }
+      functions[key] = definition
+      continue
+    }
     if (!is(value, PgTable)) continue
     if (isExternal(value)) continue
 
@@ -281,6 +297,7 @@ export function buildSnapshot(
     id: randomUUID(),
     prevId,
     tables,
+    ...(Object.keys(functions).length > 0 ? { functions } : {}),
   }
 }
 

package/src/data/migrate/sql-emit.ts

@@ -1,6 +1,8 @@
 import type {
   DiffOp,
 } from './diff.js'
+import { bodyQuote } from '../db/function-definition.js'
+import type { FunctionDefinition } from '../db/function-definition.js'
 import type {
   PwTableSnapshot,
   PwColumnSnapshot,
@@ -24,7 +26,7 @@ function qualifiedTable(schema: string, name: string): string {
  * Every op type except the two `emitSQL` routes itself: `create_table` (whose
  * foreign keys are hoisted out) and `add_foreign_key`. Issue #312.
  */
-type InlineOp = Exclude<DiffOp, { type: 'create_table' } | { type: 'add_foreign_key' }>
+type InlineOp = Exclude<DiffOp, { type: 'create_table' } | { type: 'add_foreign_key' } | { type: 'create_function' } | { type: 'drop_function' }>
 
 export function emitSQL(ops: DiffOp[]): string[] {
   // Foreign keys are hoisted to run after every CREATE TABLE. A from-scratch
@@ -34,8 +36,15 @@ export function emitSQL(ops: DiffOp[]): string[] {
   // tables in place before any constraint is added. Issue #312.
   const tables: string[] = []
   const foreignKeys: string[] = []
+  // Function drops lead and function creates trail, whatever order the ops come in; see diffSnapshots.
+  const functionDrops: string[] = []
+  const functionCreates: string[] = []
   for (const op of ops) {
-    if (op.type === 'create_table') {
+    if (op.type === 'drop_function') {
+      functionDrops.push(emitDropFunction(op.fn))
+    } else if (op.type === 'create_function') {
+      functionCreates.push(emitCreateFunction(op.fn))
+    } else if (op.type === 'create_table') {
       tables.push(...emitCreateTable(op.table))
       const partitioned = op.table.partitionBy !== undefined
       for (const fk of Object.values(op.table.foreignKeys)) {
@@ -47,7 +56,7 @@ export function emitSQL(ops: DiffOp[]): string[] {
       tables.push(...emitOp(op))
     }
   }
-  return [...tables, ...foreignKeys]
+  return [...functionDrops, ...tables, ...foreignKeys, ...functionCreates]
 }
 
 function emitOp(op: InlineOp): string[] {
@@ -390,3 +399,24 @@ function emitAddCompositePK(tableName: string, tableSchema: string, pk: PwCompos
 function emitReplaceCompositePK(tableName: string, tableSchema: string, from: PwCompositePKSnapshot, to: PwCompositePKSnapshot, partitioned: boolean): string[] {
   return emitKeyConstraint(tableName, tableSchema, 'PRIMARY KEY', to, partitioned, from.name)
 }
+
+function qualifiedFunction(fn: FunctionDefinition): string {
+  return `${q(fn.schema)}.${q(fn.name)}`
+}
+
+function emitDropFunction(fn: FunctionDefinition): string {
+  return `DROP FUNCTION ${qualifiedFunction(fn)}(${fn.args.join(', ')})`
+}
+
+/**
+ * `CREATE OR REPLACE FUNCTION`, always `LANGUAGE sql`, STABLE or IMMUTABLE, no SET clause, not SECURITY DEFINER, not STRICT:
+ * the form Postgres inlines into the calling query. The body is dollar-quoted so the statement scanner keeps it whole.
+ */
+function emitCreateFunction(fn: FunctionDefinition): string {
+  const returns = fn.returns.kind === 'scalar'
+    ? fn.returns.type
+    : `TABLE(${fn.returns.columns.map(c => `${q(c.name)} ${c.type}`).join(', ')})`
+  const rows = fn.returns.kind === 'table' ? ` ROWS ${fn.returns.rows}` : ''
+  const tag = bodyQuote(fn.body)
+  return `CREATE OR REPLACE FUNCTION ${qualifiedFunction(fn)}(${fn.args.join(', ')}) RETURNS ${returns} LANGUAGE sql ${fn.volatility.toUpperCase()}${rows} AS ${tag}${fn.body}${tag}`
+}

package/src/data/write/audit/verb-insert.ts

@@ -9,6 +9,7 @@ import { buildAuditInserts, buildEntityIdExpr, type AuditSelectContext } from '.
 import { AUDIT_COLUMNS_SQL } from './audit-columns.js'
 import { buildFinalSelect } from './final-select.js'
 import { applyOnConflict } from '../conflict.js'
+import { batchInsertSql } from '../batch-insert.js'
 import type { SQL } from '../../db/types.js'
 import type { WriteState } from '../state.js'
 
@@ -19,7 +20,9 @@ export function compileInsertAudit(db: AnyDb, state: WriteState, ctx: AuditSelec
   // `.getSQL()` strips the auto-paren drizzle adds around SQLWrapper builders
   // when they are templated — we add explicit parens at the CTE boundary so
   // the WITH clause keeps a uniform shape across verbs.
-  const inner = applyOnConflict(db.insert(state.table).values(state.values ?? []), state).returning().getSQL()
+  const inner = state.batch === true
+    ? sql`${batchInsertSql(state)} RETURNING *`
+    : applyOnConflict(db.insert(state.table).values(state.values ?? []), state).returning().getSQL()
   const after = buildTraceSafeProjection(state.table, 'inserted') ?? sql`NULL::jsonb`
   const auditSelect = buildAuditInserts(ctx, sql`FROM inserted`, buildEntityIdExpr(state.table, 'inserted'), sql`NULL::jsonb`, after)
   const finalSelect = buildFinalSelect(state, 'inserted')

package/src/data/write/audit/verb-update.ts

@@ -7,6 +7,7 @@
 // zero rows from `before`, suppressing the audit insert.
 
 import { sql } from '../../db/sql.js'
+import { getTableColumns } from '../../query/index.js'
 import { quoteIdentifier } from '../../db/identifiers.js'
 import { camelToSnake } from '../../domain/naming.js'
 import { buildTraceSafeProjection } from './projection.js'
@@ -26,11 +27,20 @@ export function compileUpdateAudit(db: AnyDb, state: WriteState, ctx: AuditSelec
   // `.getSQL()` strips the auto-paren drizzle adds around SQLWrapper builders
   // when they are templated — we add explicit parens at the CTE boundary so
   // the WITH clause keeps a uniform shape across verbs.
+  const each = state.each
   let updateChain = db.update(state.table).set(set)
+  if (each !== undefined) updateChain = updateChain.from(each.source)
   if (state.where !== undefined) updateChain = updateChain.where(state.where)
-  const updateInner = updateChain.returning().getSQL()
+  // An update for many keys also returns the index of the key each row matched, to count rows per key.
+  const updateInner = (each === undefined
+    ? updateChain.returning()
+    : updateChain.returning({ ...(getTableColumns(state.table as never) as Record<string, unknown>), __i: each.ordinal.as('__i') })).getSQL()
 
-  let beforeChain = db.select().from(state.table)
+  // Over many keys a row can match several of them; it is snapshotted once, as the update changes it once.
+  let beforeChain = each === undefined
+    ? db.select().from(state.table)
+    : db.selectDistinctOn(pk.map(k => (state.table as unknown as Record<string, unknown>)[k]), getTableColumns(state.table as never))
+      .from(state.table).crossJoin(each.source)
   if (state.where !== undefined) beforeChain = beforeChain.where(state.where)
   const beforeInner = beforeChain.getSQL()
 
@@ -45,7 +55,7 @@ export function compileUpdateAudit(db: AnyDb, state: WriteState, ctx: AuditSelec
   const after = buildTraceSafeProjection(state.table, 'updated') ?? sql`NULL::jsonb`
   const fromClause = sql.raw(`FROM updated JOIN before ON ${joinOn}`)
   const auditSelect = buildAuditInserts(ctx, fromClause, buildEntityIdExpr(state.table, 'updated'), before, after)
-  const finalSelect = buildFinalSelect(state, 'updated')
+  const finalSelect = each === undefined ? buildFinalSelect(state, 'updated') : sql.raw('SELECT "__i" FROM updated')
 
   return sql`
     WITH before AS (${beforeInner}),

package/src/data/write/batch-insert.ts

@@ -0,0 +1,179 @@
+// `pipe.insert(table).batch(rows)`: many rows as ONE statement, whatever the row count.
+//
+//   INSERT INTO "t" ("a", "b") SELECT "batch"."a"::uuid, "batch"."b"::text[] FROM unnest($1::text[], $2::text[]) AS "batch"("a", "b")
+//
+// Each column travels as one text-array parameter holding the cells exactly as the column's own driver
+// encoding (`mapToDriverValue`) would send them for a single-row insert, and is cast back to the column's SQL
+// type in the SELECT. Two parameters per two columns, not one per cell, so the row count never reaches
+// Postgres's parameter limit; and because the cast happens per cell, an array column (any dimension) needs no
+// `unnest` of its own, which would flatten it. It is plain INSERT ... SELECT, so RLS insert policies, `ON CONFLICT`,
+// `RETURNING` and the audit CTE all apply as they do to a `values()` insert (`COPY FROM` does none of these: see REFERENCE.md).
+
+import { getTableColumns, is, SQL as SQLClass } from '../query/index.js'
+import { getTableConfig } from '../query/pg-core/index.js'
+import type { PgTable } from '../query/pg-core/index.js'
+import { sql } from '../db/sql.js'
+import type { SQL } from '../db/types.js'
+import { arrayLiteral } from '../db/rows.js'
+import { insertTenant } from '../../auth/tenant/scoped-db.js'
+import type { WriteState } from './state.js'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle's column type is deeply generic; only the members read below are used
+type AnyColumn = any
+
+const SQL_TYPE = /^[A-Za-z_"][A-Za-z0-9_". ]*(\([0-9, ]+\))?(\[[0-9]*\])*$/
+const SERIAL_AS: Record<string, string> = { serial: 'integer', bigserial: 'bigint', smallserial: 'smallint' }
+
+function fail(problem: string, fix: string): never {
+  throw new Error(`[pipework] pipe.insert().batch(): ${problem}\n\n  Fix: ${fix}\n`)
+}
+
+function quote(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+/** The table's name as SQL: schema-qualified when it has a schema. */
+export function qualifiedName(table: PgTable): string {
+  const config = getTableConfig(table)
+  return config.schema === undefined ? quote(config.name) : `${quote(config.schema)}.${quote(config.name)}`
+}
+
+/**
+ * The state with the tenant column set on every row when the connection is tenant-scoped (a row naming another
+ * tenant throws, as `values()` does). Also runs the connection's insert policy, so a guard refuses a tenant table.
+ */
+export function scopeBatchRows(state: WriteState, db: unknown): WriteState {
+  const tenant = insertTenant(db as never, state.table)
+  if (tenant === null || state.values === undefined) return state
+  const { columnKey, tenantId } = tenant
+  const values = state.values.map(row => {
+    const existing = row[columnKey]
+    if (existing !== undefined && existing !== tenantId) {
+      throw new Error(
+        `[pipework] Tenant-scoped insert: value has ${columnKey} "${String(existing)}" ` +
+        `but the current context tenant is "${tenantId}".\n\n` +
+        `  Remove the explicit ${columnKey} from your insert values — it's set automatically.\n` +
+        '  If you need cross-tenant writes, file an issue on the pipework repo.\n',
+      )
+    }
+    return { ...row, [columnKey]: tenantId }
+  })
+  return { ...state, values }
+}
+
+function cellText(column: AnyColumn, key: string, index: number, value: unknown): string | null {
+  if (value === null) return null
+  if (is(value, SQLClass)) {
+    fail(`row ${String(index)} sets "${key}" to a sql expression.`, 'a batch carries values only; use pipe.insert().values() for a row that needs an expression.')
+  }
+  const driver: unknown = column.mapToDriverValue(value)
+  if (driver === null || driver === undefined) return null
+  if (typeof driver === 'string') return driver
+  if (typeof driver === 'number' || typeof driver === 'bigint' || typeof driver === 'boolean') return String(driver)
+  if (driver instanceof Date) return driver.toISOString()
+  if (driver instanceof Uint8Array) return `\\x${Buffer.from(driver).toString('hex')}`
+  return JSON.stringify(driver)
+}
+
+/**
+ * When a batch is split: the library sends at most this many rows, and at most this many bytes of parameter
+ * text, per statement, several in order in one transaction. Measured on the test cluster, 139,000 rows of a
+ * uuid, a text, an int and a text[] were one statement of 19 MB of parameters in 2.4 s; the bounds sit well
+ * above that and well under Postgres's 1 GB cap on a single parameter. Mutable so tests can shrink them.
+ */
+export const batchLimits = { rows: 250_000, bytes: 256 * 1024 * 1024 }
+
+export interface BatchColumn { readonly key: string; readonly name: string; readonly type: string; readonly cells: (string | null)[] }
+
+export function encode(state: WriteState): BatchColumn[] {
+  const rows = state.values ?? []
+  const columns = getTableColumns(state.table as unknown as PgTable) as Record<string, AnyColumn>
+  for (let i = 0; i < rows.length; i++) {
+    for (const key of Object.keys(rows[i]!)) {
+      if (columns[key] === undefined) {
+        fail(`row ${String(i)} has "${key}", which is not a field of "${state.table.$name}".`, `use the table's field keys: ${Object.keys(columns).join(', ')}.`)
+      }
+    }
+  }
+  const out: BatchColumn[] = []
+  for (const [key, column] of Object.entries(columns)) {
+    if (column.shouldDisableInsert() === true) continue
+    const given = rows.map(row => row[key])
+    const supplied = given.filter(v => v !== undefined).length
+    // A JS-side default (`$defaultFn`, `$onUpdateFn`) fills an omitted cell as `values()` does.
+    const jsDefault = column.defaultFn ?? (column.default === undefined || column.default === null ? column.onUpdateFn : undefined)
+    if (supplied === 0 && jsDefault === undefined) continue
+    if (supplied > 0 && supplied < rows.length && jsDefault === undefined) {
+      const missing = given.findIndex(v => v === undefined)
+      fail(
+        `row ${String(missing)} omits "${key}" while ${String(supplied)} of ${String(rows.length)} rows set it.`,
+        `a batch is one statement, so every row names the same columns: pass null for NULL, a value for each row, or omit "${key}" from all of them (its column default applies).`,
+      )
+    }
+    const cells = given.map((v, i) => {
+      if (v !== undefined) return cellText(column, key, i, v)
+      return cellText(column, key, i, (jsDefault as () => unknown)())
+    })
+    const raw = String(column.getSQLType())
+    const type = SERIAL_AS[raw] ?? raw
+    if (!SQL_TYPE.test(type)) fail(`column "${key}" has the SQL type "${type}", which a batch cannot cast to.`, 'use pipe.insert().values() for this table.')
+    out.push({ key, name: String(column.name), type, cells })
+  }
+  if (out.length === 0) fail('no row sets a column.', 'give at least one column a value in some row, or a column with a JS-side default.')
+  return out
+}
+
+/**
+ * The statements a batch is sent as: the whole list in one when it fits `batchLimits`, otherwise consecutive
+ * slices (each slice's rows, in input order) that each fit. Every slice carries its already-encoded columns.
+ */
+export function planBatch(state: WriteState): WriteState[] {
+  const rows = state.values ?? []
+  const columns = encode(state)
+  const slices: [number, number][] = []
+  let from = 0
+  let bytes = 0
+  for (let i = 0; i < rows.length; i++) {
+    let rowBytes = 0
+    for (const c of columns) rowBytes += c.cells[i] === null ? 0 : Buffer.byteLength(c.cells[i]!)
+    if (i > from && (i - from >= batchLimits.rows || bytes + rowBytes > batchLimits.bytes)) {
+      slices.push([from, i])
+      from = i
+      bytes = 0
+    }
+    bytes += rowBytes
+  }
+  slices.push([from, rows.length])
+  if (slices.length === 1) return [{ ...state, encoded: columns }]
+  return slices.map(([a, b]) => ({
+    ...state,
+    values: rows.slice(a, b),
+    encoded: columns.map(c => ({ ...c, cells: c.cells.slice(a, b) })),
+  }))
+}
+
+/** Row i of the result is row i of `state.values`; the statement is `INSERT ... SELECT FROM unnest(...)` with the state's `ON CONFLICT` clause, no RETURNING. */
+export function batchInsertSql(state: WriteState): SQL {
+  const columns = (state.encoded as BatchColumn[] | undefined) ?? encode(state)
+  const table = state.table as unknown as PgTable
+  const names = columns.map(c => quote(c.name))
+  const arrays = columns.map(c => sql`${sql.param(arrayLiteral(c.cells))}::text[]`)
+  const picked = columns.map(c => `"batch".${quote(c.name)}::${c.type}`)
+  let conflict = sql.raw('')
+  if (state.onConflict !== undefined) {
+    const target = state.onConflict.target
+    if (target === undefined) {
+      conflict = sql` ON CONFLICT DO NOTHING`
+    } else {
+      const cols = getTableColumns(table) as Record<string, AnyColumn>
+      const list = target.map(k => {
+        if (cols[k] === undefined) {
+          throw new Error(`pipe.insert: onConflictDoNothing target "${k}" is not a field of "${state.table.$name}". Use a field key declared on the table.`)
+        }
+        return quote(String(cols[k].name))
+      })
+      conflict = sql` ON CONFLICT (${sql.raw(list.join(', '))}) DO NOTHING`
+    }
+  }
+  return sql`INSERT INTO ${sql.raw(qualifiedName(table))} (${sql.raw(names.join(', '))}) SELECT ${sql.raw(picked.join(', '))} FROM unnest(${sql.join(arrays, sql`, `)}) AS "batch"(${sql.raw(names.join(', '))})${conflict}`
+}

package/src/data/write/execute.ts

@@ -26,9 +26,17 @@ import { resolveActorId } from './audit/actor.js'
 import type { AuditSelectContext } from './audit/audit-select.js'
 import { rowsPerStatement } from '../db/insert-split.js'
 import { applyOnConflict, reportSkipped } from './conflict.js'
+import { batchInsertSql, planBatch, scopeBatchRows } from './batch-insert.js'
+import { buildFinalSelect } from './audit/final-select.js'
+import { sql } from '../db/sql.js'
 
-export async function executeWrite(state: WriteState): Promise<unknown> {
-  const db = pipe(state.table.$options.database)
+export async function executeWrite(input: WriteState): Promise<unknown> {
+  const db = pipe(input.table.$options.database)
+  // A batch carries the tenant on its rows before the audit and vanilla paths read them.
+  const state = input.batch === true ? scopeBatchRows(input, db) : input
+  if (state.batch === true && (state.values === undefined || state.values.length === 0)) {
+    return state.returning === undefined || state.returning === null ? undefined : []
+  }
   const flow = getContext()
   if (flow !== undefined && flow.trace !== null) {
     const stepCtx = flow.trace.buffer.currentStep()
@@ -51,6 +59,7 @@ export async function executeWrite(state: WriteState): Promise<unknown> {
       if (chunkValueSize !== null) {
         return executeChunkedAuditWrite(state, auditCtx, chunkValueSize)
       }
+      if (state.batch === true) return executeBatchAudit(state, auditCtx)
       const stmt = compileAuditWrite(db, state, auditCtx)
       // The compiled CTE is already tenant-scoped at compile time (the user
       // write inside the CTE was built against the scoped `pipe()` DB, so it
@@ -60,10 +69,12 @@ export async function executeWrite(state: WriteState): Promise<unknown> {
       const rawDb = pipeRaw(state.table.$options.database)
       const rows = await rawDb.execute(stmt)
       for (const touch of selection.written) stepCtx.markWrote(touch)
+      if (state.each !== undefined) return tally(state.each.count, rows, '__i')
       if (state.onConflict !== undefined) reportSkipped(state, Array.isArray(rows) ? rows.length : 0)
       return decodeReturning(state, rows)
     }
   }
+  if (state.batch === true) return executeBatchInsert(state)
   if ((state.verb === 'insert' || state.verb === 'upsert') && state.values !== undefined) {
     const size = rowsPerStatement(state.table)
     if (state.values.length > size) return executeChunkedWrite(state, size)
@@ -90,6 +101,8 @@ function computeChunkValueSize(
   if (state.verb !== 'insert' && state.verb !== 'upsert') return null
   if (state.values === undefined) return null
   if (touches === 0) return null
+  // A batch is one statement by contract: its audit rows come from one INSERT ... SELECT, with no parameter per row.
+  if (state.batch === true) return null
 
   const limit = flow.instance.config.trace.auditChunkSize
   const projectedAuditRows = state.values.length * touches
@@ -176,8 +189,70 @@ type AnyDb = any
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyChain = any
 
+/** Rows per input index of a keys rowset: how many table rows each key updated. */
+function tally(count: number, rows: unknown, column: string): number[] {
+  const counts = new Array<number>(count).fill(0)
+  if (Array.isArray(rows)) for (const row of rows as Record<string, unknown>[]) counts[Number(row[column])]! += 1
+  return counts
+}
+
+/**
+ * Runs the statements of a batch plan in order. A batch over `batchLimits` is several statements, so they run in
+ * one transaction (a savepoint when nested): all of it lands or none, and each statement reads the one before.
+ */
+async function inBatches(state: WriteState, one: (chunk: WriteState) => Promise<unknown[]>): Promise<unknown[]> {
+  const plan = planBatch(state)
+  if (plan.length === 1) return one(plan[0]!)
+  const out: unknown[] = []
+  const run = async (): Promise<void> => {
+    for (const chunk of plan) for (const row of await one(chunk)) out.push(row)
+  }
+  const dbName = state.table.$options.database
+  if (dbName === undefined) await pipe.transaction(run)
+  else await pipe.transaction(dbName, run)
+  return out
+}
+
+/** `INSERT ... SELECT FROM unnest(...)`, one statement per plan slice; rows come back as `values()` returns them, in input order. */
+async function executeBatchInsert(state: WriteState): Promise<unknown> {
+  const dbName = state.table.$options.database
+  const returns = state.returning !== undefined && state.returning !== null
+  const rows = await inBatches(state, async chunk => {
+    const rawDb = pipeRaw(dbName)
+    const insertSql = batchInsertSql(chunk)
+    if (!returns && state.onConflict === undefined) {
+      await rawDb.execute(insertSql)
+      return []
+    }
+    // Under onConflictDoNothing the rows written are the rows returned, so they are asked for even when the caller did not.
+    const out = await rawDb.execute(sql`WITH inserted AS (${insertSql} RETURNING *) ${buildFinalSelect(state, 'inserted')}`)
+    return Array.isArray(out) ? [...out] : []
+  })
+  if (state.onConflict !== undefined) reportSkipped(state, rows.length)
+  if (!returns) return state.onConflict === undefined ? undefined : []
+  return decodeReturning(state, rows)
+}
+
+/** The write-and-audit statement, one per plan slice, in one transaction when there are several; each slice's audit rows land with its rows. */
+async function executeBatchAudit(state: WriteState, ctx: AuditSelectContext): Promise<unknown> {
+  const dbName = state.table.$options.database
+  const rows = await inBatches(state, async chunk => {
+    const stmt = compileAuditWrite(pipe(dbName), chunk, ctx)
+    const out = await pipeRaw(dbName).execute(stmt)
+    return Array.isArray(out) ? [...out] : []
+  })
+  for (const touch of ctx.written) ctx.step.markWrote(touch)
+  if (state.onConflict !== undefined) reportSkipped(state, rows.length)
+  return decodeReturning(state, rows)
+}
+
 async function executeUpdate(db: AnyDb, state: WriteState): Promise<unknown> {
   let q: AnyChain = db.update(state.table).set(state.set ?? {})
+  if (state.each !== undefined) {
+    q = q.from(state.each.source)
+    if (state.where !== undefined) q = q.where(state.where)
+    return tally(state.each.count, await q.returning({ i: state.each.ordinal }), 'i')
+  }
   if (state.where !== undefined) q = q.where(state.where)
   return runWithReturning(q, state.returning)
 }

package/src/data/write/index.ts

@@ -9,3 +9,5 @@ export { insert, InsertBuilder } from './insert.js'
 export { remove, DeleteBuilder } from './delete.js'
 export { upsert, UpsertBuilder } from './upsert.js'
 export type { WriteState, WriteVerb, ReturningShape } from './state.js'
+export { updateEach } from './update-each.js'
+export type { UpdateEachOptions } from './update-each.js'

package/src/data/write/insert.ts

@@ -19,6 +19,21 @@ export class InsertBuilder<T extends PgTable, TResult = unknown> implements Prom
     })
   }
 
+  /**
+   * Sends the rows as ONE statement up to 250,000 rows or 256 MiB of parameter text, then as consecutive statements of that size in one transaction (the library splits, never the caller): each column travels as a single array parameter
+   * (so no parameter limit and no chunking) and is cast back per cell, which carries array columns, NULLs and
+   * every type `values()` carries, encoded as `values()` would. Every row must name the same columns; a column
+   * no row names takes its default. Composes with `onConflictDoNothing()` and `returning()`; the rows come back in
+   * input order. Runs under RLS insert policies and audits as `values()` does, in the caller's transaction.
+   */
+  batch(rows: ReadonlyArray<InsertValues<T>>): InsertBuilder<T, TResult> {
+    return new InsertBuilder<T, TResult>({
+      ...this.state,
+      batch: true,
+      values: rows as ReadonlyArray<Record<string, unknown>>,
+    })
+  }
+
   /**
    * Leaves a row that conflicts with an existing one and inserts the rest.
    * Without `target`, any unique or exclusion constraint conflict is skipped.