@stonyx/orm 0.3.2-alpha.4 → 0.3.2-alpha.41

package/src/dynamodb/operation-builder.ts

@@ -0,0 +1,202 @@
+/**
+ * DynamoDB operation parameter builders.
+ *
+ * Each function returns a plain-object "params" bag that can be passed
+ * directly to the corresponding DocumentClient command
+ * (PutCommand, GetCommand, UpdateCommand, DeleteCommand, ScanCommand, QueryCommand).
+ *
+ * All functions are pure — no SDK imports here; the caller wraps params
+ * in the appropriate Command class.
+ */
+
+export interface PutItemParams {
+  TableName: string;
+  Item: Record<string, unknown>;
+  ConditionExpression?: string;
+}
+
+export interface GetItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+}
+
+export interface UpdateItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+  UpdateExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+  ExpressionAttributeValues: Record<string, unknown>;
+  ReturnValues: string;
+}
+
+export interface DeleteItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+}
+
+export interface ScanParams {
+  TableName: string;
+  FilterExpression?: string;
+  ExpressionAttributeNames?: Record<string, string>;
+  ExpressionAttributeValues?: Record<string, unknown>;
+  ExclusiveStartKey?: Record<string, unknown>;
+}
+
+export interface QueryParams {
+  TableName: string;
+  IndexName: string;
+  KeyConditionExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+  ExpressionAttributeValues: Record<string, unknown>;
+  ExclusiveStartKey?: Record<string, unknown>;
+}
+
+/**
+ * PutItem — optionally with a condition expression.
+ *
+ * Pass conditionExpression = 'attribute_not_exists(id)' to enforce uniqueness.
+ */
+export function buildPutItem(
+  tableName: string,
+  item: Record<string, unknown>,
+  conditionExpression?: string,
+): PutItemParams {
+  const params: PutItemParams = { TableName: tableName, Item: item };
+  if (conditionExpression) params.ConditionExpression = conditionExpression;
+  return params;
+}
+
+/**
+ * GetItem by primary key.
+ */
+export function buildGetItem(
+  tableName: string,
+  key: Record<string, unknown>,
+): GetItemParams {
+  return { TableName: tableName, Key: key };
+}
+
+/**
+ * UpdateItem with a SET expression built from the `updates` object.
+ * Only the supplied attributes are updated (diff-based call site).
+ */
+export function buildUpdateItem(
+  tableName: string,
+  key: Record<string, unknown>,
+  updates: Record<string, unknown>,
+): UpdateItemParams {
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const setClauses: string[] = [];
+
+  for (const [attr, val] of Object.entries(updates)) {
+    const nameAlias = `#${attr}`;
+    const valAlias = `:${attr}`;
+    names[nameAlias] = attr;
+    values[valAlias] = val;
+    setClauses.push(`${nameAlias} = ${valAlias}`);
+  }
+
+  return {
+    TableName: tableName,
+    Key: key,
+    UpdateExpression: `SET ${setClauses.join(', ')}`,
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values,
+    ReturnValues: 'NONE',
+  };
+}
+
+/**
+ * DeleteItem by primary key.
+ */
+export function buildDeleteItem(
+  tableName: string,
+  key: Record<string, unknown>,
+): DeleteItemParams {
+  return { TableName: tableName, Key: key };
+}
+
+/**
+ * ScanCommand params.
+ * If conditions are supplied they are rendered as a FilterExpression using AND.
+ */
+export function buildScan(
+  tableName: string,
+  conditions?: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): ScanParams {
+  const params: ScanParams = { TableName: tableName };
+
+  if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
+
+  if (conditions && Object.keys(conditions).length > 0) {
+    const validEntries = Object.entries(conditions).filter(
+      ([, val]) => val !== undefined && val !== null,
+    );
+
+    if (validEntries.length > 0) {
+      const names: Record<string, string> = {};
+      const values: Record<string, unknown> = {};
+      const clauses: string[] = [];
+
+      for (const [attr, val] of validEntries) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        clauses.push(`${nameAlias} = ${valAlias}`);
+      }
+
+      params.FilterExpression = clauses.join(' AND ');
+      params.ExpressionAttributeNames = names;
+      params.ExpressionAttributeValues = values;
+    }
+  }
+
+  return params;
+}
+
+/**
+ * QueryCommand params for a GSI.
+ * keyConditions must be in the form { attrName: value } and will be rendered
+ * as equality expressions joined by AND.
+ */
+export function buildQuery(
+  tableName: string,
+  indexName: string,
+  keyConditions: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): QueryParams {
+  const validEntries = Object.entries(keyConditions).filter(
+    ([, val]) => val !== undefined && val !== null,
+  );
+
+  if (validEntries.length === 0) {
+    throw new Error('buildQuery: all keyCondition values are undefined/null');
+  }
+
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const clauses: string[] = [];
+
+  for (const [attr, val] of validEntries) {
+    const nameAlias = `#${attr}`;
+    const valAlias = `:${attr}`;
+    names[nameAlias] = attr;
+    values[valAlias] = val;
+    clauses.push(`${nameAlias} = ${valAlias}`);
+  }
+
+  const params: QueryParams = {
+    TableName: tableName,
+    IndexName: indexName,
+    KeyConditionExpression: clauses.join(' AND '),
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values,
+  };
+
+  if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
+
+  return params;
+}

package/src/dynamodb/type-map.ts

@@ -0,0 +1,54 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+
+export type DynamoScalarType = 'S' | 'N' | 'BOOL';
+
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+const typeMap: Record<string, DynamoScalarType> = {
+  string: 'S',
+  number: 'N',
+  float: 'N',
+  boolean: 'BOOL',
+  date: 'S',
+  timestamp: 'N',
+  passthrough: 'S',
+  trim: 'S',
+  uppercase: 'S',
+  ceil: 'N',
+  floor: 'N',
+  round: 'N',
+};
+
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export function getDynamoType(attrType: string): DynamoScalarType {
+  return typeMap[attrType] ?? 'S';
+}
+
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export function getDynamoKeyType(attrType: string): 'S' | 'N' {
+  const t = getDynamoType(attrType);
+  return t === 'N' ? 'N' : 'S';
+}
+
+export default typeMap;

package/src/index.ts

@@ -26,6 +26,7 @@ import { count, avg, sum, min, max } from './aggregates.js';
 
 export { default } from './main.js';
 export { store, relationships } from './main.js';
+export type { PersistErrorDetail } from './main.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers

package/src/main.ts

@@ -49,6 +49,13 @@ const defaultOptions: OrmOptions = {
   dbType: 'json'
 }
 
