Update documentation on upsert_all so that it is correct for Postgres

Details in https://github.com/rails/rails/issues/35519

In short, MySQL and Sqlite3 allow a record to be both inserted _and_ replaced in the same operation. Postgres (and the SQL-2003 rules for MERGE) do not.

Postgres's rationale seems to be that the operation would be nondeterministic.

I think it's OK for Rails users to have a different experience with this feature depending on their database; but I think you should be able to follow the examples in the docs on any database.

1 files changed, 7 insertions, 3 deletions

diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb
index a09b5f0e96..200cfed465 100644
--- a/activerecord/lib/active_record/persistence.rb
+++ b/activerecord/lib/active_record/persistence.rb
@@ -240,11 +240,15 @@ module ActiveRecord
       #
       # ==== Examples
       #
-      #   # Insert multiple records, performing an upsert when records have duplicate ISBNs
+      #   # Given a Unique Index on books.isbn and the following record:
+      #   Book.create!(title: 'Rework', author: 'David', isbn: '1')
+      #
+      #   # Insert multiple records, allowing new records with the same ISBN
+      #   # as an existing record to overwrite the existing record.
       #   # ('Eloquent Ruby' will overwrite 'Rework' because its ISBN is duplicate)
       #   Book.upsert_all([
-      #     { title: 'Rework', author: 'David', isbn: '1' },
-      #     { title: 'Eloquent Ruby', author: 'Russ', isbn: '1' }
+      #     { title: 'Eloquent Ruby', author: 'Russ', isbn: '1' },
+      #     { title: 'Clean Code', author: 'Robert', isbn: '2' }
       #   ],
       #      unique_by: { columns: %w[ isbn ] })
       #