@simtlix/simfinity-postgres 3.2.0

package/src/schema/constraints.js

@@ -0,0 +1,142 @@
+import { identifier as q, qualified, literal, generatedName, invalid } from './sql.js';
+
+// JavaScript uses astronomical ISO years (including zero and signed extended
+// years). Validate their Gregorian components without PostgreSQL's AD/BC parser
+// or timestamp range. Mapping years modulo 400 preserves leap-year rules.
+const dateTimeValidation = `DECLARE parts integer[]; BEGIN
+  IF jsonb_typeof($1) <> 'string' THEN RETURN false; END IF;
+  parts := regexp_match($1 #>> '{}', '^([0-9]{4}|[+-][0-9]{6})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})[.]([0-9]{3})Z$')::integer[];
+  IF parts IS NULL OR ($1 #>> '{}') LIKE '-000000-%' THEN RETURN false; END IF;
+  PERFORM make_date(2000 + ((parts[1] % 400 + 400) % 400), parts[2], parts[3]);
+  RETURN parts[4] BETWEEN 0 AND 23 AND parts[5] BETWEEN 0 AND 59 AND parts[6] BETWEEN 0 AND 59
+    AND parts >= ARRAY[-271821, 4, 20, 0, 0, 0, 0] AND parts <= ARRAY[275760, 9, 13, 0, 0, 0, 0];
+END;`;
+
+/** 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);
+    return qualified(schema, name);
+  };
+  const jsonValidator = (table, field, path = []) => {
+    const name = generatedName(table.name, ...path, field.name, 'json_valid');
+    let test;
+    if (field.list) {
+      const item = jsonValidator(table, { ...field, name: field.name, list: false, required: field.itemRequired }, [...path, field.name, 'item']);
+      test = `IF jsonb_typeof($1) <> 'array' THEN RETURN false; END IF;
+  RETURN NOT EXISTS (SELECT 1 FROM jsonb_array_elements($1) AS e(value) WHERE NOT ${item}(e.value));`;
+    } else if (field.kind === 'embedded') {
+      const checks = field.fields.map((child) => `${jsonValidator(table, child, [...path, field.name])}($1 -> ${literal(child.storageName)})`);
+      test = `IF jsonb_typeof($1) <> 'object' THEN RETURN false; END IF; RETURN ${checks.join(' AND ') || 'true'};`;
+    } else {
+      const value = '($1 #>> \'{}\')';
+      const conditions = {
+        String: 'jsonb_typeof($1) = \'string\'', Boolean: 'jsonb_typeof($1) = \'boolean\'',
+        Enum: `jsonb_typeof($1) = 'string' AND ${value} = ANY (ARRAY[${(field.values || []).map(literal).join(', ')}]::text[])`,
+        ID: `jsonb_typeof($1) = 'string' AND ${value} ~ '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'`,
+        Int: `jsonb_typeof($1) = 'number' AND ${value}::numeric = trunc(${value}::numeric) AND ${value}::numeric BETWEEN -2147483648 AND 2147483647`,
+        Float: `jsonb_typeof($1) = 'number' AND ${value}::double precision BETWEEN '-1.7976931348623157e308'::double precision AND '1.7976931348623157e308'::double precision`,
+      };
+      test = field.scalar === 'DateTime' ? dateTimeValidation : `RETURN ${conditions[field.scalar]};`;
+    }
+    return fn(name, ['jsonb'], 'boolean', `BEGIN
+  IF $1 IS NULL OR $1 = 'null'::jsonb THEN RETURN ${!field.required}; END IF;
+  ${test}
+EXCEPTION WHEN data_exception THEN RETURN false;
+END`, true);
+  };
+  const addJSON = (table, field) => addCheck(table, field.storageName, 'shape', `${table.ownership?.nullableItems ? `(NOT ${q('__item_present')}) OR ` : ''}${jsonValidator(table, field)}(${q(field.storageName)})`);
+  const addUnique = (table, field, type) => { uniquePaths.push({ table, field, type }); };
+  const chain = (table) => {
+    const result = [table];
+    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 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)));
+    const maintenance = [];
+    for (const root of roots) {
+      const ownedTables = sources.filter((table) => table.ownership && chain(table)[0] === root);
+      const guard = addTable(generatedName(root.name, 'guard'));
+      guard.auxiliary = { rootTable: root.name, kind: 'guard' };
+      guard.columns = [{ name: '__owner_id', type: 'uuid', nullable: false }, { name: 'version', type: 'bigint', nullable: false, default: '0' }];
+      guard.primaryKey.columns = ['__owner_id'];
+      addReference(guard, '__owner_id', root.name, 'id', true);
+      let checks = '';
+      for (const table of ownedTables) {
+        const parentPath = chain(table).slice(0, -1); const parent = parentPath.at(-1); const alias = `t${parentPath.length - 1}`;
+        const children = `SELECT * FROM ${qualified(schema, table.name)} c WHERE c.__owner_id = ${alias}.${q(parent.primaryKey.columns[0])}`;
+        const invalidCount = table.ownership.list ? 'counts.n > 0 AND (counts.lo <> 0 OR counts.hi <> counts.n - 1)' : 'counts.n <> 1';
+        checks += `
+  IF EXISTS (SELECT 1 FROM ${joins(parentPath)} CROSS JOIN LATERAL (SELECT count(*) n, ${table.ownership.list ? 'min(c.__position) lo, max(c.__position) hi' : '0 lo, 0 hi'} FROM (${children}) c) counts
+    WHERE t0.id = $1 AND ((${alias}.${q(table.ownership.stateColumn)} <> 'present' AND counts.n <> 0) OR (${alias}.${q(table.ownership.stateColumn)} = 'present' AND (${invalidCount})))) THEN
+    RAISE EXCEPTION 'Invalid owned shape: %', ${literal(table.name)} USING ERRCODE = '23514'; END IF;`;
+        if (table.ownership.nullableItems) {
+          const nested = ownedTables.filter((item) => item.ownership.ownerTable === table.name);
+          const payload = table.columns.filter((column) => !column.name.startsWith('__')).map((column) => `c.${q(column.name)} IS NOT NULL`);
+          for (const column of table.columns.filter((item) => item.presenceColumn)) payload.push(`c.${q(column.presenceColumn)}`);
+          for (const child of nested) payload.push(`c.${q(child.ownership.stateColumn)} <> 'missing'`, `EXISTS (SELECT 1 FROM ${qualified(schema, child.name)} x WHERE x.__owner_id = c.__id)`);
+          if (payload.length) checks += `
+  IF EXISTS (SELECT 1 FROM ${joins(chain(table))} JOIN ${qualified(schema, table.name)} c ON c.__id = t${parentPath.length}.__id WHERE t0.id = $1 AND NOT c.__item_present AND (${payload.join(' OR ')})) THEN
+    RAISE EXCEPTION 'Null owned item has payload: %', ${literal(table.name)} USING ERRCODE = '23514'; END IF;`;
+        }
+      }
+      const validateName = generatedName(root.name, 'owned_valid');
+      const validate = fn(validateName, ['uuid'], 'void', `BEGIN${checks}\nEND`);
+      let rebuild = '';
+      for (const key of uniquePaths.filter((item) => chain(item.table)[0] === root)) {
+        const path = chain(key.table); const alias = `t${path.length - 1}`;
+        const column = `${alias}.${q(key.field.storageName)}`;
+        const source = key.table.ownership?.nullableItems ? `CASE WHEN ${alias}.__item_present THEN ${column} END` : column;
+        const value = key.field.list ? 'v.value' : source;
+        const kind = `CASE ${key.field.list ? `WHEN cardinality(${source}) = 0 THEN 'empty' ` : ''}WHEN ${value} IS NULL THEN 'null' ELSE 'value' END`;
+        const query = `SELECT DISTINCT t0.id AS __owner_id, ${kind}::text COLLATE pg_catalog."C" AS kind, ${value} AS value FROM ${joins(path, true)}${key.field.list ? ` LEFT JOIN LATERAL unnest(${source}) v(value) ON true` : ''} WHERE t0.id = $1`;
+        const storage = addTable(generatedName(key.table.name, key.field.name, 'keys'));
+        storage.uniqueKeys = { rootTable: root.name, sourceTable: key.table.name, field: key.field.storageName };
+        storage.auxiliary = { rootTable: root.name, kind: 'uniqueKeys' };
+        addColumn(storage, { name: '__owner_id', type: 'uuid', nullable: false });
+        addColumn(storage, { name: 'kind', type: 'text', nullable: false });
+        addColumn(storage, { name: 'value', type: key.type.replace(/\[\]$/, ''), nullable: true });
+        addReference(storage, '__owner_id', root.name, 'id', true);
+        addIndex(storage, ['kind', 'value'], true);
+        addCheck(storage, 'kind', 'key', '((kind = \'value\'::text) AND (value IS NOT NULL)) OR ((kind = ANY (ARRAY[\'null\'::text, \'empty\'::text])) AND (value IS NULL))');
+        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 });
+      // 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.
+      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 });
+        }
+      }
+    }
+    return { functions, triggers, maintenance };
+  };
+  return { addJSON, addUnique, finish };
+};

package/src/schema/ddl.js

@@ -0,0 +1,29 @@
+import { identifier, qualified, columnsSQL, literal } 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}` : ''}`);
+  columns.push(`CONSTRAINT ${identifier(table.primaryKey.name)} PRIMARY KEY (${columnsSQL(table.primaryKey.columns)})`);
+  for (const check of table.checks) columns.push(`CONSTRAINT ${identifier(check.name)} CHECK (${check.expression})`);
+  return `CREATE TABLE ${qualified(schema, table.name)} (\n  ${columns.join(',\n  ')}\n)`;
+};
+export const createForeignKeySQL = (schema, table, key) => `ALTER TABLE ${qualified(schema, table.name)} ADD CONSTRAINT ${identifier(key.name)} FOREIGN KEY (${columnsSQL(key.columns)}) REFERENCES ${qualified(schema, key.targetTable)} (${columnsSQL(key.targetColumns)}) ON UPDATE ${key.onUpdate} ON DELETE ${key.onDelete} ${key.deferrable ? `DEFERRABLE INITIALLY ${key.initiallyDeferred ? 'DEFERRED' : 'IMMEDIATE'}` : 'NOT DEFERRABLE'}`;
+export const createIndexSQL = (schema, table, index) => `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX ${identifier(index.name)} ON ${qualified(schema, table.name)} (${columnsSQL(index.columns)})${index.nullsNotDistinct ? ' NULLS NOT DISTINCT' : ''}`;
+
+export const createFunctionSQL = (schema, fn) => {
+  const settings = fn.configuration.map((setting) => {
+    const position = setting.indexOf('=');
+    return `SET ${identifier(setting.slice(0, position))} TO ${literal(setting.slice(position + 1))}`;
+  }).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)}()`;
+
+/** Tables/primary keys precede all FKs so forward and cyclic references work. */
+export const compileDatabaseSchema = (description) => [
+  `CREATE SCHEMA IF NOT EXISTS ${identifier(description.schema)}`,
+  ...(description.functions || []).map((fn) => createFunctionSQL(description.schema, fn)),
+  ...description.tables.map((table) => createTableSQL(description.schema, table)),
+  ...description.tables.flatMap((table) => table.foreignKeys.map((key) => createForeignKeySQL(description.schema, table, key))),
+  ...description.tables.flatMap((table) => table.indexes.map((index) => createIndexSQL(description.schema, table, index))),
+  ...(description.triggers || []).map((trigger) => createTriggerSQL(description.schema, trigger)),
+];

