MONGOID-5472 Save models using the overridden storage options used for their loading (#5750)

* documents remember the active persistence context when they are instantiated

* add Mongoid.legacy_persistence_context_behavior feature flag

* update the docs to include the new feature flag

* update the release notes

* persist the storage options, not the persistence context

otherwise, we may leak client instances

* update docs too

* fix comparison with persistence context

* remembered_storage_options can be nil

* force correct storage options if reusing a persistence context for a child document

* infer correct persistence context for child record

* check argument types correctly

* add tests to ensure an explicit context overrides a remembered one

* remove artifact from previous implementation

Author: jamis

source/reference/configuration.txt

@@ -320,6 +320,30 @@ for details on driver options.
       # to parent contexts by default.
       # join_contexts: false
 
+      # When this flag is false (the default as of Mongoid 9.0), a document that
+      # is created or loaded will remember the storage options that were active
+      # when it was loaded, and will use those same options by default when
+      # saving or reloading itself.
+      #
+      # When this flag is true you'll get pre-9.0 behavior, where a document will
+      # not remember the storage options from when it was loaded/created, and
+      # subsequent updates will need to explicitly set up those options each time.
+      #
+      # For example:
+      #
+      #    record = Model.with(collection: 'other_collection') { Model.first }
+      #
+      # This will try to load the first document from 'other_collection' and
+      # instantiate it as a Model instance. Pre-9.0, the record object would
+      # not remember that it came from 'other_collection', and attempts to
+      # update it or reload it would fail unless you first remembered to
+      # explicitly specify the collection every time.
+      #
+      # As of Mongoid 9.0, the record will remember that it came from
+      # 'other_collection', and updates and reloads will automatically default
+      # to that collection, for that record object.
+      # legacy_persistence_context_behavior: false
+
       # When this flag is false, a document will become read-only only once the
       # #readonly! method is called, and an error will be raised on attempting
       # to save or update such documents, instead of just on delete. When this

source/release-notes/mongoid-9.0.txt

@@ -444,8 +444,40 @@ by running the following command:
 
 ... code-block:: bash
 
-$ ruby -ractive_support/values/time_zone \
-  -e 'puts ActiveSupport::TimeZone::MAPPING.keys'
+  $ ruby -ractive_support/values/time_zone \
+    -e 'puts ActiveSupport::TimeZone::MAPPING.keys'
+
+
+Records now remember the persistence context in which they were loaded/created
+------------------------------------------------------------------------------
+
+Consider the following code:
+
+... code-block:: ruby
+
+  record = Model.with(collection: 'other_collection') { Model.first }
+  record.update(field: 'value')
+
+Prior to Mongoid 9.0, this could would silently fail to execute the update,
+because the storage options (here, the specification of an alternate
+collection for the model) would not be remembered by the record. Thus, the
+record would be loaded from "other_collection", but when updated, would attempt
+to look for and update the document in the default collection for Model. To
+make this work, you would have had to specify the collection explicitly for
+every update.
+
+As of Mongoid 9.0, records that are created or loaded under explicit storage
+options, will remember those options (including a named client,
+a different database, or a different collection).
+
+If you need the legacy (pre-9.0) behavior, you can enable it with the following
+flag:
+
+... code-block:: ruby
+
+  Mongoid.legacy_persistence_context_behavior = true
+
+This flag defaults to false in Mongoid 9.
 
 
 Bug Fixes and Improvements