Packagist · #2453 most downloaded on Packagist

mavinoo/laravel-batch

v3.3.04.2M downloads/momavinoo/laravelBatch ↗New releases in your daily digest, changelog included.

Insert and update batch (bulk) in laravel

Last release 3 days ago
05 Oct 2026
Release timing varies
gaps range from 2 weeks to 1.3 years
Some releases are documented
notes for 14 of 36 stable releases
Nothing withdrawn
no release was ever pulled
9 years old
36 releases · first in 2018

Release timeline

36 releases since 2018

2018202020222024

Releases

v3.3.05 Oct 2026
Counter and conditional upserts, rows back from upserts, a report of skipped duplicates, fast imports, row validation and exports. Everything is addit
Counter and conditional upserts, rows back from upserts, a report of skipped duplicates, fast
imports, row validation and exports. Everything is additive, so upgrading from 3.2 needs no code
changes:

composer update mavinoo/laravel-batch

Added

Counter upserts

Batch::upsert(new Stock, $rows, ['sku'], ['qty' => ['+']]); // qty = stored qty + new qty

['-'], ['max'] and ['min'] work the same way, on every database.

Conditional upserts

Batch::upsert(new Product, $rows, ['sku'], null, ['onlyIf' => ['updated_at' => '>']]);

Updates an existing row only when the new value wins. New rows are always inserted.

Rows back, and the duplicates that were skipped

$users = Batch::upsertReturning(new User, $rows, ['email'], ['name'], ['id', 'email']); $result = Batch::insertOrIgnoreRows(new User, $rows, ['email']); // ['inserted' => 98, 'skipped' => [['email' => 'dup@example.com', ...], ...]]

insertOrIgnoreRows() was checked with 8 concurrent writers inserting overlapping keys on
MySQL 8.4, MariaDB and PostgreSQL. Every row was reported by the connection that inserted it.

Fast imports

Batch::import(new Order, storage_path('orders.csv'), ['fast' => true]);

Uses COPY on PostgreSQL and LOAD DATA LOCAL INFILE on MySQL and MariaDB.

Bad values that MySQL would silently store with a warning throw instead, and nothing is written.

1,000,000-row CSV import fast

PostgreSQL 18.7 s 6.6 s

MySQL 8.4 18.7 s 8.4 s

MariaDB 12.6 s 6.4 s

Row validation in imports

Batch::import(new User, 'users.csv', ['rules' => ['email' => 'required|email']]); // ['totalRows' => 9988, 'skipped' => 12, 'errors' => [15 => ['email' => [...]]]]

Export

User::where('active', true)->exportTo(storage_path('users.csv'), ['maxRows' => 100000]);

Writes CSV, TSV or JSON Lines files (also gzipped), a chunk at a time with constant memory.

maxRows splits the output into numbered parts.

Turn timestamps off

User::withoutTimestamps(fn () => Batch::update(new User, $rows)) now has documentation and tests
for every method (#97).

Changed

upsert() takes an optional fifth $options argument.

import() also returns an errors key.

Full changelog: https://github.com/mavinoo/laravelBatch/blob/master/CHANGELOG.md
Pull request: #128

1,000,000-row CSV	import	`fast`
PostgreSQL	18.7 s	6.6 s
MySQL 8.4	18.7 s	8.4 s
MariaDB	12.6 s	6.4 s

Additional notes2 sources agree

Added

Counter upserts: upsert($table, $rows, ['sku'], ['qty' => ['+']]) adds to the stored value. Also ['-'], ['max'] and ['min'], on every database.
Conditional upserts: the onlyIf option, e.g. ['onlyIf' => ['updated_at' => '>']], updates an existing row only when the new value wins.
upsertReturning(): upsert and get every row of the batch back as stored, in input order.
insertOrIgnoreRows(): insert, skip duplicates, and report exactly which rows were skipped.
Documented and tested that Model::withoutTimestamps() turns timestamps off for every method (#97).
import() option fast: load with COPY on PostgreSQL and LOAD DATA LOCAL INFILE on MySQL and MariaDB, 2 to 2.8 times faster. Bad values that MySQL would store with a warning throw instead.
import() option rules: validate each row with Laravel's validator; failing rows are skipped and their messages returned in the new errors result, by row number.
export() and the exportTo() builder macro: write the rows a query matches to CSV, TSV or JSON Lines files (also gzipped), a chunk at a time, optionally split into parts.

Changed

upsert() takes an optional fifth $options argument.
import() also returns an errors key.

Open source →

v3.2.05 Oct 2026

New bulk operations for large tables and files, JSON column updates, and two JSON bug fixes. Everything is additive, so upgrading from 3.1 needs no co

New bulk operations for large tables and files, JSON column updates, and two JSON bug fixes.
Everything is additive, so upgrading from 3.1 needs no code changes:

composer update mavinoo/laravel-batch

Added

Update keys inside JSON columns (#64, #83, #111)

Batch::update(new User, [
    ['id' => 1, 'settings->theme' => 'dark', 'settings->notify->email' => false],
]);

Works in every update method, on MySQL, MariaDB, PostgreSQL and SQLite.
Other keys are kept, missing objects are created, and values keep their JSON type.
updated_at only changes when the document changes.
Arrays and collections for columns the model casts to JSON (array, json, collection,
AsCollection, ...) are encoded the way the model stores them, in update, insert and upsert.

`insertGetIds()`: insert rows and get their ids (#48)

$ids = Batch::insertGetIds(new User, $rows); // [101, 102, ...] in row order

Checked with 8 concurrent writers and 78,720 rows on MySQL 8.4, MariaDB, PostgreSQL and SQLite,
with 0 wrong ids.

`import()`: import files and iterables with constant memory

Batch::import(new User, storage_path('users.csv'), ['mode' => 'upsert', 'uniqueBy' => ['email']]);

Reads CSV, TSV and JSON Lines files (also .gz), open streams, or any iterable such as
Model::cursor().
Supports column mapping, null values, transforms, and progress and error callbacks.

500,000-row CSV	`import()`	array + `insertRows()`
Memory	7 MB	765 MB
Time	30–45% faster

`splitFile()`: split large files

Batch::splitFile($path, lines: 50000); // users-001.csv, users-002.csv, ...

Splits by number of records and / or size.
Never cuts a record or a multi-line CSV field in half, and repeats the header in every part.

`deleteInChunks()`, `updateInChunks()`, `archive()`

Log::where('created_at', '<', now()->subYear())->deleteInChunks(10000);
User::where('active', false)->updateInChunks(['status' => 'archived']);
Order::where('created_at', '<', '2020-01-01')->archiveTo('orders_archive');

Each runs a chunk at a time, in primary key order, so no lock is held for long.
Deleting 200k rows on MySQL 8.4: the longest chunk took 0.10 s, against 0.8 s for one DELETE.
archive() copies and deletes each chunk in one transaction.

`sync()`: make a table match a list

Product::where('supplier_id', 5)->syncRows($feedRows, ['sku']);
// ['inserted' => 120, 'updated' => 4800, 'deleted' => 35]

Inserts, updates and deletes in one transaction.
The database compares the keys itself, so its collation decides which are equal. On MySQL,
"ABC" and "abc" are the same key.
Soft-deleted rows that are in the list are restored.
Syncing 100,000 rows takes 1.4–4.8 s with about 15 MB of memory.

Fixed

Updating a PostgreSQL json column failed with operator does not exist: json <> unknown.
MySQL json columns touched updated_at even when their value didn't change.

Also

219 tests on SQLite, MySQL, MariaDB and PostgreSQL, PHP 8.1 – 8.5 and Laravel 10 – 13.
PHPStan level 9 with Larastan.

Full changelog: https://github.com/mavinoo/laravelBatch/blob/master/CHANGELOG.md
Pull request: #126

Open source →

Additional notes2 sources agree

Added

Update keys inside JSON columns with column->key (#64, #83, #111). Values keep their JSON type, missing objects are created and updated_at only changes when the document changes.
Arrays and collections for columns the model casts to JSON are encoded the way the model stores them, in every update, insert and upsert method.
insertGetIds() and HasBatch::batchInsertGetIds(): insert rows and get their auto-increment ids, in row order (#48).
import() and HasBatch::batchImport(): import rows from CSV, TSV and JSON Lines files (also gzipped), open streams or any iterable, a chunk at a time with constant memory. Supports insert, insert-ignore and upsert, column mapping, transforms, progress and error callbacks.
splitFile(): split a large file into parts by number of records and / or size, without cutting a record or a multi-line CSV field in half.
deleteInChunks(), updateInChunks() and archive(): delete, update or move the rows a query matches a chunk at a time, walking the table in primary key order. Also available as deleteInChunks(), updateInChunks() and archiveTo() on Eloquent and query builders.
sync(): insert, update and delete the rows a query matches so they match a list, in one transaction. The database compares the keys, so its collation decides which are equal. Also available as syncRows() on Eloquent builders.

Fixed

Updating a PostgreSQL json column failed with "operator does not exist: json <> unknown".
MySQL json columns touched updated_at even when their value didn't change.

Open source →

v3.1.04 Oct 2026

New ways to write batches, a preview mode, and much faster large updates. Everything is additive, so upgrading from 3.0 needs no code changes:

New ways to write batches, a preview mode, and much faster large updates. Everything is
additive, so upgrading from 3.0 needs no code changes:

composer update mavinoo/laravel-batch

Added

updateByKeys(): update rows matched on any number of key columns.
insertRows(): insert rows given as column => value pairs.
upsert(): insert or update in one query, with timestamps (created_at only on new
rows), enums, and large batches split automatically in one transaction.
deleteByKeys(): delete rows matched on one or more key columns. Models using
SoftDeletes are soft deleted unless $force is true.
pretend(): see the SQL and bindings a call would run, without running it or
connecting to the database.
Static HasBatch methods for every operation: batchUpdateMultipleCondition(),
batchUpdateWithTwoIndex(), batchUpdateByKeys(), batchInsertRows(),
batchUpsert(), batchDeleteByKeys().

Faster updates

Each UPDATE ... CASE statement now holds at most 100 rows. The database checks every
row against the CASE branches one by one, so large statements slowed down quickly.

Updating 50,000 rows	3.0.0	3.1.0
MySQL 8.4	30.5 s	3.1 s
MariaDB 10.11	25.3 s	2.4 s
PostgreSQL 16	over 15 min	2.5 s
SQLite 3.45	3.7 s	3.4 s

Deprecated

The instance method (new Model)->updateMultipleCondition(); use the static
Model::batchUpdateMultipleCondition(). It will be removed in 4.0.

Also

Clearer InvalidArgumentExceptions for rows that aren't arrays, non-string column
names and invalid arithmetic operators.
PHPStan level 9 with Larastan now runs in CI.

Full changelog: https://github.com/mavinoo/laravelBatch/blob/v3.1.0/CHANGELOG.md
Pull request: #125

Open source →

Additional notes2 sources agree

Added

updateByKeys(): update rows matched on any number of key columns.
insertRows(): insert rows given as column => value pairs.
upsert(): insert or update in one query, with timestamps, enums and automatic splitting of large batches in one transaction.
pretend(): return the statements a call would run, with bindings, without running them or connecting to the database.
deleteByKeys(): delete rows matched on one or more key columns. Soft-deleting models are soft deleted unless $force is true.
Static HasBatch methods: batchUpdateMultipleCondition(), batchUpdateWithTwoIndex(), batchUpdateByKeys(), batchInsertRows(), batchUpsert() and batchDeleteByKeys().
PHPStan (level 9) with Larastan in CI, and a composer analyse script.

Changed

Large updates are much faster: each UPDATE ... CASE statement now holds at most 100 rows. The database checks every row against the CASE branches one by one, so big statements got slow quickly. Updating 50,000 rows went from 30.5 s to 3.1 s on MySQL 8.4, from 25.3 s to 2.4 s on MariaDB 10.11, and from over 15 minutes to 2.5 s on PostgreSQL 16.
The service provider registers one shared Batch instance, so the facade, batch() and the HasBatch trait see the same pretend() state.

Deprecated

The instance method HasBatch::updateMultipleCondition(); use the static batchUpdateMultipleCondition(). It will be removed in 4.0.

Open source →

v3.0.04 Oct 2026

A major release that rewrites how queries are built. Every 2.x user should upgrade : all 2.x versions build SQL by escaping values by hand, which allo

A major release that rewrites how queries are built. Every 2.x user should upgrade:
all 2.x versions build SQL by escaping values by hand, which allows SQL injection
(always on PostgreSQL, and through index values and JSON keys on every database).
3.0 sends every value as a bound parameter and lets Laravel's grammar quote every
column and table name.

composer require "mavinoo/laravel-batch:^3.0"

Requires PHP 8.1+ and Laravel 10 – 13. Upgrading from 2.x takes a few
minutes for most projects: see the upgrade guide.

Breaking changes

The $raw argument is removed. Wrap only the values that are SQL in DB::raw():
['id' => 1, 'score' => DB::raw('score * 2')]. Passing true for the old argument
throws, so a missed call never stores SQL as text.
Update methods return int and insert() returns array. Empty input returns
0 / zero counts instead of false.
Invalid input throws InvalidArgumentException before anything is written.
BatchInterface and Batch declare return types.
Mavinoo\Batch\Common\Common and the global str() helper are removed.

Added

Laravel 13 support.
DB::raw() in values, index values and conditions.
Enum values in every method.
Batches over the database's bound parameter limit are split automatically and
run in one transaction on the model's connection.
A test suite (composer test) and GitHub Actions on PHP 8.1 – 8.5,
Laravel 10 – 13, MySQL, MariaDB, PostgreSQL and SQLite.

Fixed

Quotes, backslashes, JSON, leading zeros and booleans are stored exactly as
given (#66, #68, #70, #73, #76, #96, #101).
Every method works on PostgreSQL and SQLite (#116).
updateMultipleCondition() with string keys, on PostgreSQL, with null
conditions, and when a condition column is updated in the same call on MySQL.
updated_at only changes for rows that change, on every database (#120).
Models with CREATED_AT or UPDATED_AT set to null (#107).
insert() rolls back on the model's own connection, and $insertIgnore works
on PostgreSQL and SQLite.

Full changelog: https://github.com/mavinoo/laravelBatch/blob/v3.0.0/CHANGELOG.md
Pull request: #124

Open source →

Additional notes2 sources agree

Upgrading from 2.x: see UPGRADE.md.

Security

Build every query with bound parameters and grammar-quoted identifiers. 2.x escaped values by hand, which allowed SQL injection, always on PostgreSQL and through index values and JSON keys on every database.

Breaking

Require PHP 8.1+ and Laravel 10 – 13.
Remove the $raw argument; wrap raw SQL values in DB::raw() instead. Passing true throws.
Update methods return int, insert() returns array. Empty input returns 0 / zero counts instead of false.
Invalid input throws InvalidArgumentException instead of returning false, failing with an SQL error, or throwing ArgumentCountError / TypeError.
Add return types to BatchInterface and Batch.
Remove Mavinoo\Batch\Common\Common and the global str() helper.

Added

Laravel 13 support.
DB::raw() values in rows, index values and conditions.
Enum values in every method (backed enums by value, other enums by name).
Automatic splitting of batches that exceed the database's bound parameter limit, in one transaction.
A standalone test suite (composer test) for SQLite, MySQL, MariaDB and PostgreSQL.
GitHub Actions running the tests on PHP 8.1 – 8.5, Laravel 10 – 13 and every supported database.

Fixed

Strings with quotes or backslashes, JSON, numeric strings with leading zeros and booleans are stored exactly as given (#66, #68, #70, #73, #76, #96, #101).
PostgreSQL and SQLite support for every method (#116).
updateMultipleCondition() with string key values, on PostgreSQL, with null conditions, and when a condition column is updated in the same call on MySQL.
updated_at is only touched for rows that change, on every database (#120).
insert() uses a transaction on the model's connection, and $insertIgnore works on PostgreSQL and SQLite.
Arithmetic with a negative operand on PostgreSQL and SQLite.
Models with CREATED_AT or UPDATED_AT set to null (#107).

Open source →

v2.5.14 Oct 2026Deprecated

Nullable parameters are now declared as ?string , which works on PHP 7.1 through 8.5 and still avoids the PHP 8.4 deprecation notice.

A bug-fix release for v2.5.0. All v2.5.0 users should upgrade, especially on PHP 7.

What's Changed

Fix PHP 7 support and v2.5.0 regressions by @mavinoo in #123

Fixed

PHP 7.1 – 7.4: v2.5.0 failed with syntax error, unexpected '|'. Nullable
parameters are now declared as ?string, which works on PHP 7.1 through 8.5
and still avoids the PHP 8.4 deprecation notice.
MySQL / MariaDB: updated_at is updated again for rows that change, in
update(), updateWithTwoIndex() and updateMultipleCondition().
updated_at is now updated when a column changes from NULL to a value.
An explicit updated_at passed for one row is kept when other rows in the
same call get the automatic timestamp.
updateWithTwoIndex() writes values the same way as v2.4.1 again: leading
zeros are kept ('0912…'), false is stored as 0, and string values work
on PostgreSQL.
updateMultipleCondition() no longer fails with
Method Illuminate\Support\Stringable::toString does not exist on older
Laravel versions (#118).

updated_at is still only touched when a value actually changes (#120), and
now this works on every database.

Upgrading

No code changes are needed:

composer update mavinoo/laravel-batch

Tested on PHP 7.1 – 8.5, with Laravel 8 and 11, on MySQL/MariaDB, PostgreSQL and SQLite.

Full Changelog: v2.5.0...v2.5.1

Open source →

Additional notes2 sources agree

Fixed

PHP 7.1 – 7.4 support, broken in 2.5.0 (#123).
updated_at not being updated on MySQL / MariaDB, when a column changes from NULL, and an explicit updated_at being dropped (#123).
updateWithTwoIndex() dropping leading zeros, failing on false and on PostgreSQL (#123).
updateMultipleCondition() failing on older Laravel versions with Stringable::toString (#118).

Open source →

v2.5.08 Jan 2026Deprecated

Fix PHP 8.4 deprecation notices: parameters that default to null are now declared as string|null in Batch , BatchInterface and HasBatch by @neoighodar…

⚠️ Superseded by v2.5.1, which fixes the known issues below and PHP 7 support. Please upgrade.

What's Changed

Fix PHP 8.4 deprecation notices: parameters that default to null are now
declared as string|null in Batch, BatchInterface and HasBatch
by @neoighodaro in #113
Only touch updated_at when a value actually changes
by @manandhar in #119
updateWithTwoIndex() no longer writes to its two index columns, and uses a
new value formatter by @mohamed-3ly in #122

⚠️ Known issues

These were found by testing this release against v2.4.1 on MySQL/MariaDB,
PostgreSQL and SQLite:

MySQL / MariaDB: update() and updateMultipleCondition() no longer update
updated_at for rows that change. MySQL applies SET assignments left to right,
so the "did it change?" check already sees the new values.
All databases: when a column changes from NULL to a value, updated_at
is not updated.
All databases: an explicit updated_at passed for one row is dropped when
another row in the same call gets the automatic timestamp.
updateWithTwoIndex():
- numeric strings are written without quotes, so leading zeros are lost
  ('09121234567' is stored as 9121234567) on MySQL and SQLite
- false fails on MySQL and PostgreSQL, and is stored as an empty string on SQLite
- on PostgreSQL every string value fails (column "..." does not exist)

If you use updated_at on MySQL, store numeric strings or booleans with
updateWithTwoIndex(), or use updateWithTwoIndex() on PostgreSQL,
stay on v2.4.1 for now:

composer require mavinoo/laravel-batch:2.4.1

All of these are fixed in the upcoming v3.0.0.

Full Changelog: v2.4.1...v2.5.0

Open source →

Additional notes2 sources agree

Added

Only touch updated_at when a value changes (#119).

Fixed

PHP 8.4 deprecation notices (#113).
updateWithTwoIndex() writing to its index columns (#122).

Open source →

mavinoo/laravel-batch

Release timeline

Releases

Added

Counter upserts

Conditional upserts

Rows back, and the duplicates that were skipped

Fast imports

Row validation in imports

Export

Turn timestamps off

Changed

Added

Changed

Added

Update keys inside JSON columns (#64, #83, #111)

insertGetIds(): insert rows and get their ids (#48)

import(): import files and iterables with constant memory

splitFile(): split large files

deleteInChunks(), updateInChunks(), archive()

sync(): make a table match a list

Fixed

Also

Added

Fixed

Added

Faster updates

Deprecated

Also

Added

Changed

Deprecated

Breaking changes

Added

Fixed

Security

Breaking

Added

Fixed

What's Changed

Fixed

Upgrading

Fixed

What's Changed

⚠️ Known issues

Added

Fixed

`insertGetIds()`: insert rows and get their ids (#48)

`import()`: import files and iterables with constant memory

`splitFile()`: split large files

`deleteInChunks()`, `updateInChunks()`, `archive()`

`sync()`: make a table match a list