Class: BulkUpsertBuilder<T>

Defined in: src/bulk/BulkUpsertBuilder.ts:38

High-performance bulk upsert engine executing chunked batch insert-or-update operations across database engines.

Automatically manages audit timestamps (@CreatedAt, @UpdatedAt), creator identifiers (@CreatedBy), and optimistic concurrency versions across batches.

Usecase

Ideal for sync pipelines, API integrations, and catalog ingestion where incoming records may be new or existing.

Example

PostgreSQL / MySQL / SQLite / MSSQL:

const upsertEngine = new BulkUpsertBuilder(adapter, 'products', metadata);
const processed = await upsertEngine.execute(incomingProducts, {
  conflictKeys: ['sku'],
  update: ['price', 'stockQuantity', 'title'],
  batchSize: 500,
});
console.log(`Processed ${processed} upsert items`);

Type Parameters

Type Parameter
T extends object

Constructors

Constructor

new BulkUpsertBuilder<T>(adapter, tableName, metadata?, transaction?, context?): BulkUpsertBuilder<T>

Defined in: src/bulk/BulkUpsertBuilder.ts:39

Parameters

Parameter	Type
adapter	IDbAdapter
tableName	string
metadata?	EntityMetadata
transaction?	DbTransaction
context?	any

Returns

BulkUpsertBuilder<T>

Methods

execute()

execute(entities, options): Promise<number>

Defined in: src/bulk/BulkUpsertBuilder.ts:54

Executes the bulk upsert workflow across the supplied entities.

Parameters

Parameter	Type	Description
entities	Partial<T>[]	List of entity objects to insert or update.
options	BulkUpsertOptions<T>	Upsert configuration specifying conflict keys and update fields.

Returns

Promise<number>

Total number of records inserted or updated.