@simtlix/simfinity-postgres 3.5.3 → 3.5.6

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.3` 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.5.6` 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.
+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.
 
-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.
+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.
 
 A default module instance is also available when a singleton facade is preferable:
 
@@ -53,14 +53,16 @@ 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. Unknown commit outcomes are not replayed. The caller owns the pool lifecycle.
+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.
 
 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.3 @modelcontextprotocol/sdk@^1.13.0
+npm install @simtlix/simfinity-mcp@3.5.6 @modelcontextprotocol/sdk@^1.31.0
 ```
 
 ```javascript
@@ -71,10 +73,12 @@ const mcpServer = await createMCPServer(schema);
 
 ## Storage and compatible subset
 
-Entity identities and references use UUIDs. Scalars use native PostgreSQL types, scalar lists use arrays, reference-free embedded values use JSONB, and embedded values containing references use private owned tables. Foreign keys, inverse collections, explicit linking entities, missing/null markers, nullable embedded-list items, hooks, rollback, and state transitions are supported by the runtime.
+Entity identities and references use UUIDs. Scalars use native PostgreSQL types, scalar lists (including `[ID]` lists) use arrays without a generated index, reference-free embedded values use JSONB, and embedded values containing references use private owned tables. Foreign keys, inverse collections, explicit linking entities, missing/null markers, nullable embedded-list items, hooks, rollback, and state transitions are supported by the runtime.
 
 Queries support nested scalar/reference paths, logical filter groups, scopes, sort, pagination, count, and grouped `SUM`, `COUNT`, `AVG`, `MIN`, and `MAX` facts. The PostgreSQL implementation preserves root multiplicity when joining collection paths.
 
+Errors that PostgreSQL reports become `SimfinityError`s without SQL details, with the driver error as `getCause()`; errors that application code throws propagate unchanged. Text cannot contain NUL and native date-times start at 4714-11-24 BC: such input fails with `INVALID_VALUE` (400).
+
 PostgreSQL enforces required values, real FKs, JSONB/owned embedded shapes, root and embedded scalar/reference uniqueness, and scalar-list multikey uniqueness. Root unique indexes use `NULLS NOT DISTINCT`; private typed owner-key tables allow repeated keys within one owner but reject the same key across owners. Presence markers preserve missing versus explicit null fields. This is stronger and broader than generated Mongoose storage.
 
 Scalar-list leaves inside nested embedded lists support filters, sorts, ragged group projections, and array-valued facts. Array `MIN`/`MAX` compares complete arrays; result sorting uses immediate extrema. Date parameters use per-query UTC encoding without changing global `pg` behavior.
