feat: add upsert method

docs/src/concepts/factories.md

@@ -43,6 +43,36 @@ assert_eq!(product.name, "Anvil 3000");
 
 Fields you don't set are filled with generated values automatically.
 
+## Building Without Persisting
+
+Use `make()` instead of `create()` to build a model instance
+in memory without hitting the database:
+
+```rust
+# extern crate fabrique;
+# extern crate sqlx;
+# extern crate uuid;
+# use fabrique::prelude::*;
+# use uuid::Uuid;
+#
+# #[derive(Model, Factory)]
+# pub struct Product {
+#     id: Uuid,
+#     name: String,
+#     price_cents: i32,
+# }
+# fn main() {
+let product: Product = Product::factory::<sqlx::Sqlite>()
+    .name("Anvil 3000".to_string())
+    .make();
+
+assert_eq!(product.name, "Anvil 3000");
+# }
+```
+
+This is useful for preparing data for bulk operations like
+[`upsert()`](../cookbook/bulk-update-and-upsert.md#bulk-upsert-a-collection).
+
 ## Random Value Generation
 
 By default, factories generate random values for all fields using

docs/src/concepts/models.md

@@ -255,8 +255,12 @@ let anvil: Product = Product::find(&pool, anvil.id).await?;
 // Upsert (insert or update on PK conflict)
 let anvil: Product = anvil.save(&pool).await?;
 
+// Bulk upsert a collection
+let products = vec![anvil];
+products.upsert(&pool, Product::ID).await?;
+
 // Delete by primary key, no instance needed
-Product::destroy(&pool, anvil.id).await?;
+Product::destroy(&pool, Uuid::new_v4()).await?;
 # Ok(())
 # }
 ```

docs/src/cookbook/bulk-update-and-upsert.md

@@ -189,6 +189,73 @@ let saved: Product = Product::insert()
 values from the INSERT — the SQL equivalent of
 `SET col = EXCLUDED.col` for each column.
 
+## Bulk Upsert a Collection
+
+When you have a `Vec` of models to upsert — e.g. syncing an
+external data source — use `.upsert()` to insert or update
+them all in a single statement:
+
+```rust
+# extern crate fabrique;
+# extern crate sqlx;
+# extern crate tokio;
+# extern crate uuid;
+# use fabrique::prelude::*;
+# use uuid::Uuid;
+#
+# #[derive(Clone, Debug, Factory, Model)]
+# pub struct Product {
+#     pub id: Uuid,
+#     pub name: String,
+#     pub price_cents: i32,
+#     pub in_stock: bool,
+# }
+#
+# #[fabrique::doctest]
+# async fn main(pool: Pool<Sqlite>) -> Result<(), fabrique::Error> {
+# let products = vec![
+#     Product::factory().name("Anvil 3000".to_string()).make(),
+#     Product::factory().name("Rocket Skates".to_string()).make(),
+# ];
+// Insert all products, or update on ID conflict
+products.upsert(&pool, Product::ID).await?;
+# Ok(())
+# }
+```
+
+The second argument specifies the conflict target — the column
+(or columns) that identify a unique row. All other columns are
+updated when a conflict is detected.
+
+For a composite unique key, pass a tuple:
+
+```rust,no_run
+# extern crate fabrique;
+# extern crate sqlx;
+# extern crate uuid;
+# use fabrique::prelude::*;
+# use uuid::Uuid;
+# #[derive(Clone, Debug, Factory, Model)]
+# pub struct Product {
+#     pub id: Uuid,
+#     pub name: String,
+#     pub price_cents: i32,
+#     pub in_stock: bool,
+# }
+# async fn example(
+#     products: Vec<Product>,
+#     pool: Pool<Sqlite>,
+# ) -> Result<(), fabrique::Error> {
+products
+    .upsert(&pool, (Product::NAME, Product::PRICE_CENTS))
+    .await?;
+# Ok(())
+# }
+```
+
+> **Note:** The conflict target columns must have a UNIQUE
+> constraint or be the primary key in your database schema.
+
 If you only want to skip duplicates without updating, use
 `.do_nothing()`:
 

fabrique-core/src/lib.rs

@@ -12,6 +12,7 @@ pub mod factory;
 pub mod model;
 pub mod relation;
 pub mod sql;
+pub mod upsert;
 
 // Re-export for use in generated code
 pub use database::Nil;
@@ -24,3 +25,5 @@ pub use factory::SetForeignKey;
 pub use relation::Alias;
 pub use relation::BelongsTo;
 pub use relation::Joinable;
+pub use upsert::UniqueBy;
+pub use upsert::Upsert;

fabrique-core/src/model.rs

@@ -116,6 +116,10 @@ pub trait Persist<DB: Dialect>: Model {
     ) -> impl Future<Output = Result<Self, crate::Error>> + Send + 'e
     where
         A: sqlx::Acquire<'e, Database = DB> + Send + 'e;
+
+    /// Pushes all field values as bind parameters into a separated
+    /// query builder row.
+    fn push_bind_values(self, separated: sqlx::query_builder::Separated<'_, DB, &'static str>);
 }
 
 /// Delete operations

fabrique-core/src/upsert.rs

@@ -0,0 +1,84 @@
+use crate::{
+    database::Column,
+    dialect::Dialect,
+    model::{Model, Persist},
+};
+
+pub trait UniqueBy<M> {
+    fn column_names() -> &'static [&'static str];
+}
+
+macro_rules! impl_unique_by {
+    ($($C:ident),+) => {
+        impl<M, $($C),+> UniqueBy<M> for ($($C,)+)
+        where
+            $($C: Column<M>,)+
+        {
+            fn column_names() -> &'static [&'static str] {
+                &[$($C::NAME),+]
+            }
+        }
+    };
+}
+impl_unique_by!(C0);
+impl_unique_by!(C0, C1);
+impl_unique_by!(C0, C1, C2);
+impl_unique_by!(C0, C1, C2, C3);
+
+pub trait Upsert<DB: Dialect> {
+    type Model: Model;
+
+    fn upsert<'e, A, U>(
+        self,
+        executor: A,
+        unique_by: U,
+    ) -> impl Future<Output = Result<(), crate::Error>>
+    where
+        A: sqlx::Acquire<'e, Database = DB> + Send + 'e,
+        U: UniqueBy<Self::Model>;
+}
+
+impl<M, DB> Upsert<DB> for Vec<M>
+where
+    M: Persist<DB> + Send,
+    DB: Dialect,
+    <DB as sqlx::Database>::Arguments: sqlx::IntoArguments<DB>,
+    for<'c> &'c mut <DB as sqlx::Database>::Connection: sqlx::Executor<'c, Database = DB>,
+{
+    type Model = M;
+
+    async fn upsert<'e, A, U>(self, executor: A, _unique_by: U) -> Result<(), crate::Error>
+    where
+        A: sqlx::Acquire<'e, Database = DB> + Send + 'e,
+        U: UniqueBy<M>,
+    {
+        if self.is_empty() {
+            return Ok(());
+        }
+
+        let mut conn = executor.acquire().await.map_err(crate::Error::from)?;
+
+        let mut qb = sqlx::QueryBuilder::new("INSERT INTO ");
+        qb.push(M::table_name());
+        qb.push(" (");
+        qb.push(M::columns().join(", "));
+        qb.push(") ");
+
+        qb.push_values(self, |separated, model| {
+            model.push_bind_values(separated);
+        });
+
+        let unique_cols = U::column_names();
+        qb.push(DB::on_conflict_sql(unique_cols));
+
+        let update_cols: Vec<&str> = M::columns()
+            .iter()
+            .copied()
+            .filter(|c| !unique_cols.contains(c))
+            .collect();
+        qb.push(DB::do_update_sql(&update_cols));
+
+        qb.build().execute(&mut *conn).await?;
+        Ok(())
+    }
+}

fabrique-derive/src/codegen/columns.rs

@@ -70,6 +70,12 @@ impl<'a> ColumnsCodegen<'a> {
                         #into_db_body
                     }
                 }
+
+                impl ::fabrique::UniqueBy<#base_struct_ident> for #type_name {
+                    fn column_names() -> &'static [&'static str] {
+                        &[#column_name]
+                    }
+                }
             }
         });
 
@@ -127,6 +133,13 @@ mod tests {
                         value
                     }
                 }
+
+                impl ::fabrique::UniqueBy<Anvil> for AnvilIdColumn {
+                    fn column_names() -> &'static [&'static str] {
+                        &["id"]
+                    }
+                }
+
                 impl ::fabrique::Column<Anvil> for AnvilNameColumn {
                     type Type = String;
                     type DbType = String;
@@ -139,6 +152,12 @@ mod tests {
                     }
                 }
 
+                impl ::fabrique::UniqueBy<Anvil> for AnvilNameColumn {
+                    fn column_names() -> &'static [&'static str] {
+                        &["name"]
+                    }
+                }
+
                 impl Anvil {
                     pub const ID: AnvilIdColumn = AnvilIdColumn;
                     pub const NAME: AnvilNameColumn = AnvilNameColumn;
@@ -182,6 +201,13 @@ mod tests {
                         value
                     }
                 }
+
+                impl ::fabrique::UniqueBy<Account> for AccountIdColumn {
+                    fn column_names() -> &'static [&'static str] {
+                        &["id"]
+                    }
+                }
+
                 impl ::fabrique::Column<Account> for AccountStatusColumn {
                     type Type = Status;
                     type DbType = String;
@@ -194,6 +220,12 @@ mod tests {
                     }
                 }
 
+                impl ::fabrique::UniqueBy<Account> for AccountStatusColumn {
+                    fn column_names() -> &'static [&'static str] {
+                        &["status"]
+                    }
+                }
+
                 impl Account {
                     pub const ID: AccountIdColumn = AccountIdColumn;
                     pub const STATUS: AccountStatusColumn = AccountStatusColumn;