Batch API

These methods are available on the Drizzle Postgres driver (drizzle-orm/postgres).

MethodUse it toOn failure
batchCommit togetherRolls back the batch
pipelineSend queries on one connectionOther queries can commit
parallelRun queries in parallelOther queries can commit
bulkInsertInsert many rowsRolls back by default
bulkUpdateUpdate rows by keyRolls back by default

Batch

db.batch() runs all statements in one transaction. If the insert fails on a unique constraint on stockReceipts.id, PostgreSQL rolls back the stock update.

const sku = 'usb-c-cable';
const quantity = 20;

const response = await db.batch([
  db.update(products)
    .set({ stock: sql`${products.stock} + ${quantity}` })
    .where(eq(products.sku, sku))
    .returning({ stock: products.stock }),
  db.insert(stockReceipts).values({ id: 'receipt-1042', sku, quantity }),
]);

console.log(response[0]); // [{ stock: 20 }] if the product started at zero

The driver sends the batch in one round trip and returns results in input order.

Batch options

Isolation

Use isolation to control which changes from other transactions each query can see.

At PostgreSQL’s default isolation level, read committed, the count can include a product inserted after the list was read. With repeatable read, both queries read from the same snapshot. PostgreSQL transaction isolation

const [page, total] = await db.batch([
  db.select().from(products).orderBy(products.sku).limit(25),
  db.$count(products),
], { isolation: 'repeatable read', readOnly: true });

Set readOnly: true to run a read-only transaction. In a read-only serializable transaction, deferrable: true lets PostgreSQL wait for a safe snapshot.

Use snapshot to import a snapshot exported by another transaction that is still open. This requires repeatable read or serializable. PostgreSQL transaction options

Metrics

Set metrics to measure the batch. response.metrics.total includes time spent waiting for a connection, and roundTrips counts network round trips. Find each query’s timings in response.metrics.queries, in input order.

const response = await db.batch([
  db.$count(products),
  db.$count(stockReceipts),
], { metrics: 'us' });

console.log(response.metrics.total, response.metrics.roundTrips);

Use metrics: true for fractional milliseconds, 'ms' for whole milliseconds, or 'us' for whole microseconds.

Pipeline

db.pipeline() sends queries back-to-back on one connection. Each statement runs in its own transaction.

const [usb, hdmi] = await db.pipeline([
  db.update(products)
    .set({ stock: 19 })
    .where(eq(products.sku, 'usb-c-cable'))
    .returning({ sku: products.sku }),
  db.update(products)
    .set({ stock: 8 })
    .where(eq(products.sku, 'hdmi-cable'))
    .returning({ sku: products.sku }),
]);

if (usb.status === 'rejected') console.error(usb.reason);
if (hdmi.status === 'rejected') console.error(hdmi.reason);

Each query returns a settled result in input order. If the HDMI update fails, hdmi.reason contains the error and a successful USB update stays committed. If a SKU is missing, its update succeeds and value is an empty array.

Parallel

db.parallel() runs independent queries concurrently across the pool. Like pipeline, it returns one settled result per query in input order.

const [page, total] = await db.parallel([
  db.select().from(products).orderBy(products.sku).limit(25),
  db.$count(products),
]);

if (page.status === 'rejected') throw page.reason;

const catalog = {
  products: page.value,
  total: total.status === 'fulfilled' ? total.value : null,
};

When the list and count need the same snapshot, use a batch with repeatable read.

bulkInsert

db.bulkInsert() inserts rows into one table. Omitted values use Drizzle’s runtime defaults when configured, then PostgreSQL column defaults.

const inserted = await db.bulkInsert(products, [
  { sku: 'usb-c-hub', name: 'USB-C Hub' },
  { sku: 'usb-c-adapter', name: 'USB-C Adapter' },
]);

console.log(inserted.rowCount); // 2

bulkUpdate

db.bulkUpdate() matches input rows to existing rows using by. Pass a unique key column or an array of columns for a composite key. Each input row needs the full key and the same update columns. Drizzle can supply values for columns with $onUpdateFn.

const updated = await db.bulkUpdate(products, [
  { sku: 'usb-c-hub', name: 'USB-C Hub', stock: 40 },
  { sku: 'usb-c-adapter', name: 'USB-C Adapter', stock: 75 },
  { sku: 'usb-c-charger', name: 'USB-C Charger', stock: 12 },
], { by: products.sku });

console.log(updated.rowCount); // 2 when the charger SKU is missing

Unmatched keys are skipped. bulkUpdate sends values as arrays and turns them into rows with PostgreSQL’s unnest. Use db.update() for column types that this method cannot send as arrays.

Bulk writes and transactions

Both bulk methods split the input into chunks and run them in one transaction by default. Set chunk to control how many rows go into each chunk. With atomic: false, each chunk commits independently. If a later chunk fails, earlier committed chunks stay in the database.

Use rowCount to read the total affected rows after a successful call. To get the written rows back, use .returning() on the regular insert or update builder.

Prepared queries

batch, pipeline, and parallel accept prepared queries. The bulk methods take rows. In this example, call .prepare() once and .bind() for each SKU.

const productBySku = db.select().from(products)
  .where(eq(products.sku, sql.placeholder('sku')))
  .prepare('product_by_sku');

const [usb, hdmi] = await db.batch([
  productBySku.bind({ sku: 'usb-c-cable' }),
  productBySku.bind({ sku: 'hdmi-cable' }),
]);

HTTP connections

Upgrading to v1

If you use drizzle-orm/postgres/http/neon, change the import to drizzle-orm/postgres/neon-http.