@@ -97,4 +101,4 @@ const statements = compileDatabaseSchema(description);
 await initializeDatabase(pool, description, { mode: 'validate' });
 ```
 
-`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 })` 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.3",
+  "version": "3.5.6",
   "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.3",
-    "@simtlix/simfinity-sql": "3.5.3",
+    "@simtlix/simfinity-core": "3.5.6",
+    "@simtlix/simfinity-sql": "3.5.6",
     "pg": "^8.16.3"
   },
   "peerDependencies": {

package/src/codecs.js

@@ -44,19 +44,40 @@ export const decodeScalar = (field, value, gqlField) => {
   return value;
 };
 
+const databaseErrors = {
+  '23503': ['Reference constraint violated', 'REFERENCE_CONSTRAINT_VIOLATION', 409],
+  '23505': ['Unique value already exists', 'DUPLICATE_KEY', 409],
+  '23502': ['A required value is missing', 'REQUIRED_VALUE', 400],
+  '23514': ['A value violates the generated schema', 'INVALID_VALUE', 400],
+  '22P02': ['Invalid stored value', 'INVALID_VALUE', 400],
+  '22003': ['Numeric value is out of range', 'INVALID_VALUE', 400],
+  // Values PostgreSQL cannot store: longer than a sized column, a timestamp or date outside its range
+  // (including generated make_date calls), and text or JSON with NUL (U+0000) or a character the
+  // server encoding lacks. Index row size limits (54000) stay a DATABASE_ERROR.
+  '22001': ['Value is too long', 'INVALID_VALUE', 400],
+  '22008': ['Date or time value is out of range', 'INVALID_VALUE', 400],
+  '22021': ['Text contains a character the database cannot store', 'INVALID_VALUE', 400],
+  '22P05': ['Text contains a character the database cannot store', 'INVALID_VALUE', 400],
+  '40001': ['Concurrent write could not be completed', 'TRANSACTION_RETRY_EXCEEDED', 409],
+  '40P01': ['Concurrent write could not be completed', 'TRANSACTION_RETRY_EXCEEDED', 409],
+};
+
+/** Serialization failures and deadlocks: confirmed aborts that are safe to retry. */
+export const isRetryableDatabaseError = (error) => ['40001', '40P01'].includes(error?.code);
+
+// An error the server reported, as node-postgres exposes it: a five-character SQLSTATE and a severity.
+// An application error that only has a `code`, such as ECONNREFUSED or a domain code, is not one.
+export const isPostgresError = (error) => typeof error?.code === 'string' && /^[0-9A-Z]{5}$/.test(error.code) && typeof error.severity === 'string';
+
+/** Maps PostgreSQL errors (and exhausted retries) without SQL details; returns every other value unchanged. */
 export const normalizeDatabaseError = (error) => {
-  if (error instanceof SimfinityError || !error.code) return error;
-  const errors = {
-    '23503': ['Reference constraint violated', 'REFERENCE_CONSTRAINT_VIOLATION', 409],
-    '23505': ['Unique value already exists', 'DUPLICATE_KEY', 409],
-    '23502': ['A required value is missing', 'REQUIRED_VALUE', 400],
-    '23514': ['A value violates the generated schema', 'INVALID_VALUE', 400],
-    '22P02': ['Invalid stored value', 'INVALID_VALUE', 400],
-    '22003': ['Numeric value is out of range', 'INVALID_VALUE', 400],
-    '40001': ['Concurrent write could not be completed', 'TRANSACTION_RETRY_EXCEEDED', 409],
-    '40P01': ['Concurrent write could not be completed', 'TRANSACTION_RETRY_EXCEEDED', 409],
-  };
-  return new SimfinityError(...(errors[error.code] || ['Database operation failed', 'DATABASE_ERROR', 500]));
+  if (error instanceof SimfinityError || !(isPostgresError(error) || isRetryableDatabaseError(error))) return error;
+  const normalized = new SimfinityError(...(databaseErrors[error.code] || ['Database operation failed', 'DATABASE_ERROR', 500]));
+  // Kept for server logging, but non-enumerable as on a native Error, so serializing or spreading the
+  // client-facing error never copies the driver's detail, table or constraint.
+  Object.defineProperty(normalized, 'cause', { value: error, writable: true, configurable: true, enumerable: false });
+  normalized.getCause = () => normalized.cause;
+  return normalized;
 };
 
 /** pg's local Date formatting truncates historical offset seconds; use UTC per parameter. */

package/src/index.js

@@ -1,10 +1,10 @@
 import { createSQL } from '@simtlix/simfinity-sql';
 import { postgresPlugin } from './plugin.js';
+import { describeDatabase as describeSchema } from './schema/describe.js';
+import { compileDatabaseSchema as compileSchemaSQL } from './schema/ddl.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 {
   auth,
   buildErrorFormatter,
@@ -25,3 +25,14 @@ export const { configureQueryLimits, configureMutationLimits, configure, connect
 export const initializeDatabase = (poolOrOptions, description, options) => description
   ? initializeSchema(poolOrOptions, description, options)
   : defaultInstance.initializeDatabase(poolOrOptions);
+/**
+ * With arguments, the low-level describer, whose schema defaults to `public`; without, the configured
+ * default instance's description, in the schema given to configure().
+ */
+export const describeDatabase = (registrations, options) => registrations === undefined && options === undefined
+  ? defaultInstance.describeDatabase()
+  : describeSchema(registrations, options);
+/** With a description, the low-level DDL compiler; without, the configured default instance's DDL. */
+export const compileDatabaseSchema = (description) => description === undefined
+  ? defaultInstance.compileDatabaseSchema()
+  : compileSchemaSQL(description);

package/src/plugin.js

@@ -6,7 +6,7 @@ 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';
+import { castId, encodeScalar, decodeScalar, encodeParameter, isRetryableDatabaseError, normalizeDatabaseError } from './codecs.js';
 
 export const postgresPlugin = (options) => ({
   apiVersion: 1,
@@ -29,11 +29,22 @@ export const postgresPlugin = (options) => ({
     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'),
+    // PostgreSQL answers COMMIT with ROLLBACK, and no error, when a statement in the transaction failed
+    // and was caught; nothing was stored, so the operation must fail. A result without a command, from a
+    // pool wrapper that does not pass pg's through, resolves as before.
+    commit: async (client) => {
+      const result = await client.query('COMMIT');
+      if (result?.command !== 'ROLLBACK') return;
+      const error = new SimfinityError('Transaction was rolled back because one of its statements failed', 'DATABASE_ERROR', 500);
+      // The same shape as every other PostgreSQL DATABASE_ERROR: a non-enumerable cause, without SQL.
+      Object.defineProperty(error, 'cause', { value: new Error('COMMIT reported ROLLBACK'), writable: true, configurable: true, enumerable: false });
+      error.getCause = () => error.cause;
+      throw error;
+    },
     rollback: (client) => client.query('ROLLBACK'),
     // A release error makes pg-pool destroy a connection whose transaction may still be open.
     release: (client, error) => client.release(error),
-    isRetryable: (error) => ['40001', '40P01'].includes(error.code),
+    isRetryable: isRetryableDatabaseError,
     normalizeError: normalizeDatabaseError,
   },
 });

package/src/query/compiler.js

@@ -87,9 +87,12 @@ export const compileQuery = (models, database, plan, extra = null) => {
             const stored = alias();
             // Missing/null lists contribute a missing path, empty lists and null items do not.
             const condition = `${col(stored, '__owner_id')} = ${ownerId} AND ${state}${presence(stored)}`;
+            // UNION ALL pairs columns by position, and stored.* would follow the physical column order,
+            // which a migration that appends columns changes. Both branches list the description's columns.
+            const storedRow = owned.columns.map((column) => col(stored, column.name)).join(', ');
             const nullRow = owned.columns.map((column) => `NULL::${column.type} AS ${q(column.name)}`).join(', ');
             const noItems = usage === 'sort' ? ` OR NOT EXISTS (SELECT 1 FROM ${qualified(database.schema, owned.name)} empty_child WHERE empty_child.__owner_id = ${ownerId})` : '';
-            const source = `LATERAL (SELECT ${stored}.* FROM ${qualified(database.schema, owned.name)} ${stored} WHERE ${condition} UNION ALL SELECT ${nullRow} WHERE ${col(ownerAlias, owned.ownership.stateColumn)} IS DISTINCT FROM 'present'${noItems}) ${name}`;
+            const source = `LATERAL (SELECT ${storedRow} FROM ${qualified(database.schema, owned.name)} ${stored} WHERE ${condition} UNION ALL SELECT ${nullRow} WHERE ${col(ownerAlias, owned.ownership.stateColumn)} IS DISTINCT FROM 'present'${noItems}) ${name}`;
             const vector = context.vector
               ? { from: `${context.vector.from} CROSS JOIN ${source}`, where: context.vector.where }
               : { from: source, where: 'TRUE' };

package/src/schema/initialize.js

@@ -1,5 +1,5 @@
 import { SimfinityError } from '@simtlix/simfinity-core';
-import { identifier, qualified } from './sql.js';
+import { identifier, qualified, generatedName } from './sql.js';
 import { createTableSQL, createForeignKeySQL, createIndexSQL, createFunctionSQL, createTriggerSQL } from './ddl.js';
 
 const mismatch = (object, reason) => {
@@ -7,12 +7,24 @@ const mismatch = (object, reason) => {
 };
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 
+// literal() writes a value containing a backslash as E'' with doubled backslashes, while pg_get_expr,
+// read with standard_conforming_strings on, never renders E'' and doubles only quotes. Compare string
+// constants by value: decode either form and re-emit one standard form. The decoder inverts only the
+// escapes literal() emits (\\ and ''); it is not a general E'' decoder (\n or \x41 would be wrong).
+const canonicalString = (token) => {
+  const escape = token[0] !== '\'';
+  const body = token.slice(escape ? 2 : 1, -1);
+  const value = escape ? body.replace(/\\(.)|''/gs, (match, character) => character ?? '\'') : body.replaceAll('\'\'', '\'');
+  return `'${value.replaceAll('\'', '\'\'')}'`;
+};
+
 // Ignore renderer whitespace/optional quotes, keeping string contents and expression grouping.
-const normalizeExpression = (expression) => {
+export const normalizeExpression = (expression) => {
   if (expression == null) return null;
-  const tokens = expression.match(/'(?:[^']|'')*'|"(?:[^"]|"")*"|\s+|./gs) || [];
+  // An E-string is one token unless the E ends an identifier.
+  const tokens = expression.match(/(?<![\w$"])[Ee]'(?:\\.|''|[^'\\])*'|'(?:[^']|'')*'|"(?:[^"]|"")*"|\s+|./gs) || [];
   let value = tokens.map((token) => {
-    if (token.startsWith('\'')) return token;
+    if (token.length > 1 && /^[Ee]?'/.test(token)) return canonicalString(token);
     if (/^"[a-z_][a-z0-9_]*"$/.test(token)) return token.slice(1, -1);
     return /^\s+$/.test(token) ? '' : token;
   }).join('');
@@ -122,6 +134,16 @@ const validateIndex = (schema, table, index, actual) => {
   }
 };
 
+// Earlier versions generated a btree index on every [ID] list column. It caps each list at about 167
+// identifiers (btree row size) and no generated query uses it. Initialization keeps it, as it keeps
+// any extra non-unique index, but reports it when it carries the exact generated name and shape.
+const legacyListIndexes = (schema, table, actual) => table.columns
+  .filter((column) => column.type === 'uuid[]')
+  .map((column) => ({ column: column.name, name: generatedName(table.name, column.name, 'idx') }))
+  .filter(({ column, name }) => !table.indexes.some((item) => item.name === name) && actual.indexes.some((index) => index.name === name
+    && !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) => {
   for (const fn of description.functions || []) {
     const { rows } = await client.query(`SELECT p.oid, pg_get_function_identity_arguments(p.oid) AS arguments,
@@ -205,6 +227,7 @@ export const initializeDatabase = async (pool, description, { mode = 'create' }
   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 = [];
+  const legacy = [];
   let rollbackError;
   try {
     await client.query(mode === 'validate' ? 'BEGIN READ ONLY' : 'BEGIN');
@@ -258,10 +281,16 @@ export const initializeDatabase = async (pool, description, { mode = 'create' }
       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, 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(', ')}. `
+        + 'Each limits its list to about 167 identifiers and no generated query uses it. Once every process that uses this schema runs this version, drop them: '
+        + `${legacy.map((name) => `DROP INDEX CONCURRENTLY IF EXISTS ${name};`).join(' ')} See the upgrade notes at https://simtlix.github.io/simfinity.js/resources/compatibility.html`);
+    }
     return { mode, created };
   } catch (error) {
     try { await client.query('ROLLBACK'); } catch (failure) { rollbackError = failure; }

package/types/index.d.ts

@@ -109,19 +109,37 @@ export interface DatabaseDescription {
 }
 export interface DatabasePool {
   connect(): Promise<{
-    query(sql: string, values?: unknown[]): Promise<{ rows: any[]; rowCount: number | null }>;
+    query(sql: string, values?: unknown[]): Promise<{
+      rows: any[];
+      rowCount: number | null;
+      /** Command tag reported by pg, such as `COMMIT`. Wrappers should pass pg's `command` through, so that a COMMIT that PostgreSQL turned into ROLLBACK is detected. */
+      command?: string;
+    }>;
     /** An error means the connection must be destroyed instead of reused. */
     release(error?: unknown): void;
   }>;
 }
+/**
+ * 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;
+/** Describes the default module instance in its configured schema, after configure/connect/createSchema. */
+export function describeDatabase(): DatabaseDescription;
 /** Accepts a trusted description produced by describeDatabase. */
 export function compileDatabaseSchema(description: DatabaseDescription): string[];
+/** DDL of the default module instance in its configured schema, after configure/connect/createSchema. */
+export function compileDatabaseSchema(): string[];
 /** Borrows one pool client; owns its transaction, not the pool lifecycle. PostgreSQL >=15. */
 export function initializeDatabase(pool: DatabasePool, description: DatabaseDescription, options?: { mode?: 'create' | 'validate' }): Promise<{ mode: 'create' | 'validate'; created: string[] }>;
 
 export interface DatabaseQueryable {
-  query(sql: string, values?: any[]): Promise<{ rows: any[]; rowCount: number | null }>;
+  query(sql: string, values?: any[]): Promise<{
+    rows: any[];
+    rowCount: number | null;
+    /** Command tag reported by pg, such as `COMMIT`. Wrappers should pass pg's `command` through, so that a COMMIT that PostgreSQL turned into ROLLBACK is detected. */
+    command?: string;
+  }>;
 }
 export interface PostgresPool extends DatabasePool, DatabaseQueryable {}
 export interface PostgresSession extends DatabaseQueryable {
@@ -156,7 +174,14 @@ export interface PostgresRuntime extends Runtime<PostgresModel, PostgresSession>
   /** Bind pool/schema once, before createSchema. The caller owns the pool lifetime. */
   configure(options: PostgresConfiguration): void;
   describeDatabase(): DatabaseDescription;
-  /** Must be awaited before operations execute. Does not synchronize incompatible schemas. */
+  /** Physical DDL for this instance's description and schema, for review or export; initializeDatabase does not run it. */
+  compileDatabaseSchema(): string[];
+  /**
+   * Must be awaited before operations execute. Does not synchronize incompatible schemas. A request rejected before
+   * storage is touched, such as an unknown mode (INVALID_INITIALIZATION_MODE, 400) or, on a validation-only runtime,
+   * a non-empty mode other than validate (DATABASE_CREATION_DISABLED, 409), keeps the current readiness; a ready runtime keeps serving while it is initialized again, and any failure of the latest
+   * initialization makes it unavailable.
+   */
   initializeDatabase(options?: InitializationOptions): Promise<InitializationResult>;
   withTransaction<T>(session: PostgresSession | null | undefined, callback: (session: PostgresSession) => Promise<T> | T): Promise<T>;
 }
@@ -165,7 +190,12 @@ export function postgresPlugin(options?: PostgresConfiguration): SQLPlugin<
   PostgresConfiguration,
   DatabaseQueryable,
   DatabaseDescription,
-  { rows: Record<string, unknown>[]; rowCount: number | null }
+  {
+    rows: Record<string, unknown>[];
+    rowCount: number | null;
+    /** Command tag reported by pg, such as `COMMIT`. Wrappers should pass pg's `command` through, so that a COMMIT that PostgreSQL turned into ROLLBACK is detected. */
+    command?: string;
+  }
 >;
 export function createPostgres(options?: PostgresConfiguration): PostgresRuntime;
 export const configure: PostgresRuntime['configure'];

package/src/adapter.js

@@ -1,4 +0,0 @@
-import { createSQLAdapter } from '@simtlix/simfinity-sql/internal/adapter';
-import { postgresPlugin } from './plugin.js';
-
-export const createPostgresAdapter = (options) => createSQLAdapter(postgresPlugin(options));

package/src/records.js

@@ -1,4 +0,0 @@
-import { createRecordStore as createSQLRecordStore } from '@simtlix/simfinity-sql/internal/records';
-import { postgresPlugin } from './plugin.js';
-
-export const createRecordStore = (models, database, query) => createSQLRecordStore(models, database, (statement, session) => query(statement.text, statement.values, session), postgresPlugin());

package/src/transactions.js

@@ -1,4 +0,0 @@
-import { createTransactions as createSQLTransactions } from '@simtlix/simfinity-sql/internal/transactions';
-import { postgresPlugin } from './plugin.js';
-
-export const createTransactions = (getPool, assertReady) => createSQLTransactions(() => ({ pool: getPool() }), assertReady, postgresPlugin());