diff options
Diffstat (limited to 'lib/sqlalchemy/orm/session.py')
| -rw-r--r-- | lib/sqlalchemy/orm/session.py | 23 |
1 files changed, 23 insertions, 0 deletions
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 1fb1a9285..e665fbdb6 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -1329,6 +1329,29 @@ class Session(object): See :ref:`unitofwork_merging` for a detailed discussion of merging. + :param instance: Instance to be merged. + :param load: Boolean, when False, :meth:`.merge` switches into + a "high performance" mode which causes it to skip all database + access. The state of the given object is transferred directly + into the :class:`.Session` without checking the database + for existing data or discrepancies. This flag is used for + cases such as transferring graphs of objects into a :class:`.Session` + from a second level cache, or to transfer just-loaded objects + into the :class:`.Session` owned by a worker thread or process + without re-querying the database. + + The ``load=False`` use case adds the caveat that the given + object has to be in a "clean" state. This is so that when + the merge operation cascades onto related objects and + collections, the related values can be "stamped" onto the + target object as is, without concern for reconciling their + contents with any existing database value. While there's no technical + reason the state of the object can't be taken as is whether or + not it's dirty, it suggests a mis-use of the method, as state which + wasn't pulled from the database originally can't reliably be passed back to + the database without knowing the database's current state. + + """ _recursive = {} |