For a nightly Eloquent product-feed import, why use Product::upsert() instead of updateOrCreate() per row, and what does upsert() skip?

## Per-row helpers versus one statement An electronics store's nightly feed carries 80,000 products. The obvious loop is one `updateOrCreate()` per row. Each call selects the row, then inserts it or saves the changed columns, so the import costs well over 80,000 round trips and hydrates 80,000 models. `upsert()` replaces the loop with one **insert-or-update statement per batch**: the database inserts rows whose unique key is new and updates the listed columns for rows that already exist. ```php foreach (array_chunk($feedRows, 1000) as $batch) { Product::upsert( $batch, uniqueBy: ['sku'], update: ['name', 'price_cents', 'stock'], ); } ``` ## The three arguments 1. **`$values`** — an array of rows, each an associative array of column => value. A single row may also be passed. 2. **`$uniqueBy`** — the column or columns that identify an existing row. Except on SQL Server, these must be covered by a primary or unique index. 3. **`$update`** — the columns to overwrite when the row exists. Omit it and every column of the first row is updated. On the query builder an empty array turns the call into a plain insert, but Eloquent appends `updated_at` to the list on a model with timestamps, so existing rows still get their `updated_at` bumped. Eloquent adds on top of the query builder's version: - it sets `created_at` and `updated_at` on every row when the model uses timestamps, and adds `updated_at` to the update list, so an existing row keeps its original `created_at`; - for models using `HasUuids` or `HasUlids`, it generates the unique id for rows that lack one. The call returns the number of affected rows as reported by the driver. ## What upsert skips Because the rows go straight to the query builder, no models are built: - **no model events**, so observers never see the created or updated products; - **no casts or mutators**, so a JSON column needs an already-encoded string and a money value must be in its stored form; - **no mass-assignment filtering**, since `$fillable` only applies to `fill()`; - no `wasRecentlyCreated`, no dirty tracking and no report of which rows were inserted versus updated. These are the price of speed. When a side effect depends on the change, such as reindexing search for changed prices, it has to be handled explicitly after the batch. ## Database behaviour to know | Point | Detail | |---|---| | Index requirement | `uniqueBy` columns need a primary or unique index on every database except SQL Server | | MySQL and MariaDB | ignore `uniqueBy` and match on the table's primary and unique indexes | | Laravel 13 validation | an empty `uniqueBy` now throws `InvalidArgumentException` instead of producing invalid SQL | | Batch size | each row adds bindings, so batches of a few hundred to a few thousand rows keep statements under driver parameter limits | The MySQL row is a common surprise: a table with a unique `sku` **and** a unique `ean` can match on `ean` even though the call said `uniqueBy: ['sku']`. ## Choosing - **`updateOrCreate()`** for small volumes, or when observers, casts or per-row decisions must run. - **`upsert()`** for bulk imports where the data is already in storable form and side effects can run separately. - **`insertOrIgnore()` or `saveOrIgnore()`** when existing rows must be left alone entirely. A pragmatic import often combines them: batch `upsert()` for the catalogue fields, then a targeted query for the rows whose price changed to trigger downstream work. ## Preparing the rows Since casts do not run, each row must already be in the form the database stores: - JSON columns as encoded strings, for example `json_encode($row['specs'])`; - enum-backed columns as their backing value, not the enum case; - money in the stored unit, such as integer cents, not a formatted string; - every row with the **same set of keys**, since the statement is compiled from the first row's columns. Validating and normalising the feed before the batch is cheap compared with discovering a malformed column halfway through a million-row import.