From bb8adaa28aa36a341f52a154fcd368f13464e5c8 Mon Sep 17 00:00:00 2001
From: silverqx <silver.zachara@gmail.com>
Date: Sun, 21 Aug 2022 18:55:30 +0200
Subject: [PATCH] docs added Model::upsert

---
 docs/tinyorm/getting-started.mdx | 33 ++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/docs/tinyorm/getting-started.mdx b/docs/tinyorm/getting-started.mdx
index df2ef5891..b6ed5b363 100644
--- a/docs/tinyorm/getting-started.mdx
+++ b/docs/tinyorm/getting-started.mdx
@@ -26,6 +26,7 @@ keywords: [c++ orm, orm, getting started, tinyorm]
     - [Inserts](#inserts)
     - [Updates](#updates)
     - [Mass Assignment](#mass-assignment)
+    - [Upserts](#upserts)
 - [Deleting Models](#deleting-models)
     - [Truncate Table](#truncate-table)
 - [Replicating Models](#replicating-models)
@@ -645,6 +646,38 @@ If you would like to make all of your attributes mass assignable, you may define
         inline static QStringList u_guarded {};
     };
 
+### Upserts
+
+Occasionally, you may need to update an existing model or create a new model if no matching model exists.
+
+In the example below, if a flight exists with a `departure` location of `Oakland` and a `destination` location of `San Diego`, its `price` and `discounted` columns will be updated. If no such flight exists, a new flight will be created which has the attributes resulting from merging the first argument vector with the second argument vector:
+
+    auto flight = Flight::updateOrCreate(
+        {{"departure", "Oakland"}, {"destination", "San Diego"}},
+        {{"price", 99}, {"discounted", 1}}
+    );
+
+:::note
+The `firstOrCreate` and `updateOrCreate` methods persist the model, so there's no need to manually call the `save` method.
+:::
+
+If you would like to perform multiple "upserts" in a single query, then you should use the `upsert` method instead. The method's first argument consists of the values to insert or update, while the second argument lists the column(s) that uniquely identify records within the associated table. The method's third and final argument is the vector of the columns that should be updated if a matching record already exists in the database. The `upsert` method will automatically set the `created_at` and `updated_at` timestamps if timestamps are enabled on the model:
+
+    Flight::upsert(
+        {{{"departure", "Oakland"}, {"destination", "San Diego"}, {"price", 99}},
+         {{"departure", "Chicago"}, {"destination", "New York"},  {"price", 150}}},
+        {"departure", "destination"},
+        {"price"}
+    );
+
+:::caution
+All databases except SQL Server require the columns in the second argument of the `upsert` method to have a "primary" or "unique" index. In addition, the MySQL database driver ignores the second argument of the `upsert` method and always uses the "primary" and "unique" indexes of the table to detect existing records.
+:::
+
+:::info
+Row and column aliases will be used with the MySQL server >=8.0.19 instead of the VALUES() function as is described in the MySQL [documentation](https://dev.mysql.com/doc/refman/8.0/en/insert-on-duplicate.html). The MySQL server version is auto-detected and can be overridden in the [configuration](/database/getting-started.mdx#configuration).
+:::
+
 ## Deleting Models
 
 To delete a model, you may call the `remove`, or an alias `deleteRow` method on the model instance: