@simtlix/simfinity-postgres 3.2.0 → 3.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @simtlix/simfinity-postgres
 
-PostgreSQL 15 or later support for the Simfinity GraphQL runtime. The package requires GraphQL 16 and Node.js 18.18 or later, depends on `pg` and `@simtlix/simfinity-core`, and has no Mongoose or MongoDB dependency.
+PostgreSQL 15 or later support for the Simfinity GraphQL runtime. The package requires GraphQL 16 and Node.js 18.18 or later, depends on `pg`, `@simtlix/simfinity-sql`, and `@simtlix/simfinity-core`, and has no Mongoose or MongoDB dependency.
 
-Version 3.2.0 is released together with the other Simfinity packages. Install from npm and keep their versions aligned. Source and the complete startup guide: [simtlix/simfinity.js](https://github.com/simtlix/simfinity.js), [`docs/guide/postgresql.md`](https://github.com/simtlix/simfinity.js/blob/master/docs/guide/postgresql.md).
+Version 3.3.0 is released together with the other Simfinity packages. Install from npm and keep their versions aligned. Source and the complete startup guide: [simtlix/simfinity.js](https://github.com/simtlix/simfinity.js), [`docs/guide/postgresql.md`](https://github.com/simtlix/simfinity.js/blob/master/docs/guide/postgresql.md).
 
 ## Runtime
 
@@ -22,7 +22,18 @@ await simfinity.initializeDatabase({ mode: 'create' });
 // Serve `schema`; the application remains responsible for `await pool.end()`.
 ```
 
-`createPostgres` permanently binds 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.
+`createPostgres` uses the driver-free SQL runtime with the PostgreSQL plugin. The equivalent explicit entry point is:
+
+```javascript
+import { createSQL } from '@simtlix/simfinity-sql';
+import { postgresPlugin } from '@simtlix/simfinity-postgres';
+
+const simfinity = createSQL({ plugin: postgresPlugin({ pool, schema: 'library' }) });
+```
+
+Install `@simtlix/simfinity-sql@3.3.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.
 
 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.
 
@@ -42,14 +53,14 @@ const schema = createSchema();
 await initializeDatabase({ mode: 'validate' });
 ```
 
-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; mutation input is reset for each attempt. The caller owns the pool lifecycle.
+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; 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.2.0 @modelcontextprotocol/sdk@^1.13.0
+npm install @simtlix/simfinity-mcp@3.3.0 @modelcontextprotocol/sdk@^1.13.0
 ```
 
 ```javascript

package/package.json

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

package/src/adapter.js

@@ -1,125 +1,4 @@
-import { randomUUID } from 'node:crypto';
-import { getNamedType } from 'graphql';
-import { describeModels, createQueryPlan, SimfinityError } from '@simtlix/simfinity-core';
-import { describeDatabase } from './schema/describe.js';
-import { initializeDatabase } from './schema/initialize.js';
-import { compileQuery } from './query/compiler.js';
-import { createRecordStore } from './records.js';
-import { createTransactions } from './transactions.js';
-import { castId, encodeParameter, normalizeDatabaseError } from './codecs.js';
+import { createSQLAdapter } from '@simtlix/simfinity-sql/internal/adapter';
+import { postgresPlugin } from './plugin.js';
 
-export const createPostgresAdapter = (options) => {
-  let configured = options ? Object.freeze({ ...options }) : null;
-  let prepared = false;
-  let ready = false;
-  let allowSchemaCreation = true;
-  let models; let database; let records;
-  const handles = new Map();
-  const assertReady = () => {
-    if (!ready) throw new SimfinityError('Initialize the PostgreSQL database before executing operations', 'DATABASE_NOT_INITIALIZED', 503);
-  };
-  const getPool = () => configured.pool;
-  const transactions = createTransactions(getPool, assertReady);
-  const query = async (text, values, session) => {
-    assertReady();
-    // Retryable errors must reach withTransaction unchanged, so normalize only at operation boundaries.
-    const client = session ? transactions.requireSession(session) : getPool();
-    return client.query(text, values?.map(encodeParameter));
-  };
-  const safe = (operation) => async (...args) => {
-    try { return await operation(...args); } catch (error) {
-      if (['40001', '40P01'].includes(error.code)) throw error;
-      throw normalizeDatabaseError(error);
-    }
-  };
-  const nameOf = (model) => {
-    assertReady();
-    if (!model || handles.get(model.name) !== model || !models.entities.some((item) => item.name === model.name)) throw new SimfinityError('Invalid PostgreSQL model handle', 'INVALID_MODEL', 400);
-    return model.name;
-  };
-  const execute = async (model, gqltype, args, session, mode, extra) => {
-    const name = nameOf(model);
-    const plan = createQueryPlan(models, name, args, { mode });
-    const compiled = compileQuery(models, database, plan, extra);
-    const { rows } = await query(compiled.text, compiled.values, session);
-    if (mode === 'count') return Number(rows[0]?.size || 0);
-    const decodeAggregate = (value, field) => Array.isArray(value) ? value.map((item) => decodeAggregate(item, field)) : value != null && field.scalar === 'DateTime' ? new Date(value) : value;
-    if (mode === 'aggregate') return rows.map((row) => ({
-      groupId: decodeAggregate(row.groupId, compiled.aggregateFields[0]),
-      facts: Object.fromEntries(plan.aggregation.facts.map((fact, index) => {
-        const value = row[`fact_${index}`];
-        return [fact.factName, value == null ? null : ['SUM', 'COUNT', 'AVG'].includes(fact.operation) ? Number(value) : decodeAggregate(value, compiled.aggregateFields[index + 1])];
-      })),
-    }));
-    return records.hydrateRows(name, rows, session);
-  };
-  const adapter = {
-    configure(value) {
-      if (configured || prepared) throw new SimfinityError('PostgreSQL configuration is already bound', 'DATABASE_ALREADY_CONFIGURED', 409);
-      configured = Object.freeze({ ...value });
-    },
-    validateRegistration(registration) {
-      if (prepared) throw new SimfinityError('Register types before creating the schema', 'SCHEMA_ALREADY_CREATED', 409);
-      const model = registration.model;
-      if (model && !handles.has(model.name)) throw new SimfinityError('External Mongoose models cannot be used with PostgreSQL', 'INVALID_MODEL', 400);
-    },
-    prepare(registrations, { createCollection = true } = {}) {
-      if (prepared) return;
-      if (!configured?.pool?.connect || !configured.pool.query) throw new SimfinityError('Configure a pg.Pool before creating the schema', 'DATABASE_NOT_CONFIGURED', 500);
-      models = describeModels(registrations);
-      for (const registration of registrations.filter((item) => item.stateMachine)) {
-        const state = models.entities.find((item) => item.name === registration.gqltype.name)?.fields.find((item) => item.name === 'state');
-        if (state) state.stateNames = getNamedType(registration.gqltype.getFields().state.type).getValues().map((item) => ({ value: String(item.value), name: item.name }));
-      }
-      database = describeDatabase(registrations, { schema: configured.schema || 'public' });
-      allowSchemaCreation = createCollection;
-      records = createRecordStore(models, database, query);
-      prepared = true;
-    },
-    createModel(gqltype, onModelCreated) {
-      const model = {
-        name: gqltype.name, gqltype,
-        findById: (id, { session } = {}) => adapter.getById(model, id, session),
-        find: (args = {}, { session } = {}) => adapter.find(model, gqltype, args, session),
-        create: (data, { session } = {}) => adapter.withTransaction(session, (transaction) => adapter.saveRecord(model, adapter.newRecord(model, data, transaction), transaction)),
-        update: (id, changes, { session } = {}) => adapter.withTransaction(session, (transaction) => adapter.update(model, id, changes, transaction)),
-        delete: (id, { session } = {}) => adapter.withTransaction(session, (transaction) => adapter.delete(model, id, transaction)),
-      };
-      handles.set(model.name, model);
-      if (onModelCreated) onModelCreated(model);
-      return model;
-    },
-    castId,
-    stateValue: (state) => state.value,
-    withTransaction: transactions.withTransaction,
-    newRecord(model, data) { nameOf(model); const id = data._id || data.id || randomUUID(); return { ...data, _id: castId(id), id: castId(id) }; },
-    toObject(record) { return record == null ? record : { ...record }; },
-    saveRecord: safe((model, record, session) => transactions.withTransaction(session, (transaction) => records.create(nameOf(model), record, transaction))),
-    getById: safe((model, id, session, options = {}) => transactions.withTransaction(session, (transaction) => records.getById(nameOf(model), id, transaction, options))),
-    prepareUpdate(set, unset) { return { ...set, ...(Object.keys(unset).length ? { $unset: { ...unset } } : {}) }; },
-    update: safe((model, id, update, session) => records.update(nameOf(model), id, update, session)),
-    delete: safe((model, id, session) => records.remove(nameOf(model), id, session)),
-    find: safe((model, gqltype, args, session, { requiredId } = {}) => transactions.withTransaction(session, (transaction) => execute(model, gqltype, args, transaction, 'find', requiredId == null ? null : { column: 'id', id: castId(requiredId) }))),
-    count: safe((model, gqltype, args, session) => execute(model, gqltype, args, session, 'count')),
-    aggregate: safe((model, gqltype, args, session) => execute(model, gqltype, args, session, 'aggregate')),
-    findChildren: safe((model, gqltype, connectionField, parentId, args, session) => {
-      const entity = models.entities.find((item) => item.name === nameOf(model));
-      const field = entity.fields.find((item) => item.name === connectionField || item.storageName === connectionField);
-      if (!field || field.kind !== 'reference') throw new SimfinityError('Invalid inverse connection field', 'INVALID_MODEL', 400);
-      return transactions.withTransaction(session, (transaction) => execute(model, gqltype, args, transaction, 'find', { column: field.storageName, id: castId(parentId) }));
-    }),
-    async initialize(options = {}) {
-      if (!prepared) throw new SimfinityError('Create the GraphQL schema before initializing storage', 'SCHEMA_NOT_CREATED', 500);
-      ready = false;
-      if (!allowSchemaCreation && options.mode && options.mode !== 'validate') throw new SimfinityError('Database creation is disabled; initialize in validate mode', 'DATABASE_CREATION_DISABLED', 409);
-      const result = await initializeDatabase(getPool(), database, allowSchemaCreation ? options : { ...options, mode: 'validate' });
-      ready = true;
-      return result;
-    },
-    describeDatabase() {
-      if (!prepared) throw new SimfinityError('Create the GraphQL schema first', 'SCHEMA_NOT_CREATED', 500);
-      return structuredClone(database);
-    },
-  };
-  return adapter;
-};
+export const createPostgresAdapter = (options) => createSQLAdapter(postgresPlugin(options));

package/src/index.js

@@ -1,13 +1,8 @@
-import {
-  auth,
-  createRuntime,
-  plugins,
-  scalars,
-  validators,
-} from '@simtlix/simfinity-core';
-import { createPostgresAdapter } from './adapter.js';
+import { createSQL } from '@simtlix/simfinity-sql';
+import { postgresPlugin } from './plugin.js';
 import { initializeDatabase as initializeSchema } from './schema/initialize.js';
 
+export { postgresPlugin } from './plugin.js';
 export { describeDatabase } from './schema/describe.js';
 export { compileDatabaseSchema } from './schema/ddl.js';
 export {
@@ -22,21 +17,7 @@ export {
 } from '@simtlix/simfinity-core';
 
 /** Each instance permanently binds one pool/schema; getModel exposes PostgreSQL native helpers. */
-export const createPostgres = (options) => {
-  const adapter = createPostgresAdapter(options);
-  const runtime = createRuntime(adapter);
-  return {
-    ...runtime,
-    auth,
-    configure: (configuration) => adapter.configure(configuration),
-    initializeDatabase: (initialization) => adapter.initialize(initialization),
-    describeDatabase: () => adapter.describeDatabase(),
-    plugins,
-    scalars,
-    validators,
-    withTransaction: (session, callback) => adapter.withTransaction(session, callback),
-  };
-};
+export const createPostgres = (options) => createSQL({ plugin: postgresPlugin(options) });
 const defaultInstance = createPostgres();
 export const { configureQueryLimits, configure, connect, addNoEndpointType, createSchema, getModel, getType, getInputType, getRegistrations, use, registerMutation, saveObject, preventCreatingCollection, withTransaction } = defaultInstance;
 

package/src/plugin.js

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+import { SimfinityError } from '@simtlix/simfinity-core';
+import { identifier, generatedName } from './schema/sql.js';
+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 { castId, encodeScalar, decodeScalar, encodeParameter, normalizeDatabaseError } from './codecs.js';
+
+export const postgresPlugin = (options) => ({
+  apiVersion: 1,
+  name: 'postgres',
+  displayName: 'PostgreSQL',
+  defaultSchema: 'public',
+  options: options || null,
+  capabilities: ['transactions', 'foreignKeys', 'deferredForeignKeys', 'embeddedValues', 'ownedRecords', 'scalarLists', 'uniqueValues', 'nullableUnique'],
+  naming: { validateIdentifier: identifier, generatedName },
+  describeSchema: describeRelationalSchema,
+  initialize: (configuration, description, initialization) => initializeDatabase(configuration.pool, description, initialization),
+  compileSchema: compileDatabaseSchema,
+  compileQuery,
+  compileRecord,
+  values: { createId: randomUUID, castId, encodeScalar, decodeScalar, encodeEmbedded: JSON.stringify },
+  driver: {
+    assertConfiguration(configuration) {
+      if (!configuration?.pool?.connect || !configuration.pool.query) throw new SimfinityError('Configure a pg.Pool before creating the schema', 'DATABASE_NOT_CONFIGURED', 500);
+    },
+    query: (configuration, statement, client) => (client || configuration.pool).query(statement.text, statement.values?.map(encodeParameter)),
+    acquire: (configuration) => configuration.pool.connect(),
+    begin: (client) => client.query('BEGIN ISOLATION LEVEL REPEATABLE READ'),
+    commit: (client) => client.query('COMMIT'),
+    rollback: (client) => client.query('ROLLBACK'),
+    release: (client) => client.release(),
+    isRetryable: (error) => ['40001', '40P01'].includes(error.code),
+    normalizeError: normalizeDatabaseError,
+  },
+});

package/src/record-statements.js

@@ -0,0 +1,22 @@
+import { SimfinityError } from '@simtlix/simfinity-core';
+import { identifier as q, qualified } from './schema/sql.js';
+
+/** operation.table is the physical table metadata returned by describeSchema. */
+export const compileRecord = (database, operation) => {
+  const { kind, table: storage, id, data } = operation;
+  const target = qualified(database.schema, storage.name);
+  if (kind === 'selectById') return { text: `SELECT * FROM ${target} WHERE id = $1::uuid${operation.lock ? ' FOR UPDATE' : ''}`, values: [id] };
+  if (kind === 'selectOwned') return { text: `SELECT * FROM ${target} WHERE "__owner_id" = ANY ($1::uuid[])${operation.ordered ? ' ORDER BY "__position"' : ''}`, values: [operation.ids] };
+  if (kind === 'deleteById') return { text: `DELETE FROM ${target} WHERE id = $1::uuid`, values: [id] };
+  if (kind === 'deleteOwned') return { text: `DELETE FROM ${target} WHERE "__owner_id" = $1::uuid`, values: [operation.ownerId] };
+  if (kind === 'insert') {
+    const entries = Object.entries(data);
+    const placeholders = entries.map(([name], index) => `$${index + 1}::${storage.columns.find((column) => column.name === name).type}`);
+    return { text: `INSERT INTO ${target} (${entries.map(([name]) => q(name)).join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING *`, values: entries.map(([, value]) => value) };
+  }
+  if (kind === 'update') {
+    const entries = Object.entries(data);
+    return { text: `UPDATE ${target} SET ${entries.map(([key], index) => `${q(key)} = $${index + 2}::${storage.columns.find((column) => column.name === key).type}`).join(', ')} WHERE id = $1::uuid RETURNING *`, values: [id, ...entries.map(([, value]) => value)] };
+  }
+  throw new SimfinityError(`Unknown record operation ${kind}`, 'INVALID_RECORD_OPERATION', 400);
+};

package/src/records.js

@@ -1,219 +1,4 @@
-import { randomUUID } from 'node:crypto';
-import { getNamedType } from 'graphql';
-import { SimfinityError } from '@simtlix/simfinity-core';
-import { identifier as q, qualified } from './schema/sql.js';
-import { castId, encodeScalar, decodeScalar } from './codecs.js';
+import { createRecordStore as createSQLRecordStore } from '@simtlix/simfinity-sql/internal/records';
+import { postgresPlugin } from './plugin.js';
 
-const missing = (name) => { throw new SimfinityError(`Required value ${name} is missing`, 'REQUIRED_VALUE', 400); };
-const shapeError = (name) => { throw new SimfinityError(`Invalid value for ${name}`, 'INVALID_VALUE', 400); };
-
-export const createRecordStore = (models, database, query) => {
-  const model = (name) => models.entities.find((item) => item.name === name);
-  const table = (name) => database.tables.find((item) => item.name === name);
-  const children = (owner) => database.tables.filter((item) => item.ownership?.ownerTable === owner.name);
-  const child = (owner, field) => children(owner).find((item) => item.ownership.field === field.name);
-  const gqlFields = (type) => type?.getFields() || {};
-  const encodeValue = (field, value) => {
-    if (value == null) return null;
-    if (field.kind === 'embedded') return mapEmbedded(field, value, encodeFields);
-    if (field.list) {
-      if (!Array.isArray(value)) shapeError(field.name);
-      return value.map((item) => {
-        if (item == null && field.itemRequired) missing(`${field.name}[]`);
-        return encodeScalar(field, item);
-      });
-    }
-    return encodeScalar(field, value);
-  };
-  const mapEmbedded = (field, value, mapper, gqltype) => {
-    if (value == null) return value;
-    if (field.list) {
-      if (!Array.isArray(value)) shapeError(field.name);
-      return value.map((item) => {
-        if (item == null) { if (field.itemRequired) missing(`${field.name}[]`); return null; }
-        return mapper(field.fields, item, gqltype);
-      });
-    }
-    return mapper(field.fields, value, gqltype);
-  };
-  // Mongoose inline objects materialize descendant array defaults and minimize
-  // scalar-only empty objects. Embedded array items themselves are retained.
-  const normalize = (fields, data, full = true) => {
-    if (!data || typeof data !== 'object' || Array.isArray(data)) shapeError('embedded object');
-    const result = { ...data };
-    for (const field of fields) {
-      if (field.kind === 'collection' || (!full && !Object.hasOwn(data, field.storageName))) continue;
-      let value = data[field.storageName];
-      if (value === undefined && !full) continue;
-      if (value === undefined && full && field.list) value = [];
-      if (field.kind === 'embedded' && value !== null) {
-        if (field.list) {
-          if (!Array.isArray(value)) shapeError(field.name);
-          value = value.map((item) => item == null ? item : normalize(field.fields, item));
-        } else {
-          value = normalize(field.fields, value ?? {});
-          if (!Object.keys(value).length) value = undefined;
-        }
-      }
-      if (value !== undefined) result[field.storageName] = value;
-      else if (full) delete result[field.storageName];
-      else result[field.storageName] = undefined;
-    }
-    return result;
-  };
-  const encodeFields = (fields, data) => {
-    if (!data || typeof data !== 'object' || Array.isArray(data)) shapeError('embedded object');
-    const result = {};
-    for (const field of fields) {
-      if (field.kind === 'collection') continue;
-      const value = data[field.storageName];
-      if (value == null && field.required) missing(field.name);
-      if (value !== undefined) result[field.storageName] = encodeValue(field, value);
-      else if (field.list) result[field.storageName] = [];
-    }
-    return result;
-  };
-  const decodeFields = (fields, data, gqltype) => {
-    const result = {};
-    for (const field of fields) {
-      if (field.kind === 'collection' || data[field.storageName] === undefined) continue;
-      const value = data[field.storageName];
-      const gqlField = gqlFields(gqltype)[field.name];
-      if (field.kind === 'embedded') result[field.storageName] = mapEmbedded(field, value, decodeFields, gqlField && getNamedType(gqlField.type));
-      else result[field.storageName] = field.list && value ? value.map((item) => decodeScalar(field, item, gqlField)) : decodeScalar(field, value, gqlField);
-    }
-    return result;
-  };
-  const hydrate = async (storage, fields, rows, gqltype, session) => {
-    const result = rows.map((row) => {
-      const visible = { ...row };
-      for (const column of storage.columns) if (column.presenceColumn && row[column.name] == null && !row[column.presenceColumn]) delete visible[column.name];
-      const value = decodeFields(fields, visible, gqltype);
-      if (!storage.ownership) { value._id = row.id; value.id = row.id; }
-      return value;
-    });
-    if (!rows.length) return result;
-    for (const owned of children(storage)) {
-      const field = fields.find((item) => item.name === owned.ownership.field);
-      const ids = rows.filter((row) => row[owned.ownership.stateColumn] === 'present').map((row) => row[storage.primaryKey.columns[0]]);
-      let ownedRows = [];
-      if (ids.length) ownedRows = (await query(`SELECT * FROM ${qualified(database.schema, owned.name)} WHERE "__owner_id" = ANY ($1::uuid[])${field.list ? ' ORDER BY "__position"' : ''}`, [ids], session)).rows;
-      const decoded = await hydrate(owned, field.fields, ownedRows, getNamedType(gqlFields(gqltype)[field.name].type), session);
-      const byOwner = new Map();
-      ownedRows.forEach((row, index) => {
-        const list = byOwner.get(row.__owner_id) || [];
-        list.push(owned.ownership.nullableItems && !row.__item_present ? null : decoded[index]);
-        byOwner.set(row.__owner_id, list);
-      });
-      rows.forEach((row, index) => {
-        const state = row[owned.ownership.stateColumn];
-        if (state === 'null') result[index][field.storageName] = null;
-        else if (state === 'present') {
-          const items = byOwner.get(row[storage.primaryKey.columns[0]]) || [];
-          result[index][field.storageName] = field.list ? items : items[0] ?? null;
-        }
-      });
-    }
-    return result;
-  };
-  const columnValues = (storage, fields, data, full, nullItem = false) => {
-    const result = {};
-    for (const field of fields) {
-      if (field.kind === 'collection' || (!storage.ownership && ['id', '_id'].includes(field.name))) continue;
-      const present = Object.hasOwn(data, field.storageName);
-      let value = data[field.storageName];
-      if (!present && !full) continue;
-      if (!present && full && field.list && !nullItem) value = [];
-      const owned = child(storage, field);
-      if (owned) {
-        if (value == null && field.required && !nullItem) missing(field.name);
-        result[owned.ownership.stateColumn] = value === undefined ? 'missing' : value === null ? 'null' : 'present';
-      } else {
-        if (value == null && field.required && !nullItem) missing(field.name);
-        const presenceColumn = storage.columns.find((column) => column.name === field.storageName)?.presenceColumn;
-        if (presenceColumn) result[presenceColumn] = value !== undefined && !nullItem;
-        if (value !== undefined) {
-          const encoded = encodeValue(field, value);
-          result[field.storageName] = field.kind === 'embedded' && encoded != null ? JSON.stringify(encoded) : encoded;
-        } else if (full || field.kind === 'embedded') result[field.storageName] = null;
-      }
-    }
-    return result;
-  };
-  const insertRow = async (storage, data, session) => {
-    const entries = Object.entries(data);
-    const placeholders = entries.map(([name], index) => `$${index + 1}::${storage.columns.find((column) => column.name === name).type}`);
-    return (await query(`INSERT INTO ${qualified(database.schema, storage.name)} (${entries.map(([name]) => q(name)).join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING *`, entries.map(([, value]) => value), session)).rows[0];
-  };
-  const persistOwned = async (storage, fields, ownerId, data, session, replace = false) => {
-    for (const owned of children(storage)) {
-      const field = fields.find((item) => item.name === owned.ownership.field);
-      if (!Object.hasOwn(data, field.storageName)) continue;
-      if (replace) await query(`DELETE FROM ${qualified(database.schema, owned.name)} WHERE "__owner_id" = $1::uuid`, [ownerId], session);
-      const value = data[field.storageName];
-      if (value == null) continue;
-      if (field.list && !Array.isArray(value)) shapeError(field.name);
-      const entries = field.list ? value : [value];
-      for (let index = 0; index < entries.length; index++) {
-        const entry = entries[index];
-        if (entry == null && (!field.list || field.itemRequired)) missing(`${field.name}[]`);
-        if (entry != null && (typeof entry !== 'object' || Array.isArray(entry))) shapeError(field.name);
-        const row = { __id: randomUUID(), __owner_id: ownerId, ...columnValues(owned, field.fields, entry || {}, true, entry == null) };
-        if (field.list) row.__position = index;
-        if (owned.ownership.nullableItems) row.__item_present = entry != null;
-        await insertRow(owned, row, session);
-        if (entry) await persistOwned(owned, field.fields, row.__id, entry, session);
-      }
-    }
-  };
-  const hydrateRows = async (name, rows, session) => {
-    const entity = model(name);
-    if (!entity) throw new SimfinityError(`Type ${name} is not an entity`, 'INVALID_MODEL', 400);
-    return hydrate(table(name), entity.fields, rows, entity.gqltype, session);
-  };
-  const getById = async (name, value, session, { projection, lock, requiredId } = {}) => {
-    if (value == null) return null;
-    const id = castId(value);
-    if (requiredId != null && id !== castId(requiredId)) return null;
-    const rows = (await query(`SELECT * FROM ${qualified(database.schema, name)} WHERE id = $1::uuid${lock ? ' FOR UPDATE' : ''}`, [id], session)).rows;
-    const [record] = await hydrateRows(name, rows, session);
-    if (!record) return null;
-    return projection ? Object.fromEntries(Object.entries(record).filter(([key]) => key === '_id' || key === 'id' || projection[key])) : record;
-  };
-  const create = async (name, record, session) => {
-    const entity = model(name);
-    if (!entity) throw new SimfinityError(`Type ${name} is not an entity`, 'INVALID_MODEL', 400);
-    const storage = table(name);
-    const normalized = normalize(entity.fields, record);
-    const data = { id: castId(normalized._id || normalized.id), ...columnValues(storage, entity.fields, normalized, true) };
-    const row = await insertRow(storage, data, session);
-    await persistOwned(storage, entity.fields, row.id, normalized, session);
-    return (await hydrateRows(name, [row], session))[0];
-  };
-  const update = async (name, value, changes, session) => {
-    const id = castId(value);
-    const entity = model(name); const storage = table(name);
-    const source = normalize(entity.fields, changes, false);
-    delete source.$unset;
-    for (const field of Object.keys(changes.$unset || {})) source[field] = undefined;
-    const data = columnValues(storage, entity.fields, source, false);
-    for (const field of Object.keys(changes.$unset || {})) {
-      const column = storage.columns.find((item) => item.name === field);
-      if (column && !['id', '_id'].includes(field)) data[field] = null;
-    }
-    const entries = Object.entries(data);
-    let rows;
-    if (entries.length) rows = (await query(`UPDATE ${qualified(database.schema, name)} SET ${entries.map(([key], index) => `${q(key)} = $${index + 2}::${storage.columns.find((column) => column.name === key).type}`).join(', ')} WHERE id = $1::uuid RETURNING *`, [id, ...entries.map(([, value]) => value)], session)).rows;
-    else rows = (await query(`SELECT * FROM ${qualified(database.schema, name)} WHERE id = $1::uuid`, [id], session)).rows;
-    if (!rows.length) return null;
-    await persistOwned(storage, entity.fields, id, source, session, true);
-    return (await hydrateRows(name, rows, session))[0];
-  };
-  const remove = async (name, value, session) => {
-    const record = await getById(name, value, session);
-    if (!record) return null;
-    await query(`DELETE FROM ${qualified(database.schema, name)} WHERE id = $1::uuid`, [record._id], session);
-    return record;
-  };
-  return { create, update, remove, getById, hydrateRows };
-};
+export const createRecordStore = (models, database, query) => createSQLRecordStore(models, database, (statement, session) => query(statement.text, statement.values, session), postgresPlugin());

package/src/schema/describe.js

@@ -1,15 +1,17 @@
 import { describeModels } from '@simtlix/simfinity-core';
+import { planRelationalSchema } from '@simtlix/simfinity-sql';
 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)));
+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);
 
-/** Compile GraphQL storage metadata into a serializable PostgreSQL description. */
-export const describeDatabase = (registrations, { schema = 'public' } = {}) => {
+/** Lower engine-independent relational guarantees into PostgreSQL storage and enforcement. */
+export const describeRelationalSchema = (plan) => {
+  const { schema } = plan;
   identifier(schema);
-  const { entities } = describeModels(registrations);
   const tables = [];
   const names = new Set();
   const addTable = (name, ownership) => {
@@ -36,88 +38,44 @@ export const describeDatabase = (registrations, { schema = 'public' } = {}) => {
     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 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,
-    });
+    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]);
   };
+  for (const logical of plan.tables) {
+    const table = addTable(logical.name, logical.ownership && structuredClone(logical.ownership));
+    table.columns = [];
+    for (const column of logical.columns) addColumn(table, {
+      name: column.name, type: physicalType(column), nullable: column.nullable,
+      ...(column.default ? { default: physicalDefault(column.default) } : {}),
+      ...(column.presenceColumn ? { presenceColumn: column.presenceColumn } : {}),
+    });
+    table.primaryKey = structuredClone(logical.primaryKey);
+    table.foreignKeys = structuredClone(logical.foreignKeys);
+    table.indexes = logical.indexes.map(({ name, columns, unique, nullsEqual }) => ({ name, columns: [...columns], unique, nullsNotDistinct: nullsEqual }));
+  }
   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);
-    }
+  for (const item of plan.checkOrder) {
+    const table = tables.find((entry) => entry.name === item.table);
+    const check = plan.tables.find((entry) => entry.name === item.table).checks.find((entry) => entry.name === item.name);
+    const column = identifier(check.column);
+    if (check.kind === 'embeddedShape') { constraints.addJSON(table, check.field); continue; }
+    let expression;
+    if (check.kind === 'presentWhenItem') expression = `(NOT ${identifier('__item_present')}) OR (${column} = 'present'::text)`;
+    else if (check.kind === 'requiredWhenItem') expression = `(NOT ${identifier('__item_present')}) OR (${column} IS NOT NULL)`;
+    else if (check.kind === 'nonnegative') expression = `${column} >= 0`;
+    else if (check.kind === 'state') expression = `${column} = ANY (ARRAY[${check.values.map((value) => `${literal(value)}::text`).join(', ')}])`;
+    else if (check.kind === 'enum') {
+      const values = `ARRAY[${check.values.map((value) => `${literal(value)}::text`).join(', ')}]`;
+      expression = check.list ? `array_remove(${column}, NULL::text) <@ ${values}` : `${column} = ANY (${values})`;
+    } else if (check.kind === 'itemsRequired') expression = `array_position(${column}, NULL::${scalarTypes[check.scalar]}) IS NULL`;
+    else invalid(`Unsupported relational check: ${check.kind}`);
+    table.checks.push({ name: check.name, expression });
+  }
+  for (const item of plan.uniqueValues) {
+    const table = tables.find((entry) => entry.name === item.table);
+    constraints.addUnique(table, item.field, table.columns.find((entry) => entry.name === item.field.storageName).type);
   }
   const generated = constraints.finish();
   generated.functions.push(...queryFunctions(schema));
@@ -136,3 +94,8 @@ export const describeDatabase = (registrations, { schema = 'public' } = {}) => {
   }
   return { schema, tables: tables.sort((a, b) => a.name.localeCompare(b.name)), ...generated };
 };
+
+/** Compile GraphQL storage metadata into the compatible PostgreSQL description. */
+export const describeDatabase = (registrations, { schema = 'public' } = {}) => describeRelationalSchema(planRelationalSchema(describeModels(registrations), {
+  schema, naming: { validateIdentifier: identifier, generatedName },
+}));

package/src/transactions.js

@@ -1,32 +1,4 @@
-import { SimfinityError } from '@simtlix/simfinity-core';
-import { normalizeDatabaseError } from './codecs.js';
+import { createTransactions as createSQLTransactions } from '@simtlix/simfinity-sql/internal/transactions';
+import { postgresPlugin } from './plugin.js';
 
-export const createTransactions = (getPool, assertReady) => {
-  const sessions = new WeakSet();
-  const requireSession = (session) => {
-    if (!sessions.has(session) || !session.inTransaction()) throw new SimfinityError('Session is not an active transaction of this PostgreSQL instance', 'INVALID_SESSION', 400);
-    return session.client;
-  };
-  const withTransaction = async (session, body) => {
-    assertReady();
-    if (session) { requireSession(session); return body(session); }
-    for (let attempt = 0; attempt <= 5; attempt++) {
-      const client = await getPool().connect();
-      let active = true;
-      const handle = { client, inTransaction: () => active, query: (...args) => requireSession(handle).query(...args) };
-      sessions.add(handle);
-      try {
-        await client.query('BEGIN ISOLATION LEVEL REPEATABLE READ');
-        const result = await body(handle);
-        await client.query('COMMIT');
-        return result;
-      } catch (error) {
-        await client.query('ROLLBACK').catch(() => {});
-        // Only confirmed aborted transactions are retried, never unknown commit outcomes.
-        if (['40001', '40P01'].includes(error.code) && attempt < 5) continue;
-        throw normalizeDatabaseError(error);
-      } finally { active = false; sessions.delete(handle); client.release(); }
-    }
-  };
-  return { withTransaction, requireSession };
-};
+export const createTransactions = (getPool, assertReady) => createSQLTransactions(() => ({ pool: getPool() }), assertReady, postgresPlugin());

package/types/index.d.ts

@@ -1,4 +1,5 @@
 import type { ModelRegistration, Runtime } from '@simtlix/simfinity-core';
+import type { SQLPlugin } from '@simtlix/simfinity-sql';
 import { auth, plugins, scalars, validators } from '@simtlix/simfinity-core';
 import type { GraphQLObjectType } from 'graphql';
 export {
@@ -153,6 +154,13 @@ export interface PostgresRuntime extends Runtime<PostgresModel, PostgresSession>
   initializeDatabase(options?: InitializationOptions): Promise<InitializationResult>;
   withTransaction<T>(session: PostgresSession | null | undefined, callback: (session: PostgresSession) => Promise<T> | T): Promise<T>;
 }
+/** PostgreSQL 15+ plugin for createSQL; omitted options allow later runtime.configure. */
+export function postgresPlugin(options?: PostgresConfiguration): SQLPlugin<
+  PostgresConfiguration,
+  DatabaseQueryable,
+  DatabaseDescription,
+  { rows: Record<string, unknown>[]; rowCount: number | null }
+>;
 export function createPostgres(options?: PostgresConfiguration): PostgresRuntime;
 export const configure: PostgresRuntime['configure'];
 export const connect: PostgresRuntime['connect'];