Merge pull request #35548 from vishaltelangre/patch-1

Minor documentation fixes related to bulk insert [ci skip]

1 files changed, 13 insertions, 10 deletions

diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb
index a09b5f0e96..ba2ac7908e 100644
--- a/activerecord/lib/active_record/persistence.rb
+++ b/activerecord/lib/active_record/persistence.rb
@@ -57,7 +57,7 @@ module ActiveRecord
         end
       end
 
-      # Inserts a single record into the databases. This method constructs a single SQL INSERT
+      # Inserts a single record into the database. This method constructs a single SQL INSERT
       # statement and sends it straight to the database. It does not instantiate the involved
       # models and it does not trigger Active Record callbacks or validations. However, values
       # passed to #insert will still go through Active Record's normal type casting and
@@ -94,8 +94,8 @@ module ActiveRecord
       #
       # [:unique_by]
       #   (Postgres and SQLite only) In a table with more than one unique constraint or index,
-      #   new records may considered duplicates according to different criteria. By default,
-      #   new rows will be skipped if they violate _any_ unique constraint/index. By defining
+      #   new records may be considered duplicates according to different criteria. By default,
+      #   new rows will be skipped if they violate _any_ unique constraint or index. By defining
       #   <tt>:unique_by</tt>, you can skip rows that would create duplicates according to the given
       #   constraint but raise <tt>ActiveRecord::RecordNotUnique</tt> if rows violate other constraints.
       #
@@ -125,7 +125,7 @@ module ActiveRecord
         InsertAll.new(self, attributes, on_duplicate: :skip, returning: returning, unique_by: unique_by).execute
       end
 
-      # Inserts a single record into the databases. This method constructs a single SQL INSERT
+      # Inserts a single record into the database. This method constructs a single SQL INSERT
       # statement and sends it straight to the database. It does not instantiate the involved
       # models and it does not trigger Active Record callbacks or validations. However, values
       # passed to #insert! will still go through Active Record's normal type casting and
@@ -173,7 +173,7 @@ module ActiveRecord
       #     { title: 'Eloquent Ruby', author: 'Russ' }
       #   ])
       #
-      #   # raises ActiveRecord::RecordNotUnique because 'Eloquent Ruby'
+      #   # Raises ActiveRecord::RecordNotUnique because 'Eloquent Ruby'
       #   # does not have a unique ID
       #   Book.insert_all!([
       #     { id: 1, title: 'Rework', author: 'David' },
@@ -184,7 +184,7 @@ module ActiveRecord
         InsertAll.new(self, attributes, on_duplicate: :raise, returning: returning).execute
       end
 
-      # Upserts (inserts-or-creates) a single record into the databases. This method constructs
+      # Upserts (updates or inserts) a single record into the database. This method constructs
       # a single SQL INSERT statement and sends it straight to the database. It does not
       # instantiate the involved models and it does not trigger Active Record callbacks or
       # validations. However, values passed to #upsert will still go through Active Record's
@@ -195,7 +195,7 @@ module ActiveRecord
         upsert_all([ attributes ], returning: returning, unique_by: unique_by)
       end
 
-      # Upserts (creates-or-updates) multiple records into the database. This method constructs
+      # Upserts (updates or inserts) multiple records into the database. This method constructs
       # a single SQL INSERT statement and sends it straight to the database. It does not
       # instantiate the involved models and it does not trigger Active Record callbacks or
       # validations. However, values passed to #upsert_all will still go through Active Record's
@@ -219,11 +219,14 @@ module ActiveRecord
       #
       # [:unique_by]
       #   (Postgres and SQLite only) In a table with more than one unique constraint or index,
-      #   new records may considered duplicates according to different criteria. For MySQL,
+      #   new records may be considered duplicates according to different criteria. For MySQL,
       #   an upsert will take place if a new record violates _any_ unique constraint. For
       #   Postgres and SQLite, new rows will replace existing rows when the new row has the
-      #   same primary key as the existing row. By defining <tt>:unique_by</tt>, you can supply
-      #   a different key for matching new records to existing ones than the primary key.
+      #   same primary key as the existing row. In case of SQLite, an upsert operation causes
+      #   an insert to behave as an update or a no-op if the insert would violate
+      #   a uniqueness constraint. By defining <tt>:unique_by</tt>, you can supply
+      #   a different unique constraint for matching new records to existing ones than the
+      #   primary key.
       #
       #   (For example, if you have a unique index on the ISBN column and use that as
       #   the <tt>:unique_by</tt>, a new record with the same ISBN as an existing record