@simtlix/simfinity-postgres 3.5.8 → 3.6.0

package/README.md

@@ -31,11 +31,11 @@ import { postgresPlugin } from '@simtlix/simfinity-postgres';
 const simfinity = createSQL({ plugin: postgresPlugin({ pool, schema: 'library' }) });
 ```
 
-Install `@simtlix/simfinity-sql@3.5.8` as a direct dependency when importing its factory. PostgreSQL 15 or later is the only supported SQL plugin. The [SQL package guide](https://github.com/simtlix/simfinity.js/tree/master/packages/sql) documents relational planning and the versioned plugin contract.
+Install `@simtlix/simfinity-sql@3.6.0` as a direct dependency when importing its factory. PostgreSQL 15 or later is the only supported SQL plugin. The [SQL package guide](https://github.com/simtlix/simfinity.js/tree/master/packages/sql) documents relational planning and the versioned plugin contract.
 
-Both factories permanently bind one pool and schema. The returned runtime supports registration, generated queries and mutations, middleware and scopes, controllers and validators, custom mutations, state machines, nested relationship writes, embedded reconstruction, and native PostgreSQL model handles. Native handles expose `findById`, `find`, `create`, `update`, and `delete`; they are not Mongoose models. `find(args, { session })` accepts the generated GraphQL list query arguments. Existing `pg.Pool` configuration and `pg.PoolClient` query interfaces remain compatible across both factories. A custom pool or client wrapper should pass `pg`'s `command` through in query results: the plugin reads it from the `COMMIT` result to detect a transaction that PostgreSQL rolled back because one of its statements failed, and without it such a transaction reports success with nothing stored.
+Both factories permanently bind one pool and schema, and four optional settings: `multiRowInserts: false` keeps one `INSERT` per owned row instead of multi-row statements; `explicitNullsOrder: true` keeps the `NULLS` clause on sorts of `id` and required fields, as 3.5.9 did, instead of letting indexes serve them; the opt-in `refreshTriggers: 'perRoot'` refreshes each changed root's owned shape and unique keys once per transaction, while its guard trigger stays deferred, instead of once per changed row; and the opt-in `ownerIndexes: 'minimal'` leaves out the `(__owner_id)` indexes that the primary key or a unique index covers on new owned and guard tables. An unknown `refreshTriggers` or `ownerIndexes` value throws `INVALID_DATABASE_SCHEMA` (400). Read the [upgrade notes](https://simtlix.github.io/simfinity.js/resources/compatibility.html#upgrade-to-3-6-0) before enabling the opt-ins: versions up to 3.5.9 cannot validate databases created with them. The returned runtime supports registration, generated queries and mutations, middleware and scopes, controllers and validators, custom mutations, state machines, nested relationship writes, embedded reconstruction, and native PostgreSQL model handles. Native handles expose `findById`, `find`, `create`, `update`, and `delete`; they are not Mongoose models. `find(args, { session })` accepts the generated GraphQL list query arguments. Existing `pg.Pool` configuration and `pg.PoolClient` query interfaces remain compatible across both factories. A custom pool or client wrapper should pass `pg`'s `command` through in query results: the plugin reads it from the `COMMIT` result to detect a transaction that PostgreSQL rolled back because one of its statements failed, and without it such a transaction reports success with nothing stored.
 
-Operations attempted before successful initialization fail with `DATABASE_NOT_INITIALIZED`. Call `createSchema` before `initializeDatabase`. Configuration and registrations become immutable once schema preparation begins. `preventCreatingCollection(true)` makes instance initialization validate existing storage without issuing creation DDL. A rejected initialization request leaves readiness as it was; a ready instance keeps serving while it is initialized again, and becomes unavailable if that initialization fails. Use `mode: 'validate'` to check a live instance, because `create` mode locks the managed tables against writes until it commits. `simfinity.compileDatabaseSchema()` returns the instance's DDL for review or export.
+Operations attempted before successful initialization fail with `DATABASE_NOT_INITIALIZED`. Call `createSchema` before `initializeDatabase`. Configuration and registrations become immutable once schema preparation begins. `preventCreatingCollection(true)` makes instance initialization validate existing storage without issuing creation DDL. A rejected initialization request leaves readiness as it was; a ready instance keeps serving while it is initialized again, and becomes unavailable if that initialization fails. `create` mode reads the catalog without table locks and locks nothing when nothing is missing. When it creates objects, writers of the tables that it changes, of existing tables that a new foreign key references, or of roots whose keys it rebuilds wait until it commits, so use `mode: 'validate'` to check a live instance. `simfinity.compileDatabaseSchema()` returns the instance's DDL for review or export.
 
 A default module instance is also available when a singleton facade is preferable:
 
@@ -55,14 +55,14 @@ await initializeDatabase({ mode: 'validate' });
 
 Called without arguments after `createSchema()`, the module's `describeDatabase()` and `compileDatabaseSchema()` describe and compile this default instance in its configured schema.
 
-Transactions use one borrowed `pg` client and repeatable-read isolation. A supplied Simfinity PostgreSQL session joins the active transaction. Serialization failures and deadlocks are retried up to five times, each after a short random delay that starts once the client is released; mutation input is reset for each attempt. Unknown commit outcomes are not replayed. The caller owns the pool lifecycle.
+Transactions use one borrowed `pg` client and repeatable-read isolation. Reads without a session of types without owned embedded tables run as a single statement on a pooled connection instead. A supplied Simfinity PostgreSQL session joins the active transaction. Serialization failures and deadlocks are retried up to five times, each after a short random delay that starts once the client is released; mutation input is reset for each attempt. Unknown commit outcomes are not replayed. The caller owns the pool lifecycle.
 
 The module and every `createPostgres` instance expose the shared `auth`, `validators`, `scalars`, and `plugins` helpers. These are the same helper objects exported by the MongoDB package, so rules, scalar identities, and errors can be shared safely between backends.
 
 MCP integration is an independent opt-in and does not add MCP dependencies to PostgreSQL applications:
 
 ```sh
-npm install @simtlix/simfinity-mcp@3.5.8 @modelcontextprotocol/sdk@^1.31.0
+npm install @simtlix/simfinity-mcp@3.6.0 @modelcontextprotocol/sdk@^1.31.0
 ```
 
 ```javascript
@@ -101,4 +101,4 @@ const statements = compileDatabaseSchema(description);
 await initializeDatabase(pool, description, { mode: 'validate' });
 ```
 
-Low-level `describeDatabase(registrations, { schema })` uses the `public` schema when `schema` is omitted, not the schema of a configured runtime; pass the schema given to `configure()` or `createPostgres()`, or call `describeDatabase()` and `compileDatabaseSchema()` without arguments for the default instance. `compileDatabaseSchema` returns reviewable SQL. Low-level `initializeDatabase(pool, description, { mode })` creates or validates storage transactionally and never closes the pool. Create mode adds missing objects and rejects incompatible definitions; validate mode performs no DDL. Neither mode performs destructive schema synchronization or data migration.
+Low-level `describeDatabase(registrations, { schema, refreshTriggers, ownerIndexes })` uses the `public` schema when `schema` is omitted, not the schema of a configured runtime; pass the schema given to `configure()` or `createPostgres()`, or call `describeDatabase()` and `compileDatabaseSchema()` without arguments for the default instance. `compileDatabaseSchema` returns reviewable SQL. Low-level `initializeDatabase(pool, description, { mode })` creates or validates storage transactionally and never closes the pool. Create mode adds missing objects and rejects incompatible definitions; validate mode performs no DDL. Neither mode performs destructive schema synchronization or data migration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-postgres",
-  "version": "3.5.8",
+  "version": "3.6.0",
   "description": "PostgreSQL GraphQL runtime and schema generation with foreign keys for Simfinity",
   "type": "module",
   "main": "./src/index.js",
@@ -27,8 +27,8 @@
     "directory": "packages/postgres"
   },
   "dependencies": {
-    "@simtlix/simfinity-core": "3.5.8",
-    "@simtlix/simfinity-sql": "3.5.8",
+    "@simtlix/simfinity-core": "3.6.0",
+    "@simtlix/simfinity-sql": "3.6.0",
     "pg": "^8.16.3"
   },
   "peerDependencies": {

package/src/plugin.js

@@ -5,7 +5,7 @@ import { describeRelationalSchema } from './schema/describe.js';
 import { initializeDatabase } from './schema/initialize.js';
 import { compileDatabaseSchema } from './schema/ddl.js';
 import { compileQuery } from './query/compiler.js';
-import { compileRecord } from './record-statements.js';
+import { compileRecord, compileRecordBatch, MAX_RECORD_BATCH_VALUES } from './record-statements.js';
 import { castId, encodeScalar, decodeScalar, encodeParameter, isRetryableDatabaseError, normalizeDatabaseError } from './codecs.js';
 
 export const postgresPlugin = (options) => ({
@@ -14,13 +14,18 @@ export const postgresPlugin = (options) => ({
   displayName: 'PostgreSQL',
   defaultSchema: 'public',
   options: options || null,
-  capabilities: ['transactions', 'foreignKeys', 'deferredForeignKeys', 'embeddedValues', 'ownedRecords', 'scalarLists', 'uniqueValues', 'nullableUnique'],
+  // singleStatementReads: one statement reads one snapshot at any isolation level, so a read without owned
+  // tables needs no repeatable-read transaction.
+  capabilities: ['transactions', 'foreignKeys', 'deferredForeignKeys', 'embeddedValues', 'ownedRecords', 'scalarLists', 'uniqueValues', 'nullableUnique', 'singleStatementReads'],
   naming: { validateIdentifier: identifier, generatedName },
-  describeSchema: describeRelationalSchema,
+  // The runtime passes its bound configuration: createPostgres(options) or configure(value).
+  describeSchema: (plan, configuration) => describeRelationalSchema(plan, { refreshTriggers: configuration?.refreshTriggers, ownerIndexes: configuration?.ownerIndexes }),
   initialize: (configuration, description, initialization) => initializeDatabase(configuration.pool, description, initialization),
   compileSchema: compileDatabaseSchema,
   compileQuery,
   compileRecord,
+  compileRecordBatch,
+  maxRecordBatchValues: MAX_RECORD_BATCH_VALUES,
   values: { createId: randomUUID, castId, encodeScalar, decodeScalar, encodeEmbedded: JSON.stringify },
   driver: {
     assertConfiguration(configuration) {

package/src/query/compiler.js

@@ -4,8 +4,12 @@ import { encodeScalar, storageTypes, invalidValue } from '../codecs.js';
 
 const unsupported = (message) => { throw new SimfinityError(message, 'UNSUPPORTED_QUERY', 400); };
 
-/** Compiles validated paths; all caller values are parameters, identifiers come from metadata. */
-export const compileQuery = (models, database, plan, extra = null) => {
+/**
+ * Compiles validated paths; all caller values are parameters, identifiers come from metadata.
+ * `configuration.explicitNullsOrder: true` keeps the NULLS clause on every sort term, as 3.5.9 did.
+ */
+export const compileQuery = (models, database, plan, extra = null, configuration = null) => {
+  const explicitNullsOrder = configuration?.explicitNullsOrder === true;
   const values = [];
   const joins = new Map();
   let serial = 0;
@@ -151,7 +155,12 @@ export const compileQuery = (models, database, plan, extra = null) => {
         }
         let sql = context.vector ? arrayFrom(context.vector, expression) : expression;
         if (type === 'text') sql = `(${sql}) COLLATE "pg_catalog"."C"`;
-        return { sql, field: identity ? { ...field, scalar: 'ID' } : field, type: dateNumeric ? 'double precision' : type, list: field.list || !!context.vector, vector: !!context.vector, dateNumeric, sortKey };
+        // A NOT NULL column of the root row has no nulls to place, so its sort needs no NULLS clause and a
+        // default-order btree (the primary key or a declared index) can return it in order. Joined and
+        // embedded paths can be NULL even for NOT NULL columns, so they keep the clause.
+        const notNull = !context.json && !context.vector && !field.list && context.alias === 't0'
+          && context.table.columns.find((item) => item.name === (identity ? 'id' : field.storageName))?.nullable === false;
+        return { sql, field: identity ? { ...field, scalar: 'ID' } : field, type: dateNumeric ? 'double precision' : type, list: field.list || !!context.vector, vector: !!context.vector, dateNumeric, sortKey, notNull };
       }
     }
     unsupported('Invalid query path');
@@ -226,6 +235,8 @@ export const compileQuery = (models, database, plan, extra = null) => {
     condition += ` AND ${col('t0', column.name)} = ${bind(extra.id, 'uuid')}`;
   }
   let select = 't0.*';
+  // List values that MIN and MAX facts read, each evaluated once per row in a lateral subquery.
+  const laterals = new Map();
   let group = '';
   const order = [];
   if (plan.mode === 'count') select = 'count(*) AS size';
@@ -243,7 +254,15 @@ export const compileQuery = (models, database, plan, extra = null) => {
       if (fact.operation === 'COUNT') operation = 'count(*)';
       else if (expression.list) {
         if (fact.operation === 'SUM' || fact.operation === 'AVG') operation = fact.operation === 'SUM' ? '0' : 'NULL';
-        else operation = `(array_agg(${expression.sql} ORDER BY ${helper('value_key', expression.sql, literal(expression.field.scalar))} ${fact.operation === 'MIN' ? 'ASC' : 'DESC'}) FILTER (WHERE ${expression.sql} IS NOT NULL AND ${expression.sql} <> 'null'::jsonb))[1]`;
+        else {
+          // The list value is a correlated subquery that the aggregate reads four times; MIN and MAX of the
+          // same path share one evaluation per row. OFFSET 0 keeps the planner from pulling the subquery up
+          // and copying the expression back, and a subquery without FROM keeps one row per root row.
+          const key = fact.path.join('.');
+          if (!laterals.has(key)) laterals.set(key, { alias: `f${laterals.size}`, sql: expression.sql });
+          const value = `${laterals.get(key).alias}.value`;
+          operation = `(array_agg(${value} ORDER BY ${helper('value_key', value, literal(expression.field.scalar))} ${fact.operation === 'MIN' ? 'ASC' : 'DESC'}) FILTER (WHERE ${value} IS NOT NULL AND ${value} <> 'null'::jsonb))[1]`;
+        }
       }
       else if (['SUM', 'AVG'].includes(fact.operation) && !['Int', 'Float'].includes(expression.field.scalar)) operation = fact.operation === 'SUM' ? '0' : 'NULL';
       else if (['MIN', 'MAX'].includes(fact.operation) && expression.type === 'boolean') operation = `${fact.operation === 'MIN' ? 'bool_and' : 'bool_or'}(${expression.sql})`;
@@ -263,9 +282,11 @@ export const compileQuery = (models, database, plan, extra = null) => {
     const expression = path(term.path, 'sort');
     const key = expression.sql;
     if (expression.sortKey) { order.push(`${expression.sortKey(term.order)} ${term.order} NULLS ${term.order === 'ASC' ? 'FIRST' : 'LAST'}`); continue; }
-    order.push(`${key} ${term.order} NULLS ${term.order === 'ASC' ? 'FIRST' : 'LAST'}`);
+    order.push(expression.notNull && !explicitNullsOrder ? `${key} ${term.order}` : `${key} ${term.order} NULLS ${term.order === 'ASC' ? 'FIRST' : 'LAST'}`);
   }
-  let text = `SELECT ${select} FROM ${qualified(database.schema, root.name)} t0 ${[...joins.values()].map((item) => item.sql).join(' ')} WHERE ${condition}${group}`;
+  // Laterals follow every join, so their expressions can read the root row and any joined alias.
+  const lateralSQL = [...laterals.values()].map((item) => ` CROSS JOIN LATERAL (SELECT ${item.sql} AS value OFFSET 0) ${item.alias}`).join('');
+  let text = `SELECT ${select} FROM ${qualified(database.schema, root.name)} t0 ${[...joins.values()].map((item) => item.sql).join(' ')}${lateralSQL} WHERE ${condition}${group}`;
   if (plan.mode === 'aggregate') text = `SELECT * FROM (${text}) aggregated`;
   if (order.length) text += ` ORDER BY ${order.join(', ')}`;
   if (plan.pagination) text += ` LIMIT ${bind(plan.pagination.limit, 'bigint')} OFFSET ${bind(plan.pagination.offset, 'bigint')}`;

package/src/record-statements.js

@@ -20,3 +20,14 @@ export const compileRecord = (database, operation) => {
   }
   throw new SimfinityError(`Unknown record operation ${kind}`, 'INVALID_RECORD_OPERATION', 400);
 };
+
+// Values (rows times columns) per multi-row INSERT, well below PostgreSQL's 65,535 bind parameters.
+export const MAX_RECORD_BATCH_VALUES = 32767;
+/** One multi-row INSERT of owned rows that share their columns in the same order; no rows are returned. */
+export const compileRecordBatch = (database, { table: storage, rows }) => {
+  const names = Object.keys(rows[0]);
+  const types = names.map((name) => storage.columns.find((column) => column.name === name).type);
+  const values = [];
+  const tuples = rows.map((row) => `(${names.map((name, index) => { values.push(row[name]); return `$${values.length}::${types[index]}`; }).join(', ')})`);
+  return { text: `INSERT INTO ${qualified(database.schema, storage.name)} (${names.map((name) => q(name)).join(', ')}) VALUES ${tuples.join(', ')}`, values };
+};

package/src/schema/constraints.js

@@ -12,13 +12,138 @@ const dateTimeValidation = `DECLARE parts integer[]; BEGIN
     AND parts >= ARRAY[-271821, 4, 20, 0, 0, 0, 0] AND parts <= ARRAY[275760, 9, 13, 0, 0, 0, 0];
 END;`;
 
+const functionObject = (name, args, returns, body, immutable = false) => ({ name, arguments: args, returns, language: 'plpgsql', volatility: immutable ? 'IMMUTABLE' : 'VOLATILE', configuration: ['search_path=pg_catalog', 'TimeZone=UTC', 'DateStyle=ISO, YMD'], body });
+// The ownership chain from its root (t0) to its last table.
+const joinChain = (schema, path, left = false) => path.map((table, index) => {
+  if (!index) return `${qualified(schema, table.name)} t0`;
+  const parent = path[index - 1];
+  return `${left ? 'LEFT ' : ''}JOIN ${qualified(schema, table.name)} t${index} ON t${index}.__owner_id = t${index - 1}.${q(parent.primaryKey.columns[0])}${left ? ` AND t${index - 1}.${q(table.ownership.stateColumn)} = 'present'${parent.ownership?.nullableItems ? ` AND t${index - 1}.__item_present` : ''}` : ''}`;
+}).join(' ');
+
+/**
+ * The refresh-trigger objects of one table of a maintained root; `path` runs from the root to the table.
+ * 'perRow' (3.5.9): a touch trigger bumps the root's guard row and a deferred trigger refreshes the root
+ * once per changed row. 'perRoot': while the guard row's trigger stays deferred, the touch trigger marks
+ * the guard row dirty (a negative version) once per transaction and that trigger refreshes the root once
+ * at commit; under IMMEDIATE both happen once per changed row (guardTriggerObjects).
+ */
+const refreshTriggerObjects = (schema, path, item, layout) => {
+  const table = path.at(-1);
+  const owner = (record) => path.length === 1 ? `${record}.id` : `(SELECT t0.id FROM ${joinChain(schema, path.slice(0, -1))} WHERE t${path.length - 2}.${q(path.at(-2).primaryKey.columns[0])} = ${record}.__owner_id)`;
+  const guard = q(item.guardTable);
+  const target = `${qualified(schema, item.guardTable)} (__owner_id${layout === 'perRoot' ? ', version' : ''}) SELECT __root_id${layout === 'perRoot' ? ', -1' : ''} WHERE EXISTS (SELECT 1 FROM ${qualified(schema, item.rootTable)} WHERE id = __root_id) ON CONFLICT (__owner_id) DO UPDATE SET`;
+  // A dirty row written by an earlier transaction (its guard trigger was disabled) is marked again.
+  const touch = layout === 'perRoot'
+    ? `INSERT INTO ${target} version = -(abs(${guard}.version) + 1) WHERE ${guard}.version >= 0 OR age(${guard}.xmin) <> 0;`
+    : `INSERT INTO ${target} version = ${guard}.version + 1;`;
+  const objects = { functions: [], triggers: [] };
+  for (const deferred of layout === 'perRow' ? [false, true] : [false]) {
+    const name = generatedName(table.name, deferred ? 'deferred' : 'touch');
+    const action = deferred ? `PERFORM ${qualified(schema, item.refreshFunction)}(__root_id);` : touch;
+    objects.functions.push(functionObject(name, [], 'trigger', `DECLARE __root_id uuid; __old_root_id uuid; BEGIN
+  IF TG_OP <> 'INSERT' THEN __old_root_id := ${owner('OLD')}; END IF;
+  IF TG_OP <> 'DELETE' THEN __root_id := ${owner('NEW')}; END IF;
+  IF __old_root_id IS NOT NULL AND __old_root_id IS DISTINCT FROM __root_id THEN
+    DECLARE __new_root_id uuid := __root_id; BEGIN __root_id := __old_root_id; ${action} __root_id := __new_root_id; END;
+  END IF;
+  IF __root_id IS NOT NULL THEN ${action} END IF;
+  RETURN NULL;
+END`));
+    objects.triggers.push({ name, table: table.name, function: name, constraint: deferred, deferrable: deferred, initiallyDeferred: deferred });
+  }
+  return objects;
+};
+// 'perRoot': at commit, each dirty guard row is marked clean and its root refreshed once. The event is
+// queued by the touch write itself, so it always follows the touch, whatever the trigger names; committed
+// guard rows stay clean, as earlier versions wrote them. The once-per-transaction saving holds only while
+// this trigger stays deferred: under IMMEDIATE its event fires at the end of the touch trigger's guard
+// upsert, so the root is refreshed once per changed row, as with 'perRow', and the guard row is written
+// twice per row (marked dirty, then clean).
+const guardTriggerObjects = (schema, item) => {
+  const name = generatedName(item.guardTable, 'deferred');
+  return {
+    functions: [functionObject(name, [], 'trigger', `BEGIN
+  IF NEW.version < 0 THEN
+    UPDATE ${qualified(schema, item.guardTable)} SET version = -version WHERE __owner_id = NEW.__owner_id AND version < 0;
+    IF FOUND THEN PERFORM ${qualified(schema, item.refreshFunction)}(NEW.__owner_id); END IF;
+  END IF;
+  RETURN NULL;
+END`)],
+    // Only dirty rows queue an event: not the clean-up update, nor a backfill's guard inserts.
+    triggers: [{ name, table: item.guardTable, function: name, constraint: true, deferrable: true, initiallyDeferred: true, events: ['INSERT', 'UPDATE'], when: 'new.version < 0' }],
+  };
+};
+
+/**
+ * For each maintained root of a description, the refresh-trigger functions and triggers of both layouts,
+ * built from the description alone. Tables follow the order of the description's touch triggers.
+ */
+export const maintenanceLayouts = (description) => {
+  const { schema } = description;
+  const byName = new Map(description.tables.map((table) => [table.name, table]));
+  const chainOf = (table) => {
+    const path = [table];
+    while (path[0].ownership && byName.has(path[0].ownership.ownerTable)) path.unshift(byName.get(path[0].ownership.ownerTable));
+    return path;
+  };
+  const touches = (description.triggers || []).filter((trigger) => !trigger.constraint && byName.has(trigger.table) && trigger.name === generatedName(trigger.table, 'touch'));
+  const layouts = new Map();
+  for (const item of description.maintenance || []) {
+    const layout = { perRow: { functions: [], triggers: [] }, perRoot: { functions: [], triggers: [] } };
+    for (const touch of touches) {
+      const path = chainOf(byName.get(touch.table));
+      if (path[0].name !== item.rootTable || path[0].ownership) continue;
+      for (const name of ['perRow', 'perRoot']) {
+        const objects = refreshTriggerObjects(schema, path, item, name);
+        layout[name].functions.push(...objects.functions);
+        layout[name].triggers.push(...objects.triggers);
+      }
+    }
+    const guard = guardTriggerObjects(schema, item);
+    layout.perRoot.functions.push(...guard.functions);
+    layout.perRoot.triggers.push(...guard.triggers);
+    layouts.set(item.rootTable, layout);
+  }
+  return layouts;
+};
+
+/** 'perRoot' when the root's guard table carries the deferred trigger, otherwise 'perRow'. */
+export const layoutOf = (description, item) => ((description.triggers || []).some((trigger) => trigger.constraint && trigger.table === item.guardTable) ? 'perRoot' : 'perRow');
+
+/**
+ * Replace the refresh-trigger objects of the chosen roots (a Map of root table to layout) with that layout's,
+ * at the position of the root's first object. Every other object and the list order are kept.
+ */
+export const withLayouts = (description, choices, layouts = maintenanceLayouts(description)) => {
+  const owners = { functions: new Map(), triggers: new Map() };
+  const keys = { functions: (object) => object.name, triggers: (object) => JSON.stringify([object.table, object.name]) };
+  for (const [root, layout] of layouts) {
+    for (const kind of ['functions', 'triggers']) {
+      for (const object of [...layout.perRow[kind], ...layout.perRoot[kind]]) owners[kind].set(keys[kind](object), root);
+    }
+  }
+  const replace = (kind) => {
+    const output = [];
+    const done = new Set();
+    for (const object of description[kind] || []) {
+      const root = owners[kind].get(keys[kind](object));
+      if (!choices.has(root)) output.push(object);
+      else if (!done.has(root)) {
+        done.add(root);
+        output.push(...layouts.get(root)[choices.get(root)][kind]);
+      }
+    }
+    return output;
+  };
+  return { ...description, functions: replace('functions'), triggers: replace('triggers') };
+};
+
 /** Database-side validation and multikey maintenance. All bodies resolve names in pg_catalog. */
 export const constraintBuilder = (schema, tables, { addTable, addColumn, addReference, addIndex, addCheck }) => {
   const functions = []; const triggers = []; const uniquePaths = [];
   const fn = (name, args, returns, body, immutable = false) => {
     if (functions.some((item) => item.name === name)) invalid(`Function name collision: ${name}`);
-    const result = { name, arguments: args, returns, language: 'plpgsql', volatility: immutable ? 'IMMUTABLE' : 'VOLATILE', configuration: ['search_path=pg_catalog', 'TimeZone=UTC', 'DateStyle=ISO, YMD'], body };
-    functions.push(result);
+    functions.push(functionObject(name, args, returns, body, immutable));
     return qualified(schema, name);
   };
   const jsonValidator = (table, field, path = []) => {
@@ -55,11 +180,7 @@ END`, true);
     while (result[0].ownership) result.unshift(tables.find((item) => item.name === result[0].ownership.ownerTable));
     return result;
   };
