[8.x] Document the new upsert method

eloquent.md

@@ -609,6 +609,15 @@ You may also come across situations where you want to update an existing model o
         ['price' => 99, 'discounted' => 1]
     );
 
+If you would like to perform multiple "upserts", then you should use the `upsert` method instead. The first argument is the values to insert or update, and the second argument is the column(s) that uniquely identify records.
+
+    $numRecords = App\Models\Flight::upsert([
+        ['departure' => 'Oakland', 'destination' => 'San Diego', 'price' => 99],
+        ['departure' => 'Chicago', 'destination' => 'New York', 'price' => 150]
+    ], ['departure', 'destination']);
+
+The `upsert` method will also automatically set the `updated_at` timestamps, if timestamps are enabled on the model.
+
 <a name="deleting-models"></a>
 ## Deleting Models
 

queries.md

@@ -694,6 +694,13 @@ The `insertOrIgnore` method will ignore duplicate record errors while inserting
         ['id' => 2, 'email' => 'dayle@example.com'],
     ]);
 
+The `upsert` method will insert rows that do not exist and update the rows that already exist with the new values. The first argument is the values to insert or update, and the second argument is the column(s) that uniquely identify records.
+
+    DB::table('users')->upsert([
+        ['email' => 'taylor@example.com', 'votes' => 0],
+        ['email' => 'dayle@example.com', 'votes' => 0],
+    ], 'email');
+
 #### Auto-Incrementing IDs
 
 If the table has an auto-incrementing id, use the `insertGetId` method to insert a record and then retrieve the ID: