@stonyx/orm 0.3.2-beta.327 → 0.3.2-beta.329

package/dist/mysql/query-builder.d.ts

@@ -4,6 +4,7 @@ interface QueryResult {
 }
 export declare function validateIdentifier(name: string, context?: string): string;
 export declare function buildInsert(table: string, data: Record<string, unknown>): QueryResult;
+export declare function buildInsertMany(table: string, rows: Record<string, unknown>[]): QueryResult;
 export declare function buildUpdate(table: string, id: unknown, data: Record<string, unknown>): QueryResult;
 export declare function buildDelete(table: string, id: unknown): QueryResult;
 export declare function buildSelect(table: string, conditions?: Record<string, unknown>): QueryResult;

package/dist/mysql/query-builder.js

@@ -14,6 +14,23 @@ export function buildInsert(table, data) {
     const sql = `INSERT INTO \`${table}\` (${keys.map(k => `\`${k}\``).join(', ')}) VALUES (${placeholders.join(', ')})`;
     return { sql, values };
 }
+export function buildInsertMany(table, rows) {
+    validateIdentifier(table, 'table name');
+    const columns = [...new Set(rows.flatMap(row => Object.keys(row)))];
+    columns.forEach(column => validateIdentifier(column, 'column name'));
+    const values = [];
+    const tuples = rows.map(row => {
+        const cells = columns.map(column => {
+            if (!Object.hasOwn(row, column))
+                return 'DEFAULT';
+            values.push(row[column]);
+            return '?';
+        });
+        return `(${cells.join(', ')})`;
+    });
+    const sql = `INSERT INTO \`${table}\` (${columns.map(column => `\`${column}\``).join(', ')}) VALUES ${tuples.join(', ')}`;
+    return { sql, values };
+}
 export function buildUpdate(table, id, data) {
     validateIdentifier(table, 'table name');
     const keys = Object.keys(data);

package/dist/postgres/postgres-db.d.ts

@@ -85,6 +85,7 @@ export default class PostgresDB {
     deps: PostgresDeps;
     pool: Pool | null;
     pgConfig: Record<string, unknown>;
+    readonly persistResolvesAfterWrite = true;
     private _queuedWrites;
     private _inFlightWrites;
     private _drainingWrites;

package/dist/postgres/postgres-db.js

@@ -48,6 +48,7 @@ export default class PostgresDB {
     deps;
     pool;
     pgConfig;
+    persistResolvesAfterWrite = true;
     _queuedWrites = [];
     _inFlightWrites = new Set();
     _drainingWrites = null;

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-beta.327",
+  "version": "0.3.2-beta.329",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/index.ts

@@ -21,14 +21,14 @@ import Serializer from './serializer.js';
 import attr from './attr.js';
 import belongsTo from './belongs-to.js';
 import hasMany from './has-many.js';
-import { createRecord, updateRecord } from './manage-record.js';
+import { createRecord, updateRecord, createRecordAndPersist, updateRecordAndPersist } from './manage-record.js';
 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 { attr, belongsTo, hasMany, createRecord, updateRecord, createRecordAndPersist, updateRecordAndPersist };
 export { count, avg, sum, min, max }; // aggregate helpers
 export { default as normalizeRecordId } from './normalize-record-id.js'; // canonical URL-id -> record-id resolution (#270)
 export type { OrmRequest$ as OrmAccessRequest } from './orm-request.js'; // the request access() is handed, incl. recordId (#270)

package/src/main.ts

@@ -34,6 +34,7 @@ export interface SqlDb {
   startup(): Promise<void>;
   shutdown(): Promise<void>;
   persist(operation: string, model: string, context: unknown, response: unknown): Promise<void>;
+  persistResolvesAfterWrite?: boolean;
   findRecord(modelName: string, id: unknown): Promise<unknown>;
   findAll(modelName: string, conditions?: Record<string, unknown>): Promise<unknown[]>;
 }

package/src/manage-record.ts

@@ -28,7 +28,73 @@ const defaultOptions: CreateRecordOptions = {
 
 let pendingIdCounter = 0;
 
+interface RecordWrite<Result> {
+  result: Result;
+  written: Promise<void>;
+}
+
+type AwaitedOperation = 'create' | 'update';
+
+const writeNotRequested = Promise.resolve();
+
+function ignoreReportedFailure(): void {}
+
+function persistRequested(options: CreateRecordOptions, userOptions: CreateRecordOptions): boolean {
+  return !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
+}
+
+function reportPersistFailure(operation: AwaitedOperation, modelName: string, recordId: unknown, failure: unknown): Error {
+  const error = failure instanceof Error ? failure : new Error(String(failure));
+  Orm.instance.emitPersistError({ operation, modelName, recordId, error });
+  return error;
+}
+
 export function createRecord(modelName: string, rawData: { [key: string]: unknown } = {}, userOptions: CreateRecordOptions = {}): OrmRecord {
+  const { result: record, written } = createRecordWrite(modelName, rawData, userOptions);
+  written.catch(ignoreReportedFailure);
+  return record;
+}
+
+export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions = {}): void {
+  updateRecordWrite(record, rawData, userOptions).written.catch(ignoreReportedFailure);
+}
+
+export async function createRecordAndPersist(modelName: string, rawData: { [key: string]: unknown } = {}, userOptions: CreateRecordOptions = {}): Promise<OrmRecord> {
+  assertWriteCanBeAwaited();
+  const { result: record, written } = createRecordWrite(modelName, rawData, userOptions);
+  await written;
+  await saveJsonDatabase('create', modelName, record.id, { ...defaultOptions, ...userOptions }, userOptions);
+  return record;
+}
+
+export async function updateRecordAndPersist(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions = {}): Promise<void> {
+  assertWriteCanBeAwaited();
+  await updateRecordWrite(record, rawData, userOptions).written;
+  await saveJsonDatabase('update', record?.__model?.__name ?? '', record.id, { ...defaultOptions, ...userOptions }, userOptions);
+}
+
+function assertWriteCanBeAwaited(): void {
+  const sqlDb = Orm.instance?.sqlDb as { persistResolvesAfterWrite?: boolean } | undefined;
+  if (sqlDb && sqlDb.persistResolvesAfterWrite !== true) {
+    throw new Error('The configured database adapter cannot confirm a write has landed, so createRecordAndPersist/updateRecordAndPersist are unavailable for it (DynamoDB: abofs/stonyx-orm#299)');
+  }
+}
+
+async function saveJsonDatabase(operation: AwaitedOperation, modelName: string, recordId: unknown, options: CreateRecordOptions, userOptions: CreateRecordOptions): Promise<void> {
+  const orm = Orm.instance;
+  if (orm.sqlDb || !persistRequested(options, userOptions)) return;
+
+  const jsonDatabase = orm.db as { save?: () => Promise<void> } | undefined;
+  if (!jsonDatabase?.save) return;
+
+  try {
+    await jsonDatabase.save();
+  } catch (failure) {
+    throw reportPersistFailure(operation, modelName, recordId, failure);
+  }
+}
+
+function createRecordWrite(modelName: string, rawData: { [key: string]: unknown }, userOptions: CreateRecordOptions): RecordWrite<OrmRecord> {
   const orm = Orm.instance;
   const { initialized } = Orm;
   const options = { ...defaultOptions, ...userOptions };
@@ -50,9 +116,7 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
   const existingRecord = modelStore.get(rawData.id as number | string);
 
   if (existingRecord instanceof OrmRecord) {
-    // Update the existing record with new data so the last entry wins
-    updateRecord(existingRecord, rawData, { ...options, update: true });
-    return existingRecord;
+    return { result: existingRecord, written: updateRecordWrite(existingRecord, rawData, { ...options, update: true }).written };
   }
 
   const recordClasses = orm.getRecordClasses(modelName);
@@ -136,37 +200,26 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
     pendingBelongsTo.length = 0;
   }
 
-  // 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) => {
-        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);
-        }
-      });
-  }
+  if (!orm?.sqlDb || !persistRequested(options, userOptions)) return { result: record, written: writeNotRequested };
+
+  const registryIdBeforePersist = record.id;
+  const response = { data: { id: record.id } };
+  const written = orm.sqlDb.persist('create', modelName, { rawData }, response)
+    .catch((failure: unknown) => {
+      throw reportPersistFailure('create', modelName, record.id, failure);
+    })
+    .finally(() => {
+      if (store._memoryResolver && !store._memoryResolver(modelName)) {
+        store.evictRecord(modelName, record.id, registryIdBeforePersist);
+      }
+    });
 
-  return record;
+  return { result: record, written };
 }
 
-export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions = {}): void {
+function updateRecordWrite(record: OrmRecord, rawData: unknown, userOptions: CreateRecordOptions): RecordWrite<void> {
   if (!rawData) throw new Error('rawData must be passed in to updateRecord call');
 
-  // Guard: read-only views cannot be updated
   const modelName = record?.__model?.__name;
   if (modelName && Orm.instance?.isView?.(modelName)) {
     throw new Error(`Cannot update records for read-only view '${modelName}'`);
@@ -174,24 +227,18 @@ export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: C
 
   const options = { ...defaultOptions, ...userOptions, update: true };
 
-  // Capture old state before update for SQL diff
   const oldState = record.__data ? JSON.parse(JSON.stringify(record.__data)) : {};
 
   record.serialize(rawData, options);
 
-  // Auto-persist to SQL — skip for DB loads (isDbRecord) and relationship resolution (_relationshipKey)
   const orm = Orm.instance;
-  const shouldPersist = orm?.sqlDb && !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
-  if (shouldPersist && modelName) {
-    orm!.sqlDb!.persist('update', modelName, { record, oldState }, {}).catch((err: unknown) => {
-      orm!.emitPersistError({
-        operation: 'update',
-        modelName,
-        recordId: record.id,
-        error: err instanceof Error ? err : new Error(String(err)),
-      });
-    });
-  }
+  if (!orm?.sqlDb || !modelName || !persistRequested(options, userOptions)) return { result: undefined, written: writeNotRequested };
+
+  const written = orm.sqlDb.persist('update', modelName, { record, oldState }, {}).catch((failure: unknown) => {
+    throw reportPersistFailure('update', modelName, record.id, failure);
+  });
+
+  return { result: undefined, written };
 }
 
 /**

package/src/mysql/connection.ts

@@ -10,6 +10,8 @@ interface MysqlConfig {
   migrationsTable?: string;
   migrationsDir?: string;
   autoMigrate?: boolean;
+  writeBatchSize?: number;
+  writeQueueLimit?: number;
 }
 
 let pool: Pool | null = null;

package/src/mysql/mysql-db.ts

@@ -4,7 +4,7 @@ import { ensureMigrationsTable, getAppliedMigrations, getMigrationFiles, applyMi
 import { introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot } from './schema-introspector.js';
 import type { ModelSchema, ViewSchema, SnapshotEntry } from './schema-introspector.js';
 import { loadLatestSnapshot, detectSchemaDrift } from './migration-generator.js';
-import { buildInsert, buildUpdate, buildDelete, buildSelect } from './query-builder.js';
+import { buildInsert, buildInsertMany, buildUpdate, buildDelete, buildSelect } from './query-builder.js';
 import { store } from '@stonyx/orm';
 import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
@@ -32,6 +32,43 @@ interface ExecuteResult {
   insertId?: number;
 }
 
+interface QueuedWrite {
+  operation: string;
+  modelName: string;
+  context: PersistContext;
+  response: PersistResponse;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+}
+
+interface PreparedCreate {
+  write: QueuedWrite;
+  modelName: string;
+  record: OrmRecord;
+  row: Record<string, unknown>;
+  isPendingId: boolean;
+}
+
+type ExitEmitter = Pick<NodeJS.Process, 'once' | 'removeListener'>;
+
+const MYSQL_MAX_PLACEHOLDERS = 65535;
+const DEFAULT_WRITE_BATCH_SIZE = 500;
+const DEFAULT_WRITE_QUEUE_LIMIT = 10000;
+
+export class WriteQueueFullError extends Error {
+  constructor(limit: number) {
+    super(`MysqlDB write queue is full (${limit} queued writes, writeQueueLimit); the write was rejected`);
+    this.name = 'WriteQueueFullError';
+  }
+}
+
+export class WriteQueueClosedError extends Error {
+  constructor() {
+    super('MysqlDB is shutting down; the write was rejected');
+    this.name = 'WriteQueueClosedError';
+  }
+}
+
 interface OrmStore {
   get(key: string): Map<number | string, unknown> | undefined;
   get(key: string, id: number | string): unknown;
@@ -54,6 +91,7 @@ interface MysqlDBDeps {
   loadLatestSnapshot: typeof loadLatestSnapshot;
   detectSchemaDrift: typeof detectSchemaDrift;
   buildInsert: typeof buildInsert;
+  buildInsertMany: typeof buildInsertMany;
   buildUpdate: typeof buildUpdate;
   buildDelete: typeof buildDelete;
   buildSelect: typeof buildSelect;
@@ -65,6 +103,7 @@ interface MysqlDBDeps {
   config: typeof config;
   log: Record<string, ((...args: unknown[]) => void) | undefined>;
   path: typeof path;
+  process: ExitEmitter;
 }
 
 const defaultDeps: MysqlDBDeps = {
@@ -72,9 +111,9 @@ const defaultDeps: MysqlDBDeps = {
   getMigrationFiles, applyMigration, parseMigrationFile,
   introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
   loadLatestSnapshot, detectSchemaDrift,
-  buildInsert, buildUpdate, buildDelete, buildSelect,
+  buildInsert, buildInsertMany, buildUpdate, buildDelete, buildSelect,
   createRecord, store: store as OrmStore, confirm, readFile, getPluralName,
-  config, log, path
+  config, log, path, process
 };
 
 export default class MysqlDB {
@@ -84,14 +123,12 @@ 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();
+  readonly persistResolvesAfterWrite = true;
+  private _queuedWrites: QueuedWrite[] = [];
+  private _inFlightWrites = new Set<QueuedWrite>();
+  private _drainingWrites: Promise<void> | null = null;
+  private _acceptingWrites = true;
+  private _exitReport: (() => void) | null = null;
 
   constructor(deps: Partial<MysqlDBDeps> = {}) {
     if (MysqlDB.instance) return MysqlDB.instance;
@@ -113,6 +150,20 @@ export default class MysqlDB {
     this.pool = await this.deps.getPool(this.mysqlConfig);
     await this.deps.ensureMigrationsTable(this.pool, this.mysqlConfig.migrationsTable);
     await this.loadMemoryRecords();
+    this._acceptingWrites = true;
+    this._registerExitReport();
+  }
+
+  get writeBatchSize(): number {
+    return Number(this.mysqlConfig?.writeBatchSize) || DEFAULT_WRITE_BATCH_SIZE;
+  }
+
+  get writeQueueLimit(): number {
+    return Number(this.mysqlConfig?.writeQueueLimit) || DEFAULT_WRITE_QUEUE_LIMIT;
+  }
+
+  get pendingWriteCount(): number {
+    return this._inFlightWrites.size + this._queuedWrites.length;
   }
 
   async startup(): Promise<void> {
@@ -200,10 +251,36 @@ export default class MysqlDB {
   }
 
   async shutdown(): Promise<void> {
+    this._acceptingWrites = false;
+    while (this._drainingWrites) await this._drainingWrites;
+    this._unregisterExitReport();
     await this.deps.closePool();
     this.pool = null;
   }
 
+  private _registerExitReport(): void {
+    if (this._exitReport) return;
+    this._exitReport = () => this._reportUnpersistedWrites();
+    this.deps.process.once('exit', this._exitReport);
+  }
+
+  private _unregisterExitReport(): void {
+    if (!this._exitReport) return;
+    this.deps.process.removeListener('exit', this._exitReport);
+    this._exitReport = null;
+  }
+
+  private _reportUnpersistedWrites(): void {
+    const lostWrites = [...this._inFlightWrites, ...this._queuedWrites];
+    if (lostWrites.length === 0) return;
+
+    const lostByModel = new Map<string, number>();
+    for (const { modelName } of lostWrites) lostByModel.set(modelName, (lostByModel.get(modelName) ?? 0) + 1);
+    const breakdown = [...lostByModel].map(([modelName, count]) => `${modelName}: ${count}`).join(', ');
+
+    this.deps.log.error?.(`[MysqlDB] Process exiting with ${lostWrites.length} queued write(s) not persisted; they are lost (${breakdown})`);
+  }
+
   async save(): Promise<void> {
     // No-op: MySQL persists data immediately via persist()
   }
@@ -419,76 +496,185 @@ export default class MysqlDB {
   }
 
   async persist(operation: string, modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {
-    // Views are read-only — no-op for all write operations
     const Orm = (await import('@stonyx/orm')).default;
     if ((Orm as unknown as { instance?: { isView?: (name: string) => boolean } }).instance?.isView?.(modelName)) return;
 
-    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);
+    if (!this._acceptingWrites) throw new WriteQueueClosedError();
+    if (this._queuedWrites.length >= this.writeQueueLimit) throw new WriteQueueFullError(this.writeQueueLimit);
+
+    return new Promise<void>((resolve, reject) => {
+      const write: QueuedWrite = {
+        operation, modelName, context, response,
+        resolve: () => {
+          this._inFlightWrites.delete(write);
+          resolve();
+        },
+        reject: (error: unknown) => {
+          this._inFlightWrites.delete(write);
+          reject(error);
+        },
+      };
+      this._queuedWrites.push(write);
+      this._drainWritesInBackground();
+    });
+  }
+
+  private _drainWritesInBackground(): void {
+    if (this._drainingWrites) return;
+    this._drainingWrites = this._drainQueuedWrites().finally(() => {
+      this._drainingWrites = null;
+    });
+  }
+
+  private async _drainQueuedWrites(): Promise<void> {
+    while (this._queuedWrites.length > 0) {
+      const writes = this._takeNextWriteGroup();
+      writes.forEach(write => this._inFlightWrites.add(write));
+      try {
+        await this._executeWriteGroup(writes);
+      } catch (error) {
+        writes.filter(write => this._inFlightWrites.has(write)).forEach(write => write.reject(error));
       }
-    };
+    }
+  }
+
+  private _takeNextWriteGroup(): QueuedWrite[] {
+    const [first] = this._queuedWrites;
+    let groupSize = 1;
+
+    if (first.operation === 'create') {
+      while (
+        groupSize < this.writeBatchSize
+        && groupSize < this._queuedWrites.length
+        && this._queuedWrites[groupSize].operation === 'create'
+        && this._queuedWrites[groupSize].modelName === first.modelName
+      ) groupSize++;
+    }
 
-    // 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;
+    return this._queuedWrites.splice(0, groupSize);
   }
 
-  private async _persistCreate(modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {
-    const schemas = this.deps.introspectModels();
-    const schema = schemas[modelName];
+  private async _executeWriteGroup(writes: QueuedWrite[]): Promise<void> {
+    const [first] = writes;
+    if (first.operation === 'create') return this._persistCreates(first.modelName, writes);
 
-    if (!schema) return;
+    try {
+      if (first.operation === 'update') await this._persistUpdate(first.modelName, first.context, first.response);
+      if (first.operation === 'delete') await this._persistDelete(first.modelName, first.context);
+      first.resolve();
+    } catch (error) {
+      first.reject(error);
+    }
+  }
+
+  private async _persistCreates(modelName: string, writes: QueuedWrite[]): Promise<void> {
+    const schema = this.deps.introspectModels()[modelName];
+    const prepared: PreparedCreate[] = [];
+
+    for (const write of writes) {
+      try {
+        const create = schema ? this._prepareCreate(modelName, schema, write) : null;
+        if (create) prepared.push(create);
+        else write.resolve();
+      } catch (error) {
+        write.reject(error);
+      }
+    }
+
+    for (const chunk of this._chunkForSingleInsert(prepared)) {
+      await this._insertCreates(schema, chunk);
+    }
+  }
 
+  private _prepareCreate(modelName: string, schema: ModelSchema, write: QueuedWrite): PreparedCreate | null {
+    const { context, response } = write;
     const recordId = response?.data?.id;
     const record = recordId != null ? this.deps.store.get(modelName, (isNaN(recordId as number) ? recordId : parseInt(recordId as string)) as number | string) as OrmRecord | null : null;
 
-    if (!record) return;
-
-    const insertData = this._recordToRow(record, schema);
+    if (!record) return null;
 
-    // For auto-increment models, remove the pending ID.
-    // Check context.rawData (not record.__data) because __pendingSqlId is not a model
-    // attribute and gets lost during serialization.
+    const row = this._recordToRow(record, schema);
     const isPendingId = context.rawData?.__pendingSqlId === true;
 
-    if (isPendingId) {
-      delete insertData.id;
-    } else if (insertData.id !== undefined) {
-      // Keep user-provided ID (string IDs or explicit numeric IDs)
+    if (isPendingId) delete row.id;
+
+    return { write, modelName, record, row, isPendingId };
+  }
+
+  private _chunkForSingleInsert(prepared: PreparedCreate[]): PreparedCreate[][] {
+    const chunks: PreparedCreate[][] = [];
+    let chunk: PreparedCreate[] = [];
+    let chunkColumns = new Set<string>();
+
+    for (const create of prepared) {
+      const columnsWithCreate = new Set([...chunkColumns, ...Object.keys(create.row)]);
+      const mixesIdSources = chunk.length > 0 && chunk[0].isPendingId !== create.isPendingId;
+      const exceedsPlaceholders = (chunk.length + 1) * columnsWithCreate.size > MYSQL_MAX_PLACEHOLDERS;
+
+      if (chunk.length > 0 && (mixesIdSources || exceedsPlaceholders)) {
+        chunks.push(chunk);
+        chunk = [];
+        chunkColumns = new Set(Object.keys(create.row));
+      } else {
+        chunkColumns = columnsWithCreate;
+      }
+
+      chunk.push(create);
     }
 
-    const { sql, values } = this.deps.buildInsert(schema.table, insertData);
+    if (chunk.length > 0) chunks.push(chunk);
+    return chunks;
+  }
 
-    const [result] = await this.requirePool().execute(sql, values) as [ExecuteResult, unknown];
+  private async _insertCreates(schema: ModelSchema, creates: PreparedCreate[]): Promise<void> {
+    if (creates.length === 1) return this._insertCreatesOneByOne(schema, creates);
 
-    // Re-key the record in the store if MySQL generated the ID
-    if (isPendingId && result.insertId) {
-      const pendingId = record.id;
-      const realId = result.insertId;
-      const modelStore = this.deps.store.get(modelName);
-      if (!modelStore) throw new Error(`Model "${modelName}" not found in store during ID re-key`);
+    let firstInsertId: number | undefined;
 
-      modelStore.delete(pendingId as number | string);
-      record.__data.id = realId;
-      record.id = realId;
-      modelStore.set(realId as number | string, record);
+    try {
+      const { sql, values } = this.deps.buildInsertMany(schema.table, creates.map(({ row }) => row));
+      const [result] = await this.requirePool().execute(sql, values) as [ExecuteResult, unknown];
+      firstInsertId = result.insertId;
+    } catch {
+      return this._insertCreatesOneByOne(schema, creates);
+    }
 
-      // Update the response data with the real ID
-      if (response?.data) {
-        response.data.id = realId;
-      }
+    creates.forEach((create, index) => {
+      if (firstInsertId) this._adoptGeneratedId(create, firstInsertId + index);
+      create.write.resolve();
+    });
+  }
 
-      delete record.__data.__pendingSqlId;
+  private async _insertCreatesOneByOne(schema: ModelSchema, creates: PreparedCreate[]): Promise<void> {
+    for (const create of creates) {
+      try {
+        const { sql, values } = this.deps.buildInsert(schema.table, create.row);
+        const [result] = await this.requirePool().execute(sql, values) as [ExecuteResult, unknown];
+        if (result.insertId) this._adoptGeneratedId(create, result.insertId);
+        create.write.resolve();
+      } catch (error) {
+        create.write.reject(error);
+      }
     }
   }
 
+  private _adoptGeneratedId({ modelName, record, isPendingId, write }: PreparedCreate, realId: number): void {
+    if (!isPendingId) return;
+
+    const pendingId = record.id;
+    const modelStore = this.deps.store.get(modelName);
+    if (!modelStore) throw new Error(`Model "${modelName}" not found in store during ID re-key`);
+
+    modelStore.delete(pendingId as number | string);
+    record.__data.id = realId;
+    record.id = realId;
+    modelStore.set(realId, record);
+
+    if (write.response?.data) write.response.data.id = realId;
+
+    delete record.__data.__pendingSqlId;
+  }
+
   private async _persistUpdate(modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {
     const schemas = this.deps.introspectModels();
     const schema = schemas[modelName];