MONGOID-5363 Change #upsert to perform updating upsert rather than replacing upsert (#5492)

* MONGOID-5363 add :replace option to upsert method

* MONGOID-5363 add docs, release notes for 8.1/9.0

Author: neilshweky

docs/reference/crud.txt

@@ -51,8 +51,8 @@ operations with examples.
        has been retrieved from the database, and a* ``Hash`` *with string keys
        if it is a new document.*
 
-       *The attributes hash also contains the attributes of all embedded 
-       documents, as well as their embedded documents, etc. If an embedded 
+       *The attributes hash also contains the attributes of all embedded
+       documents, as well as their embedded documents, etc. If an embedded
        association is empty, its key will not show up in the returned hash.*
 
      -
@@ -224,9 +224,12 @@ operations with examples.
    * - ``Model#upsert``
 
        *Performs a MongoDB replace with upsert on the document. If the document
-       exists in the database, it will get overwritten with the current
-       document in the application (any attributes present in the database but
-       not in the application's document instance will be lost).
+       exists in the database and the* ``:replace`` *option is set to true, it
+       will get overwritten with the current document in the application (any
+       attributes present in the database but not in the application's document
+       instance will be lost). If the* ``:replace`` *option is false (default),
+       the document will be updated, and any attributes not in the application's
+       document will be maintained.
        If the document does not exist in the database, it will be inserted.
        Note that this only runs the* ``{before|after|around}_upsert`` *callbacks.*
      -
@@ -237,6 +240,7 @@ operations with examples.
             last_name: "Heine"
           )
           person.upsert
+          person.upsert(replace: true)
 
    * - ``Model#touch``
 

docs/release-notes.txt

@@ -9,6 +9,7 @@ Release Notes
 .. toctree::
   :titlesonly:
 
+  release-notes/mongoid-9.0
   release-notes/mongoid-8.1
   release-notes/mongoid-8.0
   release-notes/mongoid-7.5

docs/release-notes/mongoid-8.1.txt

@@ -300,3 +300,44 @@ An _id, a hash of conditions, or ``false``/``nil`` can now be included:
   Band.exists?(BSON::ObjectId('6320d96a3282a48cfce9e72c'))
   Band.exists?(false) # always false
   Band.exists?(nil) # always false
+
+
+Added ``:replace`` option to ``#upsert``
+----------------------------------------
+
+Mongoid 8.1 adds the ``:replace`` option to the ``#upsert`` method. This option
+is ``false`` by default.
+
+In Mongoid 8 and earlier, and in Mongoid 8.1 when passing ``replace: true``
+(the default) the upserted document will overwrite the current document in the
+database if it exists. Consider the following example:
+
+.. code:: ruby
+
+  existing = Player.create!(name: "Juan Soto", age: 23, team: "WAS")
+
+  player = Player.new(name: "Juan Soto", team: "SD")
+  player.id = existing.id
+  player.upsert # :replace defaults to true in 8.1
+
+  p Player.find(existing.id)
+  # => <Player _id: 633b42f43282a45fadfaaf9d, name: "Juan Soto", age: nil, team: "SD">
+
+As you can see, the value for the ``:age`` field was dropped, because the
+upsert replaced the entire document instead of just updating it. If we take the
+same example and set ``:replace`` to ``false``, however:
+
+.. code:: ruby
+
+  player.upsert(replace: false)
+
+  p Player.find(existing.id)
+  # => <Player _id: 633b42f43282a45fadfaaf9d, name: "Juan Soto", age: 23, team: "SD">
+
+This time, the value for the ``:age`` field is maintained.
+
+.. note::
+
+  The default for the ``:replace`` option will be changed to ``false`` in
+  Mongoid 9.0, therefore it is recommended to explicitly specify this option
+  while using ``#upsert`` in 8.1 for easier upgradability.

docs/release-notes/mongoid-9.0.txt

@@ -73,3 +73,16 @@ the type conversion.
 Note that in prior Mongoid versions, typecasting Date to Time during
 persistence operations was already correctly using the
 ``Mongoid.use_activesupport_time_zone`` setting.
+
+
+Flipped default for ``:replace`` option in ``#upsert``
+------------------------------------------------------
+
+Mongoid 8.1 added the ``:replace`` option to the ``#upsert`` method. This
+option was used to specify whether or not the existing document should be
+updated or replaced.
+
+Mongoid 9.0 flips the default of this flag from ``true`` => ``false``.
+
+This means that, by default, Mongoid 9 will update the existing document and
+will not replace it.

lib/mongoid/persistable.rb

@@ -161,6 +161,8 @@ def executing_atomically?
     # @param [ Object ] result The result of the operation.
     # @param [ Hash ] options The options.
     #
+    # @option options [ true | false ] :validate Whether or not to validate.
+    #
     # @return [ true ] true.
     def post_process_persist(result, options = {})
       post_persist unless result == false

lib/mongoid/persistable/upsertable.rb

@@ -10,16 +10,31 @@ module Upsertable
       # database, then Mongo will insert a new one, otherwise the fields will get
       # overwritten with new values on the existing document.
       #
+      # If the replace option is true, unspecified attributes will be dropped,
+      # and if it is false, unspecified attributes will be maintained. The
+      # replace option defaults to false in Mongoid 9.
+      #
       # @example Upsert the document.
       #   document.upsert
       #
+      # @example Upsert the document with replace.
+      #   document.upsert(replace: true)
+      #
       # @param [ Hash ] options The validation options.
       #
+      # @option options [ true | false ] :validate Whether or not to validate.
+      # @option options [ true | false ] :replace Whether or not to replace the document on upsert.
+      #
       # @return [ true ] True.
       def upsert(options = {})
         prepare_upsert(options) do
-          collection.find(atomic_selector).replace_one(
+          if options[:replace]
+            collection.find(atomic_selector).replace_one(
               as_attributes, upsert: true, session: _session)
+          else
+            collection.find(atomic_selector).update_one(
+              { "$set" => as_attributes }, upsert: true, session: _session)
+          end
         end
       end
 
@@ -36,6 +51,8 @@ def upsert(options = {})
       #
       # @param [ Hash ] options The options hash.
       #
+      # @option options [ true | false ] :validate Whether or not to validate.
+      #
       # @return [ true | false ] If the operation succeeded.
       def prepare_upsert(options = {})
         raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly

lib/mongoid/validatable.rb

@@ -44,6 +44,8 @@ def exit_validate
     #
     # @param [ Hash ] options The options to check.
     #
+    # @option options [ true | false ] :validate Whether or not to validate.
+    #
     # @return [ true | false ] If we are validating.
     def performing_validations?(options = {})
       options[:validate].nil? ? true : options[:validate]

spec/mongoid/persistable/upsertable_spec.rb

@@ -42,8 +42,10 @@
           end
         end
 
+        let(:options) { {} }
+
         before do
-          updated.upsert
+          updated.upsert(options)
         end
 
         it "updates the existing document" do
@@ -54,19 +56,46 @@
           expect(existing).to be_persisted
         end
 
-        context 'when existing document contains other fields' do
-          let!(:existing) do
-            Band.create!(name: "Photek", views: 42)
+        shared_examples "replaces the existing fields" do
+          it 'replaces the existing fields' do
+            Band.count.should == 1
+
+            existing.reload
+            existing.views.should be nil
+            existing.name.should == 'Tool'
           end
+        end
 
-          it 'removes the existing fields' do
+        shared_examples "retains the existing fields" do
+          it 'retains the existing fields' do
             Band.count.should == 1
 
             existing.reload
-            existing.views.should be nil
+            existing.views.should eq(42)
             existing.name.should == 'Tool'
           end
         end
+
+        context 'when existing document contains other fields' do
+          let!(:existing) do
+            Band.create!(name: "Photek", views: 42)
+          end
+
+          context "when not passing any options" do
+            let(:options) { {} }
+            it_behaves_like "retains the existing fields"
+          end
+
+          context "when passing replace: false" do
+            let(:options) { { replace: false } }
+            it_behaves_like "retains the existing fields"
+          end
+
+          context "when passing replace: true" do
+            let(:options) { { replace: true } }
+            it_behaves_like "replaces the existing fields"
+          end
+        end
       end
 
       context "when no matching document exists in the db" do