From 7504a984d49732ce94dcb1c72762c452841a9149 Mon Sep 17 00:00:00 2001 From: Preston Date: Tue, 3 Mar 2026 08:30:49 -0600 Subject: [PATCH 1/2] Added documentation for new on conflict do nothing functionality for DB insert. --- docs/06-concepts/06-database/05-crud.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/06-concepts/06-database/05-crud.md b/docs/06-concepts/06-database/05-crud.md index fd43499b..e13410e1 100644 --- a/docs/06-concepts/06-database/05-crud.md +++ b/docs/06-concepts/06-database/05-crud.md @@ -43,6 +43,23 @@ var companies = await Company.db.insert(session, rows); In previous versions of Serverpod the `insert` method mutated the input object by setting the `id` field. In the example above the input variable remains unmodified after the `insert`/`insertRow` call. ::: +### Ignoring conflicts + +When inserting rows that might violate a unique constraint, you can set `ignoreConflicts` to `true` on the `insert` method. This silently skips any rows that would cause a conflict and only inserts the rest. + +```dart +var rows = [Company(name: 'Serverpod'), Company(name: 'Google')]; +var inserted = await Company.db.insert(session, rows, ignoreConflicts: true); +``` + +The method returns only the rows that were successfully inserted. If all rows conflict, an empty list is returned. + +This is useful for idempotent operations where you want to insert data without failing on duplicates. + +:::note +Under the hood, this uses PostgreSQL's `ON CONFLICT DO NOTHING`. It works with any unique constraint defined on the table, including [indexes](indexing). +::: + ## Read There are three different read operations available. From 25d74fd53ff2d30f5f15b42367e60e9ff27f7b89 Mon Sep 17 00:00:00 2001 From: Preston Date: Tue, 3 Mar 2026 08:59:28 -0600 Subject: [PATCH 2/2] Cleaned up wording around the word indexes. --- docs/06-concepts/06-database/05-crud.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/06-concepts/06-database/05-crud.md b/docs/06-concepts/06-database/05-crud.md index e13410e1..fdbde880 100644 --- a/docs/06-concepts/06-database/05-crud.md +++ b/docs/06-concepts/06-database/05-crud.md @@ -45,7 +45,7 @@ In previous versions of Serverpod the `insert` method mutated the input object b ### Ignoring conflicts -When inserting rows that might violate a unique constraint, you can set `ignoreConflicts` to `true` on the `insert` method. This silently skips any rows that would cause a conflict and only inserts the rest. +When inserting rows that might violate a unique or exclusion constraint, you can set `ignoreConflicts` to `true` on the `insert` method. Rows that would cause a unique constraint violation are silently skipped, and only the non-conflicting rows are inserted. ```dart var rows = [Company(name: 'Serverpod'), Company(name: 'Google')]; @@ -57,7 +57,7 @@ The method returns only the rows that were successfully inserted. If all rows co This is useful for idempotent operations where you want to insert data without failing on duplicates. :::note -Under the hood, this uses PostgreSQL's `ON CONFLICT DO NOTHING`. It works with any unique constraint defined on the table, including [indexes](indexing). +Under the hood, this uses PostgreSQL's `ON CONFLICT DO NOTHING`. Only unique and exclusion constraint violations are ignored — other errors such as `NOT NULL`, `CHECK`, or foreign key violations will still throw an exception. ::: ## Read