package/src/schema/describe.js

@@ -0,0 +1,138 @@
+import { describeModels } from '@simtlix/simfinity-core';
+import { queryFunctions } from '../query/functions.js';
+import { constraintBuilder } 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' };
+const hasOwnedFields = (fields) => fields.some((field) => field.kind === 'reference' || field.unique || (field.fields && hasOwnedFields(field.fields)));
+
+/** Compile GraphQL storage metadata into a serializable PostgreSQL description. */
+export const describeDatabase = (registrations, { schema = 'public' } = {}) => {
+  identifier(schema);
+  const { entities } = describeModels(registrations);
+  const tables = [];
+  const names = new Set();
+  const addTable = (name, ownership) => {
+    identifier(name);
+    if (names.has(name)) invalid(`Table name collision: ${name}`);
+    names.add(name);
+    const key = ownership ? '__id' : 'id';
+    const table = {
+      name, columns: [{ name: key, type: 'uuid', nullable: false, default: 'gen_random_uuid()' }],
+      primaryKey: { name: generatedName(name, 'pk'), columns: [key] },
+      foreignKeys: [], indexes: [], checks: [],
+      ...(ownership ? { ownership } : {}),
+    };
+    tables.push(table);
+    return table;
+  };
+  const addColumn = (table, column) => {
+    identifier(column.name);
+    if (table.columns.some((item) => item.name === column.name)) invalid(`Column collision: ${table.name}.${column.name}`);
+    if (column.type === 'text' || column.type === 'text[]') column.collation = 'C';
+    table.columns.push(column);
+  };
+  const addIndex = (table, columns, unique = false) => {
+    if (table.indexes.some((index) => JSON.stringify(index.columns) === JSON.stringify(columns) && index.unique === unique)) return;
+    table.indexes.push({ name: generatedName(table.name, ...columns, unique ? 'uq' : 'idx'), columns, unique, nullsNotDistinct: unique });
+  };
+  const addCheck = (table, field, suffix, expression) => {
+    table.checks.push({ name: generatedName(table.name, field, suffix), expression });
+  };
+  const addReference = (table, column, targetTable, targetColumn = 'id', owned = false) => {
+    table.foreignKeys.push({
+      name: generatedName(table.name, column, 'fk'), columns: [column], targetTable, targetColumns: [targetColumn],
+      onDelete: owned ? 'CASCADE' : 'NO ACTION', onUpdate: 'NO ACTION', deferrable: true, initiallyDeferred: false,
+    });
+    addIndex(table, [column]);
+  };
+  const constraints = constraintBuilder(schema, tables, { addTable, addColumn, addReference, addIndex, addCheck });
+  const fieldsInto = (table, fields, path = []) => {
+    for (const field of fields) {
+      if (field.kind === 'collection') continue;
+      if (field.kind === 'embedded' && field.unique) invalid(`Whole embedded-object uniqueness is not supported: ${table.name}.${field.name}`);
+      if (!table.ownership && ['id', '_id'].includes(field.name)) {
+        if (field.kind !== 'scalar' || field.list || !['ID', 'String'].includes(field.scalar)) invalid(`Reserved identity field ${table.name}.${field.name} must be a scalar ID or String`);
+        continue;
+      }
+      if (field.storageName.startsWith('__')) invalid(`Reserved private column name ${table.name}.${field.storageName}`);
+      const conditional = table.ownership?.nullableItems === true;
+      const required = field.required && !conditional;
+      if (field.kind === 'embedded' && hasOwnedFields(field.fields)) {
+        // State preserves absent/null/empty values when the runtime reassembles nested objects.
+        const stateColumn = `__${field.name}_state`;
+        addColumn(table, { name: stateColumn, type: 'text', nullable: false, default: '\'missing\'::text' });
+        const values = field.required && !conditional ? ['present'] : ['missing', 'null', 'present'];
+        if (conditional && field.required) addCheck(table, stateColumn, 'required', `(NOT ${identifier('__item_present')}) OR (${identifier(stateColumn)} = 'present'::text)`);
+        addCheck(table, stateColumn, 'state', `${identifier(stateColumn)} = ANY (ARRAY[${values.map((v) => `${literal(v)}::text`).join(', ')}])`);
+        const owned = addTable(generatedName(table.name, field.name), {
+          ownerTable: table.name, ownerColumn: table.primaryKey.columns[0], field: field.name,
+          path: [...path, field.name], list: field.list, required: field.required,
+          nullableItems: field.list && !field.itemRequired, stateColumn,
+        });
+        addColumn(owned, { name: '__owner_id', type: 'uuid', nullable: false });
+        addReference(owned, '__owner_id', table.name, table.primaryKey.columns[0], true);
+        if (field.list) {
+          addColumn(owned, { name: '__position', type: 'integer', nullable: false });
+          addCheck(owned, '__position', 'nonnegative', `${identifier('__position')} >= 0`);
+          addIndex(owned, ['__owner_id', '__position'], true);
+          if (!field.itemRequired) addColumn(owned, { name: '__item_present', type: 'boolean', nullable: false, default: 'true' });
+        } else addIndex(owned, ['__owner_id'], true);
+        fieldsInto(owned, field.fields, [...path, field.name]);
+        continue;
+      }
+      const type = field.kind === 'embedded' ? 'jsonb' : field.kind === 'reference' ? 'uuid' : `${scalarTypes[field.scalar]}${field.list ? '[]' : ''}`;
+      if (!type || type.startsWith('undefined')) invalid(`Unsupported scalar at ${table.name}.${field.name}`);
+      const presenceColumn = table.ownership || field.kind === 'embedded' ? generatedName('__field', field.name, 'present') : null;
+      addColumn(table, { name: field.storageName, type, nullable: !required, ...(presenceColumn ? { presenceColumn } : {}) });
+      if (presenceColumn) addColumn(table, { name: presenceColumn, type: 'boolean', nullable: false, default: 'false' });
+      if (conditional && field.required) addCheck(table, field.storageName, 'required', `(NOT ${identifier('__item_present')}) OR (${identifier(field.storageName)} IS NOT NULL)`);
+      if (field.kind === 'reference') addReference(table, field.storageName, field.target);
+      if (field.scalar === 'ID') addIndex(table, [field.storageName]);
+      if (field.kind === 'embedded') constraints.addJSON(table, field);
+      if (field.unique) {
+        if (field.list || table.ownership) constraints.addUnique(table, field, type);
+        else addIndex(table, [field.storageName], true);
+      }
+      if (field.scalar === 'Enum') {
+        const values = `ARRAY[${field.values.map((value) => `${literal(value)}::text`).join(', ')}]`;
+        const expression = field.list
+          ? `array_remove(${identifier(field.storageName)}, NULL::text) <@ ${values}`
+          : `${identifier(field.storageName)} = ANY (${values})`;
+        addCheck(table, field.storageName, 'enum', expression);
+      }
+      if (field.kind === 'scalar' && field.list && field.itemRequired) {
+        addCheck(table, field.storageName, 'items', `array_position(${identifier(field.storageName)}, NULL::${scalarTypes[field.scalar]}) IS NULL`);
+      }
+    }
+  };
+  for (const entity of entities) addTable(entity.name);
+  for (const entity of entities) {
+    const table = tables.find((item) => item.name === entity.name);
+    fieldsInto(table, entity.fields);
+    for (const index of entity.indexes) {
+      const columns = index.fields.map((name) => {
+        const field = entity.fields.find((item) => item.name === name || item.storageName === name);
+        if (!field || !['scalar', 'reference'].includes(field.kind) || field.list) invalid(`Index ${entity.name}.${name} must refer to a stored scalar or reference`);
+        return field.name === '_id' ? 'id' : field.storageName;
+      });
+      addIndex(table, columns, index.unique);
+    }
+  }
+  const generated = constraints.finish();
+  generated.functions.push(...queryFunctions(schema));
+  // PostgreSQL shares one namespace for table and index names.
+  const relationNames = new Set(tables.map((table) => table.name));
+  for (const table of tables) {
+    const constraints = new Set();
+    for (const constraint of [table.primaryKey, ...table.foreignKeys, ...table.checks]) {
+      if (constraints.has(constraint.name)) invalid(`Constraint name collision: ${table.name}.${constraint.name}`);
+      constraints.add(constraint.name);
+    }
+    for (const index of [table.primaryKey, ...table.indexes]) {
+      if (relationNames.has(index.name)) invalid(`Index name collision: ${index.name}`);
+      relationNames.add(index.name);
+    }
+  }
+  return { schema, tables: tables.sort((a, b) => a.name.localeCompare(b.name)), ...generated };
+};

package/src/schema/initialize.js

@@ -0,0 +1,271 @@
+import { SimfinityError } from '@simtlix/simfinity-core';
+import { identifier, qualified } from './sql.js';
+import { createTableSQL, createForeignKeySQL, createIndexSQL, createFunctionSQL, createTriggerSQL } from './ddl.js';
+
+const mismatch = (object, reason) => {
+  throw new SimfinityError(`Schema mismatch at ${object}: ${reason}. Apply an explicit migration before startup.`, 'SCHEMA_MISMATCH', 409);
+};
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// Ignore renderer whitespace/optional quotes, keeping string contents and expression grouping.
+const normalizeExpression = (expression) => {
+  if (expression == null) return null;
+  const tokens = expression.match(/'(?:[^']|'')*'|"(?:[^"]|"")*"|\s+|./gs) || [];
+  let value = tokens.map((token) => {
+    if (token.startsWith('\'')) return token;
+    if (/^"[a-z_][a-z0-9_]*"$/.test(token)) return token.slice(1, -1);
+    return /^\s+$/.test(token) ? '' : token;
+  }).join('');
+  while (value.startsWith('(') && value.endsWith(')')) {
+    const parts = value.match(/'(?:[^']|'')*'|"(?:[^"]|"")*"|./gs);
+    let depth = 0;
+    let encloses = true;
+    for (let i = 0; i < parts.length; i += 1) {
+      if (parts[i] === '(') depth += 1;
+      if (parts[i] === ')') depth -= 1;
+      if (depth === 0 && i < parts.length - 1) { encloses = false; break; }
+    }
+    if (!encloses) break;
+    value = value.slice(1, -1);
+  }
+  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,
+    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,
+    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,
+    (SELECT count(*) = 4 AND bool_and(t.tgenabled IN ('O', 'A') AND t.tgisinternal)
+      FROM pg_trigger t WHERE t.tgconstraint = c.oid) AS enforcement_enabled,
+    n.nspname AS target_schema, t.relname AS target_table, pg_get_expr(c.conbin, c.conrelid) AS expression,
+    ARRAY(SELECT a.attname::text FROM unnest(c.conkey) WITH ORDINALITY k(num, pos)
+      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,
+    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,
+    ARRAY(SELECT a.attname::text FROM unnest(i.indkey) WITH ORDINALITY k(num, pos)
+      LEFT JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.num ORDER BY k.pos) AS columns,
+    NOT EXISTS (SELECT 1 FROM unnest(i.indoption) opt WHERE opt <> 0) AS default_order,
+    NOT EXISTS (SELECT 1 FROM unnest(i.indclass) cls JOIN pg_opclass opc ON opc.oid = cls WHERE NOT opc.opcdefault) AS default_ops,
+    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]);
+  return { columns, constraints, indexes };
+};
+
+const validateBase = (schema, table, actual, triggers = []) => {
+  const name = `${schema}.${table.name}`;
+  if (!actual) mismatch(name, 'table is missing');
+  if (actual.columns.length !== table.columns.length) mismatch(name, 'column set differs');
+  for (const column of table.columns) {
+    const stored = actual.columns.find((item) => item.name === column.name);
+    if (!stored || stored.type !== column.type || stored.nullable !== column.nullable
+      || (column.collation && (stored.collation !== column.collation || stored.collation_schema !== 'pg_catalog'))
+      || normalizeExpression(stored.default) !== normalizeExpression(column.default || null) || stored.attidentity || stored.attgenerated) {
+      mismatch(`${name}.${column.name}`, 'column type, collation, nullability or default differs');
+    }
+  }
+  const primary = actual.constraints.find((item) => item.type === 'p');
+  if (!primary || primary.name !== table.primaryKey.name || !same(primary.columns, table.primaryKey.columns) || primary.deferrable || !primary.validated) mismatch(name, 'primary key differs');
+  const primaryIndex = actual.indexes.find((item) => item.primary);
+  if (!primaryIndex?.valid || !primaryIndex.ready) mismatch(name, 'primary key index is invalid');
+  for (const check of table.checks) {
+    const stored = actual.constraints.find((item) => item.name === check.name);
+    if (!stored || stored.type !== 'c' || !stored.validated || !stored.enforced || stored.no_inherit
+      || normalizeExpression(stored.expression) !== normalizeExpression(check.expression)) {
+      mismatch(`${name}.${check.name}`, `check constraint differs (expected ${check.expression}; found ${stored?.expression || 'missing'})`);
+    }
+  }
+  const expectedNames = new Set([table.primaryKey.name, ...table.checks.map((c) => c.name), ...table.foreignKeys.map((c) => c.name), ...triggers.filter((t) => t.table === table.name && t.constraint).map((t) => t.name)]);
+  for (const constraint of actual.constraints) {
+    // PostgreSQL 18 also catalogs table NOT NULL constraints (already checked via pg_attribute).
+    if (constraint.type === 'n') {
+      const column = table.columns.find((item) => same(constraint.columns, [item.name]));
+      if (!column || column.nullable || !constraint.validated || !constraint.enforced) mismatch(`${name}.${constraint.name}`, 'NOT NULL enforcement differs');
+      continue;
+    }
+    if (!expectedNames.has(constraint.name)) mismatch(`${name}.${constraint.name}`, 'unexpected constraint');
+  }
+};
+
+const validateForeignKey = (schema, table, key, actual) => {
+  if (actual.type !== 'f' || !same(actual.columns, key.columns) || actual.target_schema !== schema
+    || actual.target_table !== key.targetTable || !same(actual.target_columns, key.targetColumns)
+    || actual.delete_action !== (key.onDelete === 'CASCADE' ? 'c' : 'a') || actual.update_action !== 'a'
+    || actual.deferrable !== key.deferrable || actual.deferred !== key.initiallyDeferred || !actual.validated || !actual.enforced || actual.match_type !== 's' || !actual.enforcement_enabled) {
+    mismatch(`${schema}.${table.name}.${key.name}`, 'foreign key target, columns, actions, deferrability or enforcement differs');
+  }
+};
+const validateIndex = (schema, table, index, actual) => {
+  if (!same(actual.columns, index.columns) || actual.unique !== index.unique || actual.nulls_not_distinct !== index.nullsNotDistinct
+    || !actual.valid || !actual.ready || !actual.immediate || actual.method !== 'btree' || !actual.no_include
+    || !actual.no_predicate || !actual.no_expression || !actual.default_order || !actual.default_ops || !actual.default_collation) {
+    mismatch(`${schema}.${table.name}.${index.name}`, 'index definition differs');
+  }
+};
+
+const ensureFunctions = async (client, description, mode, 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]);
+    if (!rows.length) {
+      if (mode === 'validate') mismatch(`${description.schema}.${fn.name}`, 'function is missing');
+      await client.query(createFunctionSQL(description.schema, fn));
+      created.push(`function:${description.schema}.${fn.name}`);
+      continue;
+    }
+    const stored = rows[0];
+    if (rows.length !== 1 || stored.arguments !== fn.arguments.join(', ') || stored.returns !== fn.returns
+      || stored.body !== fn.body || stored.language !== fn.language || stored.volatility !== fn.volatility[0].toLowerCase()
+      || !same(stored.configuration, fn.configuration) || stored.prosecdef || stored.proisstrict || stored.proleakproof
+      || stored.proparallel !== 'u' || stored.prokind !== 'f' || stored.proretset || stored.pronargdefaults
+      || stored.procost !== 100 || stored.prorows !== 0 || stored.support !== 0) {
+      mismatch(`${description.schema}.${fn.name}`, 'function identity, body, signature or configuration differs');
+    }
+  }
+};
+
+const ensureTriggers = async (client, description, mode, 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]);
+    if (!rows.length) {
+      if (mode === 'validate') mismatch(`${description.schema}.${trigger.name}`, 'trigger is missing');
+      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));
+      created.push(`trigger:${description.schema}.${trigger.table}.${trigger.name}`);
+      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 !== ''
+      || 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))) {
+      mismatch(`${description.schema}.${trigger.table}.${trigger.name}`, 'trigger definition or enforcement differs');
+    }
+  }
+};
+
+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');
+    }
+  }
+  // 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 item of description.maintenance || []) {
+    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. */
+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;
+  identifier(schema);
+  if (schema.startsWith('pg_') || schema === 'information_schema') throw new SimfinityError('System schemas cannot be managed', 'INVALID_DATABASE_SCHEMA', 400);
+  const client = await pool.connect();
+  const created = [];
+  try {
+    await client.query(mode === 'validate' ? 'BEGIN READ ONLY' : 'BEGIN');
+    await client.query('SET LOCAL search_path = pg_catalog');
+    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);
+    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}`);
+        }
+      }
+      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');
+      }
+    }
+    await ensureTriggers(client, description, mode, created);
+    if (mode === 'create' && created.length) await backfill(client, description);
+    await client.query('COMMIT');
+    return { mode, created };
+  } catch (error) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw error;
+  } finally {
+    client.release();
+  }
+};

package/src/schema/sql.js

@@ -0,0 +1,28 @@
+import { createHash } from 'node:crypto';
+import { SimfinityError } from '@simtlix/simfinity-core';
+
+export const invalid = (message) => {
+  throw new SimfinityError(message, 'INVALID_DATABASE_SCHEMA', 400);
+};
+
+export const identifier = (value) => {
+  if (typeof value !== 'string' || !value.length || value.includes('\0') || Buffer.byteLength(value) > 63) {
+    invalid(`Invalid PostgreSQL identifier: ${String(value)}`);
+  }
+  return `"${value.replaceAll('"', '""')}"`;
+};
+export const literal = (value) => {
+  const text = String(value);
+  const escaped = text.replaceAll('\\', '\\\\').replaceAll('\'', '\'\'');
+  return `${text.includes('\\') ? 'E' : ''}'${escaped}'`;
+};
+export const qualified = (schema, table) => `${identifier(schema)}.${identifier(table)}`;
+export const columnsSQL = (columns) => columns.map(identifier).join(', ');
+export const generatedName = (...parts) => {
+  const name = parts.join('__');
+  if (Buffer.byteLength(name) <= 63) return name;
+  const hash = createHash('sha256').update(name).digest('hex').slice(0, 12);
+  let prefix = name;
+  while (Buffer.byteLength(prefix) > 50) prefix = prefix.slice(0, -1);
+  return `${prefix}_${hash}`;
+};