-  const joins = (path, left = false) => path.map((table, index) => {
-    if (!index) return `${qualified(schema, table.name)} t0`;
-    const parent = path[index - 1];
-    return `${left ? 'LEFT ' : ''}JOIN ${qualified(schema, table.name)} t${index} ON t${index}.__owner_id = t${index - 1}.${q(parent.primaryKey.columns[0])}${left ? ` AND t${index - 1}.${q(table.ownership.stateColumn)} = 'present'${parent.ownership?.nullableItems ? ` AND t${index - 1}.__item_present` : ''}` : ''}`;
-  }).join(' ');
+  const joins = (path, left = false) => joinChain(schema, path, left);
   const finish = () => {
     const sources = [...tables];
     const roots = sources.filter((table) => !table.ownership && (sources.some((owned) => owned.ownership && chain(owned)[0] === table) || uniquePaths.some((key) => chain(key.table)[0] === table)));
@@ -112,28 +233,17 @@ END`, true);
         rebuild += `\n  DELETE FROM ${qualified(schema, storage.name)} WHERE __owner_id = $1;\n  INSERT INTO ${qualified(schema, storage.name)} (__owner_id, kind, value) ${query};`;
       }
       const refreshName = generatedName(root.name, 'refresh');
-      const refresh = fn(refreshName, ['uuid'], 'void', `BEGIN\n  PERFORM ${validate}($1);${rebuild}\nEND`);
-      maintenance.push({ rootTable: root.name, guardTable: guard.name, validateFunction: validateName, refreshFunction: refreshName });
+      fn(refreshName, ['uuid'], 'void', `BEGIN\n  PERFORM ${validate}($1);${rebuild}\nEND`);
+      const item = { rootTable: root.name, guardTable: guard.name, validateFunction: validateName, refreshFunction: refreshName };
+      maintenance.push(item);
       // Touch a real shared tuple at write time, not only at deferred-check time.
       // RR writers must conflict on its version; RC writers then refresh using a new
       // command snapshot after acquiring it. Lock-only reads permit stale RR keys.
+      // describeRelationalSchema swaps these 'perRow' objects for 'perRoot' ones when asked.
       for (const table of [root, ...ownedTables]) {
-        const path = chain(table);
-        const owner = (record) => table === root ? `${record}.id` : `(SELECT t0.id FROM ${joins(path.slice(0, -1))} WHERE t${path.length - 2}.${q(path.at(-2).primaryKey.columns[0])} = ${record}.__owner_id)`;
-        for (const deferred of [false, true]) {
-          const name = generatedName(table.name, deferred ? 'deferred' : 'touch');
-          const action = deferred ? `PERFORM ${refresh}(__root_id);` : `INSERT INTO ${qualified(schema, guard.name)} (__owner_id) SELECT __root_id WHERE EXISTS (SELECT 1 FROM ${qualified(schema, root.name)} WHERE id = __root_id) ON CONFLICT (__owner_id) DO UPDATE SET version = ${q(guard.name)}.version + 1;`;
-          fn(name, [], 'trigger', `DECLARE __root_id uuid; __old_root_id uuid; BEGIN
-  IF TG_OP <> 'INSERT' THEN __old_root_id := ${owner('OLD')}; END IF;
-  IF TG_OP <> 'DELETE' THEN __root_id := ${owner('NEW')}; END IF;
-  IF __old_root_id IS NOT NULL AND __old_root_id IS DISTINCT FROM __root_id THEN
-    DECLARE __new_root_id uuid := __root_id; BEGIN __root_id := __old_root_id; ${action} __root_id := __new_root_id; END;
-  END IF;
-  IF __root_id IS NOT NULL THEN ${action} END IF;
-  RETURN NULL;
-END`);
-          triggers.push({ name, table: table.name, function: name, constraint: deferred, deferrable: deferred, initiallyDeferred: deferred });
-        }
+        const objects = refreshTriggerObjects(schema, chain(table), item, 'perRow');
+        for (const object of objects.functions) fn(object.name, object.arguments, object.returns, object.body);
+        triggers.push(...objects.triggers);
       }
     }
     return { functions, triggers, maintenance };

package/src/schema/ddl.js

@@ -1,4 +1,4 @@
-import { identifier, qualified, columnsSQL, literal } from './sql.js';
+import { identifier, qualified, columnsSQL, literal, invalid } from './sql.js';
 
 export const createTableSQL = (schema, table) => {
   const columns = table.columns.map((column) => `${identifier(column.name)} ${column.type}${column.collation ? ` COLLATE ${qualified('pg_catalog', column.collation)}` : ''}${column.nullable ? '' : ' NOT NULL'}${column.default ? ` DEFAULT ${column.default}` : ''}`);
@@ -16,7 +16,9 @@ export const createFunctionSQL = (schema, fn) => {
   }).join(' ');
   return `CREATE FUNCTION ${qualified(schema, fn.name)}(${fn.arguments.join(', ')}) RETURNS ${fn.returns} LANGUAGE ${fn.language} ${fn.volatility} CALLED ON NULL INPUT SECURITY INVOKER PARALLEL UNSAFE ${settings} AS ${literal(fn.body)}`;
 };
-export const createTriggerSQL = (schema, trigger) => `CREATE ${trigger.constraint ? 'CONSTRAINT ' : ''}TRIGGER ${identifier(trigger.name)} AFTER INSERT OR UPDATE OR DELETE ON ${qualified(schema, trigger.table)} ${trigger.constraint ? 'DEFERRABLE INITIALLY DEFERRED ' : ''}FOR EACH ROW EXECUTE FUNCTION ${qualified(schema, trigger.function)}()`;
+/** Row events a trigger fires on; a trigger without `events` fires on all three. */
+export const triggerEvents = (trigger) => (trigger.events || ['INSERT', 'UPDATE', 'DELETE']).map((event) => (['INSERT', 'UPDATE', 'DELETE'].includes(event) ? event : invalid(`Unsupported trigger event: ${String(event)}`)));
+export const createTriggerSQL = (schema, trigger) => `CREATE ${trigger.constraint ? 'CONSTRAINT ' : ''}TRIGGER ${identifier(trigger.name)} AFTER ${triggerEvents(trigger).join(' OR ')} ON ${qualified(schema, trigger.table)} ${trigger.constraint ? 'DEFERRABLE INITIALLY DEFERRED ' : ''}FOR EACH ROW ${trigger.when ? `WHEN (${trigger.when}) ` : ''}EXECUTE FUNCTION ${qualified(schema, trigger.function)}()`;
 
 /** Tables/primary keys precede all FKs so forward and cyclic references work. */
 export const compileDatabaseSchema = (description) => [

package/src/schema/describe.js

@@ -1,15 +1,31 @@
 import { describeModels } from '@simtlix/simfinity-core';
 import { planRelationalSchema } from '@simtlix/simfinity-sql';
 import { queryFunctions } from '../query/functions.js';
-import { constraintBuilder } from './constraints.js';
+import { constraintBuilder, withLayouts } from './constraints.js';
 import { identifier, literal, generatedName, invalid } from './sql.js';
 
 const scalarTypes = { ID: 'uuid', String: 'text', Enum: 'text', Int: 'integer', Float: 'double precision', Boolean: 'boolean', DateTime: 'timestamp with time zone', Embedded: 'jsonb' };
 const physicalType = (column) => `${scalarTypes[column.scalar]}${column.list ? '[]' : ''}`;
 const physicalDefault = (value) => value.kind === 'identity' ? 'gen_random_uuid()' : typeof value.value === 'string' ? `${literal(value.value)}::text` : String(value.value);
+// The first value is the default, which keeps the 3.5.9 description.
+const option = (name, value, values) => {
+  if (value !== undefined && !values.includes(value)) invalid(`Unknown PostgreSQL ${name} option: ${String(value)}. Use ${values.map((item) => `'${item}'`).join(' or ')}`);
+  return value ?? values[0];
+};
 
-/** Lower engine-independent relational guarantees into PostgreSQL storage and enforcement. */
-export const describeRelationalSchema = (plan) => {
+/**
+ * Lower engine-independent relational guarantees into PostgreSQL storage and enforcement. Two opt-in
+ * options change what new databases get:
+ * - `refreshTriggers: 'perRoot'` refreshes each maintained root once per transaction, while its guard trigger
+ *   stays deferred, instead of once per changed row ('perRow'). Initialization keeps each existing root on
+ *   the layout its database holds;
+ * - `ownerIndexes: 'minimal'` omits the (__owner_id) index of owned and guard tables, which their primary
+ *   key or a unique index already covers ('all' keeps it). 'minimal' accepts existing owner indexes; a
+ *   database created with 'minimal' fails validation under 'all', and create mode adds the indexes back.
+ */
+export const describeRelationalSchema = (plan, options) => {
+  const refreshTriggers = option('refreshTriggers', options?.refreshTriggers, ['perRow', 'perRoot']);
+  const ownerIndexes = option('ownerIndexes', options?.ownerIndexes, ['all', 'minimal']);
   const { schema } = plan;
   identifier(schema);
   const tables = [];
@@ -79,6 +95,12 @@ export const describeRelationalSchema = (plan) => {
   }
   const generated = constraints.finish();
   generated.functions.push(...queryFunctions(schema));
+  if (ownerIndexes === 'minimal') {
+    for (const table of tables.filter((item) => item.ownership || item.auxiliary?.kind === 'guard')) {
+      const covered = table.primaryKey.columns[0] === '__owner_id' || table.indexes.some((index) => index.unique && index.columns[0] === '__owner_id');
+      if (covered) table.indexes = table.indexes.filter((index) => index.unique || index.columns.length !== 1 || index.columns[0] !== '__owner_id');
+    }
+  }
   // PostgreSQL shares one namespace for table and index names.
   const relationNames = new Set(tables.map((table) => table.name));
   for (const table of tables) {
@@ -92,10 +114,18 @@ export const describeRelationalSchema = (plan) => {
       relationNames.add(index.name);
     }
   }
-  return { schema, tables: tables.sort((a, b) => a.name.localeCompare(b.name)), ...generated };
+  const description = { schema, tables: tables.sort((a, b) => a.name.localeCompare(b.name)), ...generated };
+  if (refreshTriggers === 'perRow') return description;
+  const result = withLayouts(description, new Map(description.maintenance.map((item) => [item.rootTable, 'perRoot'])));
+  const functionNames = new Set();
+  for (const fn of result.functions) {
+    if (functionNames.has(fn.name)) invalid(`Function name collision: ${fn.name}`);
+    functionNames.add(fn.name);
+  }
+  return result;
 };
 
 /** Compile GraphQL storage metadata into the compatible PostgreSQL description. */
-export const describeDatabase = (registrations, { schema = 'public' } = {}) => describeRelationalSchema(planRelationalSchema(describeModels(registrations), {
+export const describeDatabase = (registrations, { schema = 'public', refreshTriggers, ownerIndexes } = {}) => describeRelationalSchema(planRelationalSchema(describeModels(registrations), {
   schema, naming: { validateIdentifier: identifier, generatedName },
-}));
+}), { refreshTriggers, ownerIndexes });

package/src/schema/initialize.js

@@ -1,6 +1,7 @@
 import { SimfinityError } from '@simtlix/simfinity-core';
 import { identifier, qualified, generatedName } from './sql.js';
-import { createTableSQL, createForeignKeySQL, createIndexSQL, createFunctionSQL, createTriggerSQL } from './ddl.js';
+import { createTableSQL, createForeignKeySQL, createIndexSQL, createFunctionSQL, createTriggerSQL, triggerEvents } from './ddl.js';
+import { maintenanceLayouts, layoutOf, withLayouts } from './constraints.js';
 
 const mismatch = (object, reason) => {
   throw new SimfinityError(`Schema mismatch at ${object}: ${reason}. Apply an explicit migration before startup.`, 'SCHEMA_MISMATCH', 409);
@@ -43,19 +44,14 @@ export const normalizeExpression = (expression) => {
   return value;
 };
 
-const readTable = async (client, schema, name) => {
-  const { rows: relations } = await client.query(`SELECT c.oid, c.relkind, c.relpersistence, c.relrowsecurity, c.relforcerowsecurity
-    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 AND c.relname = $2`, [schema, name]);
-  if (!relations.length) return null;
-  const relation = relations[0];
-  if (relation.relkind !== 'r' || relation.relpersistence !== 'p' || relation.relrowsecurity || relation.relforcerowsecurity) mismatch(`${schema}.${name}`, 'expected a persistent ordinary table without row security');
-  const { rows: columns } = await client.query(`SELECT a.attname AS name, format_type(a.atttypid, a.atttypmod) AS type,
+// Catalog columns read for each managed relation, function and trigger.
+const relationColumns = 'c.oid, c.relkind, c.relpersistence, c.relrowsecurity, c.relforcerowsecurity';
+const columnRows = `a.attname AS name, format_type(a.atttypid, a.atttypmod) AS type,
     NOT a.attnotnull AS nullable, pg_get_expr(d.adbin, d.adrelid) AS "default", a.attidentity, a.attgenerated,
     col.collname AS collation, ns.nspname AS collation_schema
     FROM pg_attribute a LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
-    LEFT JOIN pg_collation col ON col.oid = a.attcollation LEFT JOIN pg_namespace ns ON ns.oid = col.collnamespace
-    WHERE a.attrelid = $1 AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`, [relation.oid]);
-  const { rows: constraints } = await client.query(`SELECT c.conname AS name, c.contype AS type,
+    LEFT JOIN pg_collation col ON col.oid = a.attcollation LEFT JOIN pg_namespace ns ON ns.oid = col.collnamespace`;
+const constraintRows = `c.conname AS name, c.contype AS type,
     c.condeferrable AS deferrable, c.condeferred AS deferred, c.convalidated AS validated,
     COALESCE((to_jsonb(c)->>'conenforced')::boolean, true) AS enforced,
     c.confdeltype AS delete_action, c.confupdtype AS update_action, c.confmatchtype AS match_type, c.connoinherit AS no_inherit,
@@ -66,9 +62,8 @@ const readTable = async (client, schema, name) => {
       JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.num ORDER BY k.pos) AS columns,
     ARRAY(SELECT a.attname::text FROM unnest(c.confkey) WITH ORDINALITY k(num, pos)
       JOIN pg_attribute a ON a.attrelid = c.confrelid AND a.attnum = k.num ORDER BY k.pos) AS target_columns
-    FROM pg_constraint c LEFT JOIN pg_class t ON t.oid = c.confrelid LEFT JOIN pg_namespace n ON n.oid = t.relnamespace
-    WHERE c.conrelid = $1`, [relation.oid]);
-  const { rows: indexes } = await client.query(`SELECT ic.relname AS name, i.indisprimary AS primary,
+    FROM pg_constraint c LEFT JOIN pg_class t ON t.oid = c.confrelid LEFT JOIN pg_namespace n ON n.oid = t.relnamespace`;
+const indexRows = `ic.relname AS name, i.indisprimary AS primary,
     i.indisunique AS unique, i.indnullsnotdistinct AS nulls_not_distinct, i.indisvalid AS valid, i.indisready AS ready,
     i.indimmediate AS immediate, am.amname AS method, i.indnatts = i.indnkeyatts AS no_include,
     i.indpred IS NULL AS no_predicate, i.indexprs IS NULL AS no_expression,
@@ -79,10 +74,88 @@ const readTable = async (client, schema, name) => {
     NOT EXISTS (SELECT 1 FROM unnest(i.indcollation) WITH ORDINALITY col(oid, pos)
       JOIN unnest(i.indkey) WITH ORDINALITY k(num, pos) USING(pos)
       JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.num WHERE col.oid <> a.attcollation) AS default_collation
-    FROM pg_index i JOIN pg_class ic ON ic.oid = i.indexrelid JOIN pg_am am ON am.oid = ic.relam WHERE i.indrelid = $1`, [relation.oid]);
+    FROM pg_index i JOIN pg_class ic ON ic.oid = i.indexrelid JOIN pg_am am ON am.oid = ic.relam`;
+const functionRows = `p.oid, pg_get_function_identity_arguments(p.oid) AS arguments,
+      pg_get_function_result(p.oid) AS returns, p.prosrc AS body, l.lanname AS language, p.provolatile AS volatility,
+      p.proconfig AS configuration, p.prosecdef, p.proisstrict, p.proleakproof, p.proparallel, p.prokind,
+      p.proretset, p.pronargdefaults, p.procost, p.prorows, p.prosupport::oid AS support
+      FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace JOIN pg_language l ON l.oid = p.prolang`;
+// `definition` and `function_text` locate a WHEN condition in pg_get_triggerdef (whenClause).
+const triggerRows = `t.tgtype, t.tgenabled, t.tgisinternal, t.tgdeferrable, t.tginitdeferred,
+      t.tgnargs, t.tgqual IS NULL AS no_when, t.tgattr::text AS columns, p.proname AS function, n.nspname AS function_schema,
+      p.pronargs, t.tgconstraint <> 0 AS constraint, t.tgconstrrelid::oid AS constraint_relation,
+      t.tgparentid::oid AS parent, c.condeferrable, c.condeferred, c.convalidated,
+      COALESCE((to_jsonb(c)->>'conenforced')::boolean, true) AS enforced,
+      t.tgoldtable, t.tgnewtable,
+      CASE WHEN t.tgqual IS NOT NULL THEN pg_get_triggerdef(t.oid) END AS definition, quote_ident(n.nspname) || '.' || quote_ident(p.proname) AS function_text
+      FROM pg_trigger t JOIN pg_proc p ON p.oid = t.tgfoid JOIN pg_namespace n ON n.oid = p.pronamespace
+      LEFT JOIN pg_constraint c ON c.oid = t.tgconstraint`;
+const ordinaryTable = (schema, name, relation) => {
+  if (relation.relkind !== 'r' || relation.relpersistence !== 'p' || relation.relrowsecurity || relation.relforcerowsecurity) mismatch(`${schema}.${name}`, 'expected a persistent ordinary table without row security');
+};
+
+/** Re-reads one table, such as a table this run has just created. */
+const readTable = async (client, schema, name) => {
+  const { rows: relations } = await client.query(`SELECT ${relationColumns}
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 AND c.relname = $2`, [schema, name]);
+  if (!relations.length) return null;
+  const relation = relations[0];
+  ordinaryTable(schema, name, relation);
+  const { rows: columns } = await client.query(`SELECT ${columnRows}
+    WHERE a.attrelid = $1 AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`, [relation.oid]);
+  const { rows: constraints } = await client.query(`SELECT ${constraintRows}
+    WHERE c.conrelid = $1`, [relation.oid]);
+  const { rows: indexes } = await client.query(`SELECT ${indexRows} WHERE i.indrelid = $1`, [relation.oid]);
   return { columns, constraints, indexes };
 };
 
+/**
+ * Reads every managed relation, function and trigger in six statements, whatever the schema size. Names
+ * include both refresh-trigger layouts. Takes no table lock.
+ */
+const loadCatalog = async (client, schema, names) => {
+  const { rows: relations } = await client.query(`SELECT c.relname AS __name, ${relationColumns}
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 AND c.relname = ANY ($2::text[])`, [schema, names.tables]);
+  const oids = relations.map((relation) => relation.oid);
+  const { rows: columns } = await client.query(`SELECT a.attrelid AS __relation, ${columnRows}
+    WHERE a.attrelid = ANY ($1::oid[]) AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attrelid, a.attnum`, [oids]);
+  const { rows: constraints } = await client.query(`SELECT c.conrelid AS __relation, ${constraintRows}
+    WHERE c.conrelid = ANY ($1::oid[])`, [oids]);
+  const { rows: indexes } = await client.query(`SELECT i.indrelid AS __relation, ${indexRows} WHERE i.indrelid = ANY ($1::oid[])`, [oids]);
+  const { rows: functions } = await client.query(`SELECT p.proname AS __name, ${functionRows}
+      WHERE n.nspname = $1 AND p.proname = ANY ($2::text[])`, [schema, names.functions]);
+  const { rows: triggers } = await client.query(`SELECT t.tgrelid AS __relation, t.tgname AS __name, ${triggerRows}
+      WHERE t.tgrelid = ANY ($1::oid[]) AND t.tgname = ANY ($2::text[])`, [oids, names.triggers]);
+  const group = (rows, key) => {
+    const map = new Map();
+    for (const { __relation: relation, __name: name, ...row } of rows) {
+      const id = key(relation, name);
+      if (!map.has(id)) map.set(id, []);
+      map.get(id).push(row);
+    }
+    return map;
+  };
+  const relationNames = new Map(relations.map((relation) => [relation.oid, relation.__name]));
+  const byRelation = (rows) => group(rows, (relation) => relation);
+  const tableColumns = byRelation(columns); const tableConstraints = byRelation(constraints); const tableIndexes = byRelation(indexes);
+  const functionsByName = group(functions, (relation, name) => name);
+  const triggersByName = group(triggers, (relation, name) => JSON.stringify([relationNames.get(relation), name]));
+  return {
+    tables: new Map(relations.map(({ __name: name, ...relation }) => [name, {
+      relation, columns: tableColumns.get(relation.oid) || [], constraints: tableConstraints.get(relation.oid) || [], indexes: tableIndexes.get(relation.oid) || [],
+    }])),
+    functions: (name) => functionsByName.get(name) || [],
+    triggers: (table, name) => triggersByName.get(JSON.stringify([table, name])) || [],
+  };
+};
+// The stored table, as readTable returns it, or null when it does not exist.
+const fromCatalog = (schema, name, catalog) => {
+  const entry = catalog.tables.get(name);
+  if (!entry) return null;
+  ordinaryTable(schema, name, entry.relation);
+  return { columns: entry.columns, constraints: entry.constraints, indexes: entry.indexes };
+};
+
 const validateBase = (schema, table, actual, triggers = []) => {
   const name = `${schema}.${table.name}`;
   if (!actual) mismatch(name, 'table is missing');
@@ -144,16 +217,16 @@ const legacyListIndexes = (schema, table, actual) => table.columns
     && !index.unique && !index.primary && index.method === 'btree' && same(index.columns, [column]) && index.no_predicate && index.no_expression))
   .map(({ name }) => `${identifier(schema)}.${identifier(name)}`);
 
-const ensureFunctions = async (client, description, mode, created) => {
+// Each pass walks the description in the same order and rejects drift of an existing object at the same
+// point: 'validate' also rejects a missing object, 'plan' records it without DDL, and 'create' creates it
+// and records it.
+const ensureFunctions = async (client, description, catalog, pass, missing, created) => {
   for (const fn of description.functions || []) {
-    const { rows } = await client.query(`SELECT p.oid, pg_get_function_identity_arguments(p.oid) AS arguments,
-      pg_get_function_result(p.oid) AS returns, p.prosrc AS body, l.lanname AS language, p.provolatile AS volatility,
-      p.proconfig AS configuration, p.prosecdef, p.proisstrict, p.proleakproof, p.proparallel, p.prokind,
-      p.proretset, p.pronargdefaults, p.procost, p.prorows, p.prosupport::oid AS support
-      FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace JOIN pg_language l ON l.oid = p.prolang
-      WHERE n.nspname = $1 AND p.proname = $2`, [description.schema, fn.name]);
+    const rows = catalog.functions(fn.name);
     if (!rows.length) {
-      if (mode === 'validate') mismatch(`${description.schema}.${fn.name}`, 'function is missing');
+      if (pass === 'validate') mismatch(`${description.schema}.${fn.name}`, 'function is missing');
+      missing.push({ kind: 'function', name: fn.name });
+      if (pass === 'plan') continue;
       await client.query(createFunctionSQL(description.schema, fn));
       created.push(`function:${description.schema}.${fn.name}`);
       continue;
@@ -169,19 +242,25 @@ const ensureFunctions = async (client, description, mode, created) => {
   }
 };
 
-const ensureTriggers = async (client, description, mode, created) => {
+// pg_trigger.tgtype of an AFTER ... FOR EACH ROW trigger: the row bit plus one bit per event.
+const eventBits = { INSERT: 4, DELETE: 8, UPDATE: 16 };
+const triggerType = (trigger) => triggerEvents(trigger).reduce((type, event) => type + eventBits[event], 1);
+// pg_get_triggerdef renders `... FOR EACH ROW WHEN (<condition>) EXECUTE FUNCTION <function>()`.
+const whenClause = ({ definition, function_text: target }) => {
+  const head = ' FOR EACH ROW WHEN (';
+  const tail = `) EXECUTE FUNCTION ${target}()`;
+  if (!definition?.endsWith(tail)) return null;
+  const start = definition.lastIndexOf(head, definition.length - tail.length);
+  return start < 0 ? null : definition.slice(start + head.length, definition.length - tail.length);
+};
+
+const ensureTriggers = async (client, description, catalog, pass, missing, created) => {
   for (const trigger of description.triggers || []) {
-    const { rows } = await client.query(`SELECT t.tgtype, t.tgenabled, t.tgisinternal, t.tgdeferrable, t.tginitdeferred,
-      t.tgnargs, t.tgqual IS NULL AS no_when, t.tgattr::text AS columns, p.proname AS function, n.nspname AS function_schema,
-      p.pronargs, t.tgconstraint <> 0 AS constraint, t.tgconstrrelid::oid AS constraint_relation,
-      t.tgparentid::oid AS parent, c.condeferrable, c.condeferred, c.convalidated,
-      COALESCE((to_jsonb(c)->>'conenforced')::boolean, true) AS enforced,
-      t.tgoldtable, t.tgnewtable
-      FROM pg_trigger t JOIN pg_proc p ON p.oid = t.tgfoid JOIN pg_namespace n ON n.oid = p.pronamespace
-      LEFT JOIN pg_constraint c ON c.oid = t.tgconstraint
-      WHERE t.tgrelid = to_regclass($1) AND t.tgname = $2`, [qualified(description.schema, trigger.table), trigger.name]);
+    const rows = catalog.triggers(trigger.table, trigger.name);
     if (!rows.length) {
-      if (mode === 'validate') mismatch(`${description.schema}.${trigger.name}`, 'trigger is missing');
+      if (pass === 'validate') mismatch(`${description.schema}.${trigger.name}`, 'trigger is missing');
+      missing.push({ kind: 'trigger', table: trigger.table, name: trigger.name });
+      if (pass === 'plan') continue;
       const collision = await client.query('SELECT 1 FROM pg_constraint WHERE conrelid = to_regclass($1) AND conname = $2', [qualified(description.schema, trigger.table), trigger.name]);
       if (collision.rowCount) mismatch(`${description.schema}.${trigger.table}.${trigger.name}`, 'constraint name is already in use');
       await client.query(createTriggerSQL(description.schema, trigger));
@@ -189,8 +268,9 @@ const ensureTriggers = async (client, description, mode, created) => {
       continue;
     }
     const stored = rows[0];
-    if (stored.tgtype !== 29 || stored.tgenabled !== 'O' || stored.tgisinternal || stored.tgdeferrable !== trigger.deferrable
-      || stored.tginitdeferred !== trigger.initiallyDeferred || stored.tgnargs || !stored.no_when || stored.columns !== ''
+    if (stored.tgtype !== triggerType(trigger) || stored.tgenabled !== 'O' || stored.tgisinternal || stored.tgdeferrable !== trigger.deferrable
+      || stored.tginitdeferred !== trigger.initiallyDeferred || stored.tgnargs || stored.no_when !== !trigger.when
+      || (trigger.when && normalizeExpression(whenClause(stored)) !== normalizeExpression(trigger.when)) || stored.columns !== ''
       || stored.function !== trigger.function || stored.function_schema !== description.schema || stored.pronargs
       || stored.constraint !== trigger.constraint || stored.constraint_relation || stored.parent || stored.tgoldtable || stored.tgnewtable
       || (trigger.constraint && (!stored.condeferrable || !stored.condeferred || !stored.convalidated || !stored.enforced))) {
@@ -199,35 +279,168 @@ const ensureTriggers = async (client, description, mode, created) => {
   }
 };
 
-const backfill = async (client, description) => {
-  for (const table of description.tables) {
-    for (const check of table.checks) {
-      const invalid = await client.query(`SELECT 1 FROM ${qualified(description.schema, table.name)} WHERE NOT (${check.expression}) LIMIT 1`);
-      if (invalid.rowCount) mismatch(`${description.schema}.${table.name}.${check.name}`, 'existing data violates generated check');
+/** One pass over the description: schema, functions, tables, foreign keys and indexes, then triggers. */
+const traverse = async (client, description, catalog, pass, missing, created) => {
+  const { schema, tables } = description;
+  const legacy = [];
+  const namespace = await client.query('SELECT 1 FROM pg_namespace WHERE nspname = $1', [schema]);
+  if (!namespace.rowCount) {
+    if (pass === 'validate') mismatch(schema, 'schema is missing');
+    missing.push({ kind: 'schema' });
+    if (pass === 'plan') return legacy;
+    await client.query(`CREATE SCHEMA ${identifier(schema)}`);
+    created.push(`schema:${schema}`);
+  }
+  await ensureFunctions(client, description, catalog, pass, missing, created);
+  const actuals = new Map();
+  for (const table of tables) {
+    let actual = fromCatalog(schema, table.name, catalog);
+    if (!actual) {
+      if (pass === 'validate') mismatch(`${schema}.${table.name}`, 'table is missing');
+      missing.push({ kind: 'table', table: table.name });
+      // A table that does not exist has none of its foreign keys, indexes or triggers either.
+      if (pass === 'plan') continue;
+      await client.query(createTableSQL(schema, table));
+      created.push(`table:${schema}.${table.name}`);
+      actual = await readTable(client, schema, table.name);
     }
+    validateBase(schema, table, actual, description.triggers);
+    actuals.set(table.name, actual);
   }
-  // Existing keys can be stale when missing maintenance triggers are recreated.
-  // All managed tables are already locked; rebuild the complete derived key set
-  // before testing owners against one another. Rollback restores the old set.
-  for (const table of description.tables.filter((item) => item.uniqueKeys)) {
-    await client.query(`DELETE FROM ${qualified(description.schema, table.name)}`);
+  for (const table of tables.filter((item) => actuals.has(item.name))) {
+    const actual = actuals.get(table.name);
+    for (const key of table.foreignKeys) {
+      const stored = actual.constraints.find((item) => item.name === key.name);
+      if (stored) validateForeignKey(schema, table, key, stored);
+      else {
+        if (pass === 'validate') mismatch(`${schema}.${table.name}.${key.name}`, 'foreign key is missing');
+        missing.push({ kind: 'foreignKey', table: table.name, name: key.name });
+        if (pass === 'plan') continue;
+        await client.query(createForeignKeySQL(schema, table, key));
+        created.push(`foreignKey:${schema}.${table.name}.${key.name}`);
+      }
+    }
+    for (const index of table.indexes) {
+      const stored = actual.indexes.find((item) => item.name === index.name);
+      if (stored) validateIndex(schema, table, index, stored);
+      else {
+        if (pass === 'validate') mismatch(`${schema}.${table.name}.${index.name}`, 'index is missing');
+        missing.push({ kind: 'index', table: table.name, name: index.name });
+        if (pass === 'plan') continue;
+        const collision = await client.query('SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 AND c.relname = $2', [schema, index.name]);
+        if (collision.rowCount) mismatch(`${schema}.${index.name}`, 'relation name is already in use');
+        await client.query(createIndexSQL(schema, table, index));
+        created.push(`index:${schema}.${index.name}`);
+      }
+    }
+    for (const index of actual.indexes) {
+      if (index.unique && !index.primary && !table.indexes.some((item) => item.name === index.name)) mismatch(`${schema}.${table.name}.${index.name}`, 'unexpected unique index');
+    }
+    legacy.push(...legacyListIndexes(schema, table, actual));
   }
+  await ensureTriggers(client, description, catalog, pass, missing, created);
+  return legacy;
+};
+
+// Names to read from the catalog: the description's, plus the refresh-trigger objects of both layouts.
+const catalogNames = (description, layouts) => {
+  const functions = new Set((description.functions || []).map((fn) => fn.name));
+  const triggers = new Set((description.triggers || []).map((trigger) => trigger.name));
+  for (const layout of layouts.values()) {
+    for (const objects of [layout.perRow, layout.perRoot]) {
+      for (const fn of objects.functions) functions.add(fn.name);
+      for (const trigger of objects.triggers) triggers.add(trigger.name);
+    }
+  }
+  return { tables: description.tables.map((table) => table.name), functions: [...functions], triggers: [...triggers] };
+};
+
+// Each maintained root keeps the refresh-trigger layout its database already has: a function or trigger
+// that only one layout has, or a touch function with one layout's body. A root with neither, such as a
+// new one, gets the description's layout. Objects of both layouts in one root are drift.
+const resolveLayouts = (description, catalog, layouts) => {
+  const holds = (own, other) => own.functions.some((fn) => {
+    const twin = other.functions.find((item) => item.name === fn.name);
+    const stored = catalog.functions(fn.name);
+    return twin ? twin.body !== fn.body && stored.some((row) => row.body === fn.body) : stored.length > 0;
+  }) || own.triggers.some((trigger) => !other.triggers.some((item) => item.name === trigger.name && item.table === trigger.table)
+    && catalog.triggers(trigger.table, trigger.name).length > 0);
+  const choices = new Map();
   for (const item of description.maintenance || []) {
+    const { perRow, perRoot } = layouts.get(item.rootTable);
+    const row = holds(perRow, perRoot);
+    const root = holds(perRoot, perRow);
+    if (row && root) mismatch(`${description.schema}.${item.rootTable}`, 'refresh triggers of two layouts are present');
+    const described = layoutOf(description, item);
+    const layout = row ? 'perRow' : root ? 'perRoot' : described;
+    if (layout !== described) choices.set(item.rootTable, layout);
+  }
+  return choices.size ? withLayouts(description, choices, layouts) : description;
+};
+
+// The maintained root a table belongs to: itself, the root of its ownership chain, or the root an
+// auxiliary (guard or keys) table serves.
+const rootOf = (description, name) => {
+  let table = description.tables.find((item) => item.name === name);
+  if (table?.auxiliary) return table.auxiliary.rootTable;
+  while (table?.ownership) table = description.tables.find((item) => item.name === table.ownership.ownerTable);
+  return table?.name;
+};
+// Keys can be stale only for roots whose maintenance objects are missing: guard and keys tables, the
+// validate and refresh functions, and the refresh triggers and their functions. A missing foreign key or
+// index validates existing rows itself when it is created, and checks only arrive with new tables.
+const staleRoots = (description, objects) => {
+  const maintenance = description.maintenance || [];
+  const maintained = new Set(maintenance.map((item) => item.rootTable));
+  const roots = new Set();
+  for (const object of objects) {
+    let root;
+    if (object.kind === 'table' || object.kind === 'trigger') root = rootOf(description, object.table);
+    else if (object.kind === 'function') {
+      const item = maintenance.find((entry) => entry.validateFunction === object.name || entry.refreshFunction === object.name);
+      const trigger = (description.triggers || []).find((entry) => entry.function === object.name);
+      root = item ? item.rootTable : trigger && rootOf(description, trigger.table);
+    }
+    if (maintained.has(root)) roots.add(root);
+  }
+  return roots;
+};
+// Rebuilding keys needs the rows of their root to stay still until commit: lock the existing tables of
+// those roots (root, owned, guard and keys tables) in one statement. Other DDL takes its own locks.
+const lockRoots = async (client, description, catalog, roots) => {
+  const names = description.tables.filter((table) => catalog.tables.has(table.name) && roots.has(rootOf(description, table.name)));
+  if (names.length) await client.query(`LOCK TABLE ${names.map((table) => qualified(description.schema, table.name)).join(', ')} IN SHARE ROW EXCLUSIVE MODE`);
+};
+
+const backfill = async (client, description, roots) => {
+  // The keys of these roots can be stale because maintenance objects were recreated. Their tables are
+  // locked; rebuild their complete derived key set before testing owners against one another. Rollback
+  // restores the old set.
+  for (const table of description.tables.filter((item) => item.uniqueKeys && roots.has(item.uniqueKeys.rootTable))) {
+    await client.query(`DELETE FROM ${qualified(description.schema, table.name)}`);
+  }
+  for (const item of (description.maintenance || []).filter((entry) => roots.has(entry.rootTable))) {
     await client.query(`INSERT INTO ${qualified(description.schema, item.guardTable)} (__owner_id)
       SELECT id FROM ${qualified(description.schema, item.rootTable)} ON CONFLICT (__owner_id) DO NOTHING`);
     await client.query(`SELECT ${qualified(description.schema, item.refreshFunction)}(id) FROM ${qualified(description.schema, item.rootTable)} ORDER BY id`);
   }
 };
 
-/** Create missing objects or validate an existing schema; never alter/drop existing storage. */
+/**
+ * Create missing objects or validate an existing schema; never alter/drop existing storage. The catalog is
+ * read in a fixed number of statements without table locks. Create mode changes nothing, and locks nothing,
+ * when nothing is missing; otherwise it locks only the tables of roots whose keys it must rebuild.
+ */
 export const initializeDatabase = async (pool, description, { mode = 'create' } = {}) => {
   if (!['create', 'validate'].includes(mode)) throw new SimfinityError(`Unknown initialization mode: ${mode}`, 'INVALID_INITIALIZATION_MODE', 400);
-  const { schema, tables } = description;
+  const { schema } = description;
   identifier(schema);
   if (schema.startsWith('pg_') || schema === 'information_schema') throw new SimfinityError('System schemas cannot be managed', 'INVALID_DATABASE_SCHEMA', 400);
+  const layouts = maintenanceLayouts(description);
+  const names = catalogNames(description, layouts);
   const client = await pool.connect();
   const created = [];
-  const legacy = [];
+  let legacy = [];
   let rollbackError;
   try {
     await client.query(mode === 'validate' ? 'BEGIN READ ONLY' : 'BEGIN');
@@ -235,56 +448,36 @@ export const initializeDatabase = async (pool, description, { mode = 'create' }
     await client.query('SET LOCAL standard_conforming_strings = \'on\'');
     const version = await client.query('SELECT current_setting(\'server_version_num\')::integer AS version');
     if (version.rows[0].version < 150000) throw new SimfinityError('PostgreSQL 15 or later is required', 'UNSUPPORTED_DATABASE_VERSION', 400);
+    // Serializes initializers of this schema before anything is read.
     await client.query('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [`simfinity:${schema}`]);
-    const namespace = await client.query('SELECT 1 FROM pg_namespace WHERE nspname = $1', [schema]);
-    if (!namespace.rowCount) {
-      if (mode === 'validate') mismatch(schema, 'schema is missing');
-      await client.query(`CREATE SCHEMA ${identifier(schema)}`);
-      created.push(`schema:${schema}`);
-    }
-    await ensureFunctions(client, description, mode, created);
-    const catalog = new Map();
-    for (const table of tables) {
-      let actual = await readTable(client, schema, table.name);
-      if (!actual) {
-        if (mode === 'validate') mismatch(`${schema}.${table.name}`, 'table is missing');
-        await client.query(createTableSQL(schema, table));
-        created.push(`table:${schema}.${table.name}`);
-        actual = await readTable(client, schema, table.name);
-      }
-      if (mode === 'create') await client.query(`LOCK TABLE ${qualified(schema, table.name)} IN SHARE ROW EXCLUSIVE MODE`);
-      validateBase(schema, table, actual, description.triggers);
-      catalog.set(table.name, actual);
-    }
-    for (const table of tables) {
-      const actual = catalog.get(table.name);
-      for (const key of table.foreignKeys) {
-        const stored = actual.constraints.find((item) => item.name === key.name);
-        if (stored) validateForeignKey(schema, table, key, stored);
-        else {
-          if (mode === 'validate') mismatch(`${schema}.${table.name}.${key.name}`, 'foreign key is missing');
-          await client.query(createForeignKeySQL(schema, table, key));
-          created.push(`foreignKey:${schema}.${table.name}.${key.name}`);
-        }
-      }
-      for (const index of table.indexes) {
-        const stored = actual.indexes.find((item) => item.name === index.name);
-        if (stored) validateIndex(schema, table, index, stored);
-        else {
-          if (mode === 'validate') mismatch(`${schema}.${table.name}.${index.name}`, 'index is missing');
-          const collision = await client.query('SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 AND c.relname = $2', [schema, index.name]);
-          if (collision.rowCount) mismatch(`${schema}.${index.name}`, 'relation name is already in use');
-          await client.query(createIndexSQL(schema, table, index));
-          created.push(`index:${schema}.${index.name}`);
-        }
+    const inspected = await loadCatalog(client, schema, names);
+    if (mode === 'validate') legacy = await traverse(client, resolveLayouts(description, inspected, layouts), inspected, 'validate', [], created);
+    else {
+      // Inspect first, without table locks or DDL. Drift before the first missing object is reported as
+      // before; drift after one is left to the create pass, which reports what earlier versions did, such
+      // as a foreign key that existing rows violate.
+      const missing = [];
+      let planned;
+      try {
+        planned = resolveLayouts(description, inspected, layouts);
+        legacy = await traverse(client, planned, inspected, 'plan', missing, []);
+      } catch (error) {
+        if (!(error instanceof SimfinityError) || !missing.length) throw error;
       }
-      for (const index of actual.indexes) {
-        if (index.unique && !index.primary && !table.indexes.some((item) => item.name === index.name)) mismatch(`${schema}.${table.name}.${index.name}`, 'unexpected unique index');
+      if (missing.length) {
+        const roots = staleRoots(planned, missing);
+        await lockRoots(client, planned, inspected, roots);
+        const catalog = await loadCatalog(client, schema, names);
+        const effective = resolveLayouts(description, catalog, layouts);
+        const objects = [];
+        legacy = await traverse(client, effective, catalog, 'create', objects, created);
+        // A missing schema stops the plan early; its new tables need no lock. Lock any other root the
+        // plan did not reach, such as one whose objects an operator dropped meanwhile, before rebuilding.
+        const late = new Set([...staleRoots(effective, objects)].filter((root) => !roots.has(root)));
+        await lockRoots(client, effective, catalog, late);
+        if (roots.size || late.size) await backfill(client, effective, new Set([...roots, ...late]));
       }
-      legacy.push(...legacyListIndexes(schema, table, actual));
     }
-    await ensureTriggers(client, description, mode, created);
-    if (mode === 'create' && created.length) await backfill(client, description);
     await client.query('COMMIT');
     if (legacy.length) {
       console.warn(`Simfinity: PostgreSQL schema ${identifier(schema)} has btree indexes that earlier versions generated on [ID] list columns: ${legacy.join(', ')}. `

package/types/index.d.ts

@@ -94,6 +94,10 @@ export interface DatabaseTrigger {
   constraint: boolean;
   deferrable: boolean;
   initiallyDeferred: boolean;
+  /** Row events the trigger fires on; omitted means INSERT, UPDATE and DELETE. Only the `refreshTriggers: 'perRoot'` guard trigger sets it. */
+  events?: Array<'INSERT' | 'UPDATE' | 'DELETE'>;
+  /** A WHEN condition on the row; only the `refreshTriggers: 'perRoot'` guard trigger sets it. */
+  when?: string;
 }
 export interface DatabaseMaintenance {
   rootTable: string;
@@ -124,7 +128,7 @@ export interface DatabasePool {
  * Low-level describer for any registrations. `options.schema` defaults to `public`, not to the schema
  * of a configured runtime; pass the schema given to configure() or createPostgres().
  */
-export function describeDatabase(registrations: ModelRegistration[], options?: { schema?: string }): DatabaseDescription;
+export function describeDatabase(registrations: ModelRegistration[], options?: { schema?: string } & Pick<PostgresConfiguration, 'refreshTriggers' | 'ownerIndexes'>): DatabaseDescription;
 /** Describes the default module instance in its configured schema, after configure/connect/createSchema. */
 export function describeDatabase(): DatabaseDescription;
 /** Accepts a trusted description produced by describeDatabase. */
@@ -164,7 +168,31 @@ export interface PostgresModel {
   update(id: string, changes: Record<string, any>, options?: { session?: PostgresSession }): Promise<PostgresRecord | null>;
   delete(id: string, options?: { session?: PostgresSession }): Promise<PostgresRecord | null>;
 }
-export interface PostgresConfiguration { pool: PostgresPool; schema?: string }
+export interface PostgresConfiguration {
+  pool: PostgresPool;
+  schema?: string;
+  /** Defaults to true: the owned rows of an embedded list are inserted with multi-row INSERT statements. `false` keeps one INSERT per row. */
+  multiRowInserts?: boolean;
+  /**
+   * Defaults to false: sorts on `id` and required root fields omit the NULLS clause, so the primary key and declared
+   * indexes can return them in order. `true` keeps the explicit NULLS clause on every sort term, as 3.5.9 did.
+   */
+  explicitNullsOrder?: boolean;
+  /**
+   * Defaults to 'perRow', as 3.5.9: the deferred triggers of a root with owned tables or unique lists refresh its owned
+   * shape and unique keys once per changed row. 'perRoot' refreshes each changed root once per transaction while its
+   * guard trigger stays deferred, the default (under SET CONSTRAINTS ALL IMMEDIATE, once per changed row). It applies
+   * to roots created while it is set: initialization keeps each existing root on the layout its database has, and
+   * accepts both. An unknown value throws INVALID_DATABASE_SCHEMA (400) from createSchema or describeDatabase.
+   */
+  refreshTriggers?: 'perRow' | 'perRoot';
+  /**
+   * Defaults to 'all', as 3.5.9. 'minimal' does not create the (__owner_id) index of owned and guard tables, which their
+   * primary key or a unique index covers; keys tables keep theirs. Existing indexes are kept and accepted. An unknown
+   * value throws INVALID_DATABASE_SCHEMA (400) from createSchema or describeDatabase.
+   */
+  ownerIndexes?: 'all' | 'minimal';
+}
 export interface InitializationOptions { mode?: 'create' | 'validate' }
 export interface InitializationResult { mode: 'create' | 'validate'; created: string[] }
 export interface PostgresRuntime extends Runtime<PostgresModel, PostgresSession> {