+export interface PersistErrorDetail {
+  operation: 'create' | 'update' | 'delete';
+  modelName: string;
+  recordId: unknown;
+  error: Error;
+}
+
 export default class Orm {
   static initialized: boolean = false;
   static relationships: Map<string, Map<string, unknown>> = new Map();
@@ -65,6 +72,8 @@ export default class Orm {
   sqlDb?: SqlDb;
   db?: OrmDB | SqlDb;
 
+  private _persistErrorHandler: ((detail: PersistErrorDetail) => void) | null = null;
+
   constructor(options: OrmOptions = {}) {
     if (Orm.instance) return Orm.instance;
 
@@ -81,6 +90,11 @@ export default class Orm {
   }
 
   async init(): Promise<void> {
+    // Self-register so log.db works even when @stonyx/orm is in the
+    // consumer's `dependencies` (stonyx loader only merges devDependencies).
+    const { logColor = 'white', logMethod = 'db' } = config.orm;
+    log.defineType(logMethod, logColor);
+
     const { paths, restServer } = config.orm;
 
     const promises: Promise<unknown>[] = ['Model', 'Serializer', 'Transform'].map(type => {
@@ -150,6 +164,11 @@ export default class Orm {
       this.sqlDb = new MysqlDB() as SqlDb;
       this.db = this.sqlDb;
       promises.push(this.sqlDb.init());
+    } else if (config.orm.dynamodb) {
+      const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+      this.sqlDb = new DynamoDBDB() as SqlDb;
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
     } else if (this.options.dbType !== 'none') {
       const db = new DB();
       this.db = db;
@@ -214,6 +233,32 @@ export default class Orm {
     return !!this.views[`${modelClassPrefix}View`];
   }
 
+  /**
+   * Register a callback to be invoked when a fire-and-forget SQL persist fails.
+   * Without a handler, persist errors are logged via log.error (backwards-compatible).
+   */
+  onPersistError(handler: ((detail: PersistErrorDetail) => void) | null): void {
+    this._persistErrorHandler = handler;
+  }
+
+  /**
+   * Emit a persist error to the registered handler, or fall back to log.error.
+   */
+  emitPersistError(detail: PersistErrorDetail): void {
+    const fallbackLog = () => log.error?.(`[ORM] Failed to persist ${detail.operation} for ${detail.modelName}:${String(detail.recordId)}: ${detail.error.message}`);
+
+    if (this._persistErrorHandler) {
+      try {
+        this._persistErrorHandler(detail);
+      } catch (handlerError) {
+        fallbackLog();
+        log.error?.(`[ORM] onPersistError handler threw: ${handlerError instanceof Error ? handlerError.message : String(handlerError)}`);
+      }
+    } else {
+      fallbackLog();
+    }
+  }
+
   // Queue warnings to avoid the same error from being logged in the same iteration
   warn(message: string): void {
     this.warnings.add(message);

package/src/manage-record.ts

@@ -3,7 +3,6 @@ import OrmRecord from './record.js';
 import { getGlobalRegistry, getPendingRegistry, getPendingBelongsToRegistry, getBelongsToRegistry, getHasManyRegistry } from './relationships.js';
 import type Serializer from './serializer.js';
 import { isOrmRecord } from './utils.js';
-import log from 'stonyx/log';
 
 interface CreateRecordOptions {
   isDbRecord?: boolean;
@@ -80,6 +79,28 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
     pendingHasMany.splice(0);
   }
 
+  // FK-based inverse hasMany wiring — when a child record is created with a
+  // foreign-key field (e.g. `owner: 'owner-1'` on an animal), find any parent
+  // whose hasMany registry targets this model and push the child into the
+  // parent's shared array.  This covers edge cases where the child is created
+  // in a separate async frame without a belongsTo handler firing.
+  const hasManyReg = getHasManyRegistry();
+  if (hasManyReg) {
+    for (const [parentModelName, targetMap] of hasManyReg) {
+      const childArrayMap = targetMap.get(modelName);
+      if (!childArrayMap) continue;
+
+      // Check if rawData contains a FK field matching the parent model name
+      const fkValue = rawData[parentModelName];
+      if (fkValue === undefined || fkValue === null) continue;
+
+      const parentArray = childArrayMap.get(fkValue);
+      if (parentArray && !parentArray.includes(record)) {
+        parentArray.push(record);
+      }
+    }
+  }
+
   // Fulfill pending belongsTo relationships
   const pendingBelongsToQueue = getPendingBelongsToRegistry();
   const pendingBelongsToRaw = pendingBelongsToQueue.get(modelName)?.get(record.id);
@@ -87,7 +108,7 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
 
   if (pendingBelongsTo) {
     const belongsToReg = getBelongsToRegistry();
-    const hasManyReg = getHasManyRegistry();
+    const pendingHasManyReg = getHasManyRegistry();
 
     for (const { sourceRecord, sourceModelName, relationshipKey, relationshipId } of pendingBelongsTo) {
       // Update the belongsTo relationship on the source record
@@ -104,7 +125,7 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
       }
 
       // Wire inverse hasMany if it exists
-      const inverseHasMany = hasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
+      const inverseHasMany = pendingHasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
 
       if (inverseHasMany && !inverseHasMany.includes(sourceRecord)) {
         inverseHasMany.push(sourceRecord);
@@ -118,10 +139,25 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
   // Auto-persist to SQL — skip for DB loads (isDbRecord) and relationship resolution (_relationshipKey)
   const shouldPersist = orm?.sqlDb && !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
   if (shouldPersist) {
+    // Capture ID before persist — SQL adapters re-key pending IDs to real DB IDs,
+    // but relationship registries were keyed with this original ID
+    const registryId = record.id;
     const response = { data: { id: record.id } };
-    orm!.sqlDb!.persist('create', modelName, { rawData }, response).catch((err: unknown) => {
-      log.error?.(`[ORM] Failed to persist create for ${modelName}:${String(record.id)}: ${err instanceof Error ? err.message : String(err)}`);
-    });
+    orm!.sqlDb!.persist('create', modelName, { rawData }, response)
+      .catch((err: unknown) => {
+        orm!.emitPersistError({
+          operation: 'create',
+          modelName,
+          recordId: record.id,
+          error: err instanceof Error ? err : new Error(String(err)),
+        });
+      })
+      .finally(() => {
+        // Evict non-memory records after persist to prevent unbounded heap growth (stonyx#81)
+        if (store._memoryResolver && !store._memoryResolver(modelName)) {
+          store.evictRecord(modelName, record.id, registryId);
+        }
+      });
   }
 
   return record;
@@ -148,7 +184,12 @@ export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: C
   const shouldPersist = orm?.sqlDb && !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
   if (shouldPersist && modelName) {
     orm!.sqlDb!.persist('update', modelName, { record, oldState }, {}).catch((err: unknown) => {
-      log.error?.(`[ORM] Failed to persist update for ${modelName}:${String(record.id)}: ${err instanceof Error ? err.message : String(err)}`);
+      orm!.emitPersistError({
+        operation: 'update',
+        modelName,
+        recordId: record.id,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
     });
   }
 }

package/src/mysql/connection.ts

@@ -9,6 +9,7 @@ interface MysqlConfig {
   connectionLimit?: number;
   migrationsTable?: string;
   migrationsDir?: string;
+  autoMigrate?: boolean;
 }
 
 let pool: Pool | null = null;

package/src/mysql/mysql-db.ts

@@ -84,6 +84,15 @@ export default class MysqlDB {
   pool!: Pool | null;
   mysqlConfig!: MysqlConfig;
 
+  /**
+   * Promise-chain mutex for write serialization (#156).
+   * All persist() calls chain through this single queue so concurrent
+   * fire-and-forget writes never produce parallel InnoDB transactions
+   * on FK-linked rows (which cause deadlocks).
+   * Reads are NOT affected — only persist() serializes.
+   */
+  private _writeQueue: Promise<void> = Promise.resolve();
+
   constructor(deps: Partial<MysqlDBDeps> = {}) {
     if (MysqlDB.instance) return MysqlDB.instance;
     MysqlDB.instance = this;
@@ -118,7 +127,15 @@ export default class MysqlDB {
     if (pending.length > 0) {
       this.deps.log.db?.(`${pending.length} pending migration(s) found.`);
 
-      const shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+      let shouldApply: boolean;
+      if (this.mysqlConfig.autoMigrate === true) {
+        shouldApply = true;
+      } else if (this.mysqlConfig.autoMigrate === false) {
+        shouldApply = false;
+        this.deps.log.warn?.(`autoMigrate is false — skipping ${pending.length} pending migration(s).`);
+      } else {
+        shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+      }
 
       if (shouldApply) {
         for (const filename of pending) {
@@ -139,9 +156,17 @@ export default class MysqlDB {
       const modelCount = Object.keys(schemas).length;
 
       if (modelCount > 0) {
-        const shouldGenerate = await this.deps.confirm(
-          `No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`
-        );
+        let shouldGenerate: boolean;
+        if (this.mysqlConfig.autoMigrate === true) {
+          shouldGenerate = true;
+        } else if (this.mysqlConfig.autoMigrate === false) {
+          shouldGenerate = false;
+          this.deps.log.warn?.(`autoMigrate is false — skipping initial migration generation for ${modelCount} model(s).`);
+        } else {
+          shouldGenerate = await this.deps.confirm(
+            `No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`
+          );
+        }
 
         if (shouldGenerate) {
           const { generateMigration } = await import('./migration-generator.js');
@@ -398,14 +423,21 @@ export default class MysqlDB {
     const Orm = (await import('@stonyx/orm')).default;
     if ((Orm as unknown as { instance?: { isView?: (name: string) => boolean } }).instance?.isView?.(modelName)) return;
 
-    switch (operation) {
-      case 'create':
-        return this._persistCreate(modelName, context, response);
-      case 'update':
-        return this._persistUpdate(modelName, context, response);
-      case 'delete':
-        return this._persistDelete(modelName, context);
-    }
+    const work = async () => {
+      switch (operation) {
+        case 'create':
+          return this._persistCreate(modelName, context, response);
+        case 'update':
+          return this._persistUpdate(modelName, context, response);
+        case 'delete':
+          return this._persistDelete(modelName, context);
+      }
+    };
+
+    // Chain through the write queue — .then(work, work) ensures the queue
+    // advances even when a previous persist rejects (#156).
+    this._writeQueue = this._writeQueue.then(work, work);
+    return this._writeQueue;
   }
 
   private async _persistCreate(modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {

package/src/orm-request.ts

@@ -376,7 +376,7 @@ export default class OrmRequest extends Request {
     };
 
     const deleteHandler: HandlerFn = ({ params }) => {
-      store.remove(model, getId(params));
+      store.remove(model, getId(params), { _skipAutoPersist: true });
       return 204;
     };
 
@@ -443,9 +443,14 @@ export default class OrmRequest extends Request {
       // Execute main handler
       const response = await handler(request, state);
 
-      // Persist to SQL database for create/update (delete is handled by store.remove auto-persist)
+      // Set context.record for update BEFORE persist so SQL drivers can read it
+      if (operation === 'update' && (response as JsonApiResponse)?.data) {
+        context.record = store.get(this.model, getId(request.params));
+      }
+
+      // Persist to SQL database for all write operations (create/update/delete)
       const sqlDb = Orm.instance.sqlDb;
-      if (sqlDb && (operation === 'create' || operation === 'update')) {
+      if (sqlDb && WRITE_OPERATIONS.has(operation)) {
         await sqlDb.persist(operation, this.model, context, response);
       }
 
@@ -461,8 +466,6 @@ export default class OrmRequest extends Request {
         const responseData = (response as { data: { id: string | number } }).data;
         const recordId = isNaN(responseData.id as unknown as number) ? responseData.id : parseInt(responseData.id as string);
         context.record = store.get(this.model, recordId);
-      } else if (operation === 'update' && (response as JsonApiResponse)?.data) {
-        context.record = store.get(this.model, getId(request.params));
       } else if (operation === 'delete') {
         // For delete, the record may no longer exist, but we have oldState
         context.recordId = getId(request.params);

package/src/postgres/connection.ts

@@ -8,6 +8,7 @@ interface PgConfig {
   password: string;
   database: string;
   connectionLimit: number;
+  [key: string]: unknown;
 }
 
 let pool: PgPool | null = null;
@@ -20,15 +21,18 @@ export async function getPool(pgConfig: PgConfig, extensions: string[] = ['vecto
 
   const { default: pg } = await import('pg');
 
+  const { host, port, user, password, database, connectionLimit, migrationsDir, migrationsTable, autoMigrate, ...poolOpts } = pgConfig;
+
   pool = new pg.Pool({
-    host: pgConfig.host,
-    port: pgConfig.port,
-    user: pgConfig.user,
-    password: pgConfig.password,
-    database: pgConfig.database,
-    max: pgConfig.connectionLimit,
+    host,
+    port,
+    user,
+    password,
+    database,
+    max: connectionLimit,
     idleTimeoutMillis: 30000,
     connectionTimeoutMillis: 10000,
+    ...poolOpts,
   });
 
   // Enable requested PostgreSQL extensions

package/src/postgres/postgres-db.ts

@@ -90,6 +90,15 @@ export default class PostgresDB {
   pool!: Pool | null;
   pgConfig!: Record<string, unknown>;
 
+  /**
+   * Promise-chain mutex for write serialization (#156).
+   * All persist() calls chain through this single queue so concurrent
+   * fire-and-forget writes never produce parallel transactions
+   * on FK-linked rows (which cause deadlocks).
+   * Reads are NOT affected — only persist() serializes.
+   */
+  private _writeQueue: Promise<void> = Promise.resolve();
+
   constructor(deps: Partial<PostgresDeps> = {}) {
     const Ctor = this.constructor as typeof PostgresDB;
     if (Ctor.instance) return Ctor.instance;
@@ -125,7 +134,15 @@ export default class PostgresDB {
     if (pending.length > 0) {
       this.deps.log.db?.(`${pending.length} pending migration(s) found.`);
 
-      const shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+      let shouldApply: boolean;
+      if (this.pgConfig.autoMigrate === true) {
+        shouldApply = true;
+      } else if (this.pgConfig.autoMigrate === false) {
+        shouldApply = false;
+        this.deps.log.warn?.(`autoMigrate is false — skipping ${pending.length} pending migration(s).`);
+      } else {
+        shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+      }
 
       if (shouldApply) {
         for (const filename of pending) {
@@ -146,9 +163,17 @@ export default class PostgresDB {
       const modelCount = Object.keys(schemas).length;
 
       if (modelCount > 0) {
-        const shouldGenerate = await this.deps.confirm(
-          `No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`
-        );
+        let shouldGenerate: boolean;
+        if (this.pgConfig.autoMigrate === true) {
+          shouldGenerate = true;
+        } else if (this.pgConfig.autoMigrate === false) {
+          shouldGenerate = false;
+          this.deps.log.warn?.(`autoMigrate is false — skipping initial migration generation for ${modelCount} model(s).`);
+        } else {
+          shouldGenerate = await this.deps.confirm(
+            `No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`
+          );
+        }
 
         if (shouldGenerate) {
           const { generateMigration } = await import('./migration-generator.js');
@@ -468,14 +493,21 @@ export default class PostgresDB {
     const Orm = (await import('@stonyx/orm')).default;
     if ((Orm.instance as { isView?: (name: string) => boolean })?.isView?.(modelName)) return;
 
-    switch (operation) {
-      case 'create':
-        return this._persistCreate(modelName, context, response);
-      case 'update':
-        return this._persistUpdate(modelName, context, response);
-      case 'delete':
-        return this._persistDelete(modelName, context);
-    }
+    const work = async () => {
+      switch (operation) {
+        case 'create':
+          return this._persistCreate(modelName, context, response);
+        case 'update':
+          return this._persistUpdate(modelName, context, response);
+        case 'delete':
+          return this._persistDelete(modelName, context);
+      }
+    };
+
+    // Chain through the write queue — .then(work, work) ensures the queue
+    // advances even when a previous persist rejects (#156).
+    this._writeQueue = this._writeQueue.then(work, work);
+    return this._writeQueue;
   }
 
   private async _persistCreate(modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {