Merge pull request rails#43446 from sambostock/document-upsert-record…

…-timestamps

Document new `record_timestamps` option on `insert_all`

activerecord/CHANGELOG.md

@@ -1,3 +1,13 @@
+*   Automatically set timestamps on record creation during bulk insert/upsert
+
+    Prior to this change, only updates during an upsert operation (e.g. `upsert_all`) would touch timestamps (`updated_{at,on}`). Now, record creations also touch timestamp columns (`{created,updated}_{at,on}`).
+
+    This behaviour is controlled by the `<model>.record_timestamps` config, matching the behaviour of `create`, `update`, etc. It can also be overridden by using the `record_timestamps:` keyword argument.
+
+    Note that this means `upsert_all` on models with `record_timestamps = false` will no longer touch `updated_{at,on}` automatically.
+
+    *Sam Bostock*
+
 *   Don't require `role` when passing `shard` to `connected_to`.
 
     `connected_to` can now be called with a `shard` only. Note that `role` is still inherited if `connected_to` calls are nested.

activerecord/lib/active_record/persistence.rb

@@ -110,6 +110,17 @@ def insert(attributes, returning: nil, unique_by: nil, record_timestamps: nil)
       #     unique_by: %i[ author_id name ]
       #     unique_by: :index_books_on_isbn
       #
+      # [:record_timestamps]
+      #   By default, automatic setting of timestamp columns is controlled by
+      #   the model's <tt>record_timestamps</tt> config, matching typical
+      #   behavior.
+      #
+      #   To override this and force automatic setting of timestamp columns one
+      #   way or the other, pass <tt>:record_timestamps</tt>:
+      #
+      #     record_timestamps: true  # Always set timestamps automatically
+      #     record_timestamps: false # Never set timestamps automatically
+      #
       # Because it relies on the index information from the database
       # <tt>:unique_by</tt> is recommended to be paired with
       # Active Record's schema_cache.
@@ -174,6 +185,17 @@ def insert!(attributes, returning: nil, record_timestamps: nil)
       #   You can also pass an SQL string if you need more control on the return values
       #   (for example, <tt>returning: "id, name as new_name"</tt>).
       #
+      # [:record_timestamps]
+      #   By default, automatic setting of timestamp columns is controlled by
+      #   the model's <tt>record_timestamps</tt> config, matching typical
+      #   behavior.
+      #
+      #   To override this and force automatic setting of timestamp columns one
+      #   way or the other, pass <tt>:record_timestamps</tt>:
+      #
+      #     record_timestamps: true  # Always set timestamps automatically
+      #     record_timestamps: false # Never set timestamps automatically
+      #
       # ==== Examples
       #
       #   # Insert multiple records
@@ -250,6 +272,17 @@ def upsert(attributes, on_duplicate: :update, returning: nil, unique_by: nil, re
       #
       #   NOTE: in this case you must provide all the columns you want to update by yourself.
       #
+      # [:record_timestamps]
+      #   By default, automatic setting of timestamp columns is controlled by
+      #   the model's <tt>record_timestamps</tt> config, matching typical
+      #   behavior.
+      #
+      #   To override this and force automatic setting of timestamp columns one
+      #   way or the other, pass <tt>:record_timestamps</tt>:
+      #
+      #     record_timestamps: true  # Always set timestamps automatically
+      #     record_timestamps: false # Never set timestamps automatically
+      #
       # ==== Examples
       #
       #   # Inserts multiple records, performing an upsert when records have duplicate ISBNs.