<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
State Management
—
SQLAlchemy 1.2 Documentation
</title>
<!-- begin iterate through site-imported + sphinx environment css_files -->
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
<link rel="stylesheet" href="../_static/changelog.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_paramlinks.css" type="text/css" />
<!-- end iterate through site-imported + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="SQLAlchemy 1.2 Documentation" href="../index.html" />
<link rel="up" title="Using the Session" href="session.html" />
<link rel="next" title="Cascades" href="cascades.html" />
<link rel="prev" title="Session Basics" href="session_basics.html" />
<!-- end layout.mako headers -->
</head>
<body>
<div id="docs-container">
<div id="docs-top-navigation-container" class="body-background">
<div id="docs-header">
<div id="docs-version-header">
Release: <span class="version-num">1.2.19</span>
| Release Date: April 15, 2019
</div>
<h1>SQLAlchemy 1.2 Documentation</h1>
</div>
</div>
<div id="docs-body-container">
<div id="fixed-sidebar" class="withsidebar">
<div id="docs-sidebar-popout">
<h3><a href="../index.html">SQLAlchemy 1.2 Documentation</a></h3>
<p id="sidebar-topnav">
<a href="../contents.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<label>
Search terms:
<input type="text" placeholder="search..." name="q" size="12" />
</label>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<div id="sidebar-banner">
</div>
<div id="docs-sidebar-inner">
<h3>
<a href="index.html" title="SQLAlchemy ORM">SQLAlchemy ORM</a>
</h3>
<ul>
<li><span class="link-container"><a class="reference external" href="tutorial.html">Object Relational Tutorial</a></span></li>
<li><span class="link-container"><a class="reference external" href="mapper_config.html">Mapper Configuration</a></span></li>
<li><span class="link-container"><a class="reference external" href="relationships.html">Relationship Configuration</a></span></li>
<li><span class="link-container"><a class="reference external" href="loading_objects.html">Loading Objects</a></span></li>
<li><span class="link-container"><a class="reference external" href="session.html">Using the Session</a></span><ul>
<li><span class="link-container"><a class="reference external" href="session_basics.html">Session Basics</a></span></li>
<li class="selected"><span class="link-container"><strong>State Management</strong><a class="paramlink headerlink reference internal" href="#">¶</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#quickie-intro-to-object-states">Quickie Intro to Object States</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#getting-the-current-state-of-an-object">Getting the Current State of an Object</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#session-attributes">Session Attributes</a></span></li>
<li><span class="link-container"><a class="reference external" href="#session-referencing-behavior">Session Referencing Behavior</a></span></li>
<li><span class="link-container"><a class="reference external" href="#merging">Merging</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#merge-tips">Merge Tips</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="#expunging">Expunging</a></span></li>
<li><span class="link-container"><a class="reference external" href="#refreshing-expiring">Refreshing / Expiring</a></span><ul>
<li><span class="link-container"><a class="reference external" href="#what-actually-loads">What Actually Loads</a></span></li>
<li><span class="link-container"><a class="reference external" href="#when-to-expire-or-refresh">When to Expire or Refresh</a></span></li>
</ul>
</li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="cascades.html">Cascades</a></span></li>
<li><span class="link-container"><a class="reference external" href="session_transaction.html">Transactions and Connection Management</a></span></li>
<li><span class="link-container"><a class="reference external" href="persistence_techniques.html">Additional Persistence Techniques</a></span></li>
<li><span class="link-container"><a class="reference external" href="contextual.html">Contextual/Thread-local Sessions</a></span></li>
<li><span class="link-container"><a class="reference external" href="session_events.html">Tracking Object and Session Changes with Events</a></span></li>
<li><span class="link-container"><a class="reference external" href="session_api.html">Session API</a></span></li>
</ul>
</li>
<li><span class="link-container"><a class="reference external" href="extending.html">Events and Internals</a></span></li>
<li><span class="link-container"><a class="reference external" href="extensions/index.html">ORM Extensions</a></span></li>
<li><span class="link-container"><a class="reference external" href="examples.html">ORM Examples</a></span></li>
</ul>
</div>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="state-management">
<h1>State Management<a class="headerlink" href="#state-management" title="Permalink to this headline">¶</a></h1>
<div class="section" id="quickie-intro-to-object-states">
<span id="session-object-states"></span><h2>Quickie Intro to Object States<a class="headerlink" href="#quickie-intro-to-object-states" title="Permalink to this headline">¶</a></h2>
<p>It’s helpful to know the states which an instance can have within a session:</p>
<ul>
<li><p><strong>Transient</strong> - an instance that’s not in a session, and is not saved to the
database; i.e. it has no database identity. The only relationship such an
object has to the ORM is that its class has a <code class="docutils literal notranslate"><span class="pre">mapper()</span></code> associated with
it.</p></li>
<li><p><strong>Pending</strong> - when you <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add()</span></code></a> a transient
instance, it becomes pending. It still wasn’t actually flushed to the
database yet, but it will be when the next flush occurs.</p></li>
<li><p><strong>Persistent</strong> - An instance which is present in the session and has a record
in the database. You get persistent instances by either flushing so that the
pending instances become persistent, or by querying the database for
existing instances (or moving persistent instances from other sessions into
your local session).</p></li>
<li><p><strong>Deleted</strong> - An instance which has been deleted within a flush, but
the transaction has not yet completed. Objects in this state are essentially
in the opposite of “pending” state; when the session’s transaction is committed,
the object will move to the detached state. Alternatively, when
the session’s transaction is rolled back, a deleted object moves
<em>back</em> to the persistent state.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.1: </span>The ‘deleted’ state is a newly added session
object state distinct from the ‘persistent’ state.</p>
</div>
</li>
<li><p><strong>Detached</strong> - an instance which corresponds, or previously corresponded,
to a record in the database, but is not currently in any session.
The detached object will contain a database identity marker, however
because it is not associated with a session, it is unknown whether or not
this database identity actually exists in a target database. Detached
objects are safe to use normally, except that they have no ability to
load unloaded attributes or attributes that were previously marked
as “expired”.</p></li>
</ul>
<p>For a deeper dive into all possible state transitions, see the
section <a class="reference internal" href="session_events.html#session-lifecycle-events"><span class="std std-ref">Object Lifecycle Events</span></a> which describes each transition
as well as how to programmatically track each one.</p>
<div class="section" id="getting-the-current-state-of-an-object">
<h3>Getting the Current State of an Object<a class="headerlink" href="#getting-the-current-state-of-an-object" title="Permalink to this headline">¶</a></h3>
<p>The actual state of any mapped object can be viewed at any time using
the <a class="reference internal" href="../core/inspection.html#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect()</span></code></a> system:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">inspect</span>
<span class="gp">>>> </span><span class="n">insp</span> <span class="o">=</span> <span class="n">inspect</span><span class="p">(</span><span class="n">my_object</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">insp</span><span class="o">.</span><span class="n">persistent</span>
<span class="go">True</span></pre></div>
</div>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState.transient" title="sqlalchemy.orm.state.InstanceState.transient"><code class="xref py py-attr docutils literal notranslate"><span class="pre">InstanceState.transient</span></code></a></p>
<p><a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState.pending" title="sqlalchemy.orm.state.InstanceState.pending"><code class="xref py py-attr docutils literal notranslate"><span class="pre">InstanceState.pending</span></code></a></p>
<p><a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState.persistent" title="sqlalchemy.orm.state.InstanceState.persistent"><code class="xref py py-attr docutils literal notranslate"><span class="pre">InstanceState.persistent</span></code></a></p>
<p><a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState.deleted" title="sqlalchemy.orm.state.InstanceState.deleted"><code class="xref py py-attr docutils literal notranslate"><span class="pre">InstanceState.deleted</span></code></a></p>
<p><a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState.detached" title="sqlalchemy.orm.state.InstanceState.detached"><code class="xref py py-attr docutils literal notranslate"><span class="pre">InstanceState.detached</span></code></a></p>
</div>
</div>
</div>
<div class="section" id="session-attributes">
<span id="id1"></span><h2>Session Attributes<a class="headerlink" href="#session-attributes" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> itself acts somewhat like a
set-like collection. All items present may be accessed using the iterator
interface:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">obj</span> <span class="ow">in</span> <span class="n">session</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span></pre></div>
</div>
<p>And presence may be tested for using regular “contains” semantics:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">obj</span> <span class="ow">in</span> <span class="n">session</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="s2">"Object is present"</span><span class="p">)</span></pre></div>
</div>
<p>The session is also keeping track of all newly created (i.e. pending) objects,
all objects which have had changes since they were last loaded or saved (i.e.
“dirty”), and everything that’s been marked as deleted:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># pending objects recently added to the Session</span>
<span class="n">session</span><span class="o">.</span><span class="n">new</span>
<span class="c1"># persistent objects which currently have changes detected</span>
<span class="c1"># (this collection is now created on the fly each time the property is called)</span>
<span class="n">session</span><span class="o">.</span><span class="n">dirty</span>
<span class="c1"># persistent objects that have been marked as deleted via session.delete(obj)</span>
<span class="n">session</span><span class="o">.</span><span class="n">deleted</span>
<span class="c1"># dictionary of all persistent objects, keyed on their</span>
<span class="c1"># identity key</span>
<span class="n">session</span><span class="o">.</span><span class="n">identity_map</span></pre></div>
</div>
<p>(Documentation: <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.new" title="sqlalchemy.orm.session.Session.new"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Session.new</span></code></a>, <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.dirty" title="sqlalchemy.orm.session.Session.dirty"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Session.dirty</span></code></a>,
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.deleted" title="sqlalchemy.orm.session.Session.deleted"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Session.deleted</span></code></a>, <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.identity_map" title="sqlalchemy.orm.session.Session.identity_map"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Session.identity_map</span></code></a>).</p>
</div>
<div class="section" id="session-referencing-behavior">
<span id="id2"></span><h2>Session Referencing Behavior<a class="headerlink" href="#session-referencing-behavior" title="Permalink to this headline">¶</a></h2>
<p>Objects within the session are <em>weakly referenced</em>. This
means that when they are dereferenced in the outside application, they fall
out of scope from within the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> as well
and are subject to garbage collection by the Python interpreter. The
exceptions to this include objects which are pending, objects which are marked
as deleted, or persistent objects which have pending changes on them. After a
full flush, these collections are all empty, and all objects are again weakly
referenced.</p>
<p>To cause objects in the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> to remain strongly
referenced, usually a simple approach is all that’s needed. Examples
of externally managed strong-referencing behavior include loading
objects into a local dictionary keyed to their primary key, or into
lists or sets for the span of time that they need to remain
referenced. These collections can be associated with a
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>, if desired, by placing them into the
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.info" title="sqlalchemy.orm.session.Session.info"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Session.info</span></code></a> dictionary.</p>
<p>An event based approach is also feasible. A simple recipe that provides
“strong referencing” behavior for all objects as they remain within
the <a class="reference internal" href="../glossary.html#term-persistent"><span class="xref std std-term">persistent</span></a> state is as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="k">import</span> <span class="n">event</span>
<span class="k">def</span> <span class="nf">strong_reference_session</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="s2">"pending_to_persistent"</span><span class="p">)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="s2">"deleted_to_persistent"</span><span class="p">)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="s2">"detached_to_persistent"</span><span class="p">)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="s2">"loaded_as_persistent"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">strong_ref_object</span><span class="p">(</span><span class="n">sess</span><span class="p">,</span> <span class="n">instance</span><span class="p">):</span>
<span class="k">if</span> <span class="s1">'refs'</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">sess</span><span class="o">.</span><span class="n">info</span><span class="p">:</span>
<span class="n">sess</span><span class="o">.</span><span class="n">info</span><span class="p">[</span><span class="s1">'refs'</span><span class="p">]</span> <span class="o">=</span> <span class="n">refs</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">refs</span> <span class="o">=</span> <span class="n">sess</span><span class="o">.</span><span class="n">info</span><span class="p">[</span><span class="s1">'refs'</span><span class="p">]</span>
<span class="n">refs</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">instance</span><span class="p">)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="s2">"persistent_to_detached"</span><span class="p">)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="s2">"persistent_to_deleted"</span><span class="p">)</span>
<span class="nd">@event</span><span class="o">.</span><span class="n">listens_for</span><span class="p">(</span><span class="n">session</span><span class="p">,</span> <span class="s2">"persistent_to_transient"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">deref_object</span><span class="p">(</span><span class="n">sess</span><span class="p">,</span> <span class="n">instance</span><span class="p">):</span>
<span class="n">sess</span><span class="o">.</span><span class="n">info</span><span class="p">[</span><span class="s1">'refs'</span><span class="p">]</span><span class="o">.</span><span class="n">discard</span><span class="p">(</span><span class="n">instance</span><span class="p">)</span></pre></div>
</div>
<p>Above, we intercept the <a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents.pending_to_persistent" title="sqlalchemy.orm.events.SessionEvents.pending_to_persistent"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SessionEvents.pending_to_persistent()</span></code></a>,
<a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents.detached_to_persistent" title="sqlalchemy.orm.events.SessionEvents.detached_to_persistent"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SessionEvents.detached_to_persistent()</span></code></a>,
<a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents.deleted_to_persistent" title="sqlalchemy.orm.events.SessionEvents.deleted_to_persistent"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SessionEvents.deleted_to_persistent()</span></code></a> and
<a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents.loaded_as_persistent" title="sqlalchemy.orm.events.SessionEvents.loaded_as_persistent"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SessionEvents.loaded_as_persistent()</span></code></a> event hooks in order to intercept
objects as they enter the <a class="reference internal" href="../glossary.html#term-persistent"><span class="xref std std-term">persistent</span></a> transition, and the
<a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents.persistent_to_detached" title="sqlalchemy.orm.events.SessionEvents.persistent_to_detached"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SessionEvents.persistent_to_detached()</span></code></a> and
<a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents.persistent_to_deleted" title="sqlalchemy.orm.events.SessionEvents.persistent_to_deleted"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SessionEvents.persistent_to_deleted()</span></code></a> hooks to intercept
objects as they leave the persistent state.</p>
<p>The above function may be called for any <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> in order to
provide strong-referencing behavior on a per-<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> basis:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="k">import</span> <span class="n">Session</span>
<span class="n">my_session</span> <span class="o">=</span> <span class="n">Session</span><span class="p">()</span>
<span class="n">strong_reference_session</span><span class="p">(</span><span class="n">my_session</span><span class="p">)</span></pre></div>
</div>
<p>It may also be called for any <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><code class="xref py py-class docutils literal notranslate"><span class="pre">sessionmaker</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sqlalchemy.orm</span> <span class="k">import</span> <span class="n">sessionmaker</span>
<span class="n">maker</span> <span class="o">=</span> <span class="n">sessionmaker</span><span class="p">()</span>
<span class="n">strong_reference_session</span><span class="p">(</span><span class="n">maker</span><span class="p">)</span></pre></div>
</div>
</div>
<div class="section" id="merging">
<span id="unitofwork-merging"></span><h2>Merging<a class="headerlink" href="#merging" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a> transfers state from an
outside object into a new or already existing instance within a session. It
also reconciles the incoming data against the state of the
database, producing a history stream which will be applied towards the next
flush, or alternatively can be made to produce a simple “transfer” of
state without producing change history or accessing the database. Usage is as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">merged_object</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="n">existing_object</span><span class="p">)</span></pre></div>
</div>
<p>When given an instance, it follows these steps:</p>
<ul>
<li><p>It examines the primary key of the instance. If it’s present, it attempts
to locate that instance in the local identity map. If the <code class="docutils literal notranslate"><span class="pre">load=True</span></code>
flag is left at its default, it also checks the database for this primary
key if not located locally.</p></li>
<li><p>If the given instance has no primary key, or if no instance can be found
with the primary key given, a new instance is created.</p></li>
<li><p>The state of the given instance is then copied onto the located/newly
created instance. For attributes which are present on the source
instance, the value is transferred to the target instance. For mapped
attributes which aren’t present on the source, the attribute is
expired on the target instance, discarding its existing value.</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">load=True</span></code> flag is left at its default,
this copy process emits events and will load the target object’s
unloaded collections for each attribute present on the source object,
so that the incoming state can be reconciled against what’s
present in the database. If <code class="docutils literal notranslate"><span class="pre">load</span></code>
is passed as <code class="docutils literal notranslate"><span class="pre">False</span></code>, the incoming data is “stamped” directly without
producing any history.</p>
</li>
<li><p>The operation is cascaded to related objects and collections, as
indicated by the <code class="docutils literal notranslate"><span class="pre">merge</span></code> cascade (see <a class="reference internal" href="cascades.html#unitofwork-cascades"><span class="std std-ref">Cascades</span></a>).</p></li>
<li><p>The new instance is returned.</p></li>
</ul>
<p>With <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a>, the given “source”
instance is not modified nor is it associated with the target <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>,
and remains available to be merged with any number of other <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>
objects. <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a> is useful for
taking the state of any kind of object structure without regard for its
origins or current session associations and copying its state into a
new session. Here’s some examples:</p>
<ul>
<li><p>An application which reads an object structure from a file and wishes to
save it to the database might parse the file, build up the
structure, and then use
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a> to save it
to the database, ensuring that the data within the file is
used to formulate the primary key of each element of the
structure. Later, when the file has changed, the same
process can be re-run, producing a slightly different
object structure, which can then be <code class="docutils literal notranslate"><span class="pre">merged</span></code> in again,
and the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> will
automatically update the database to reflect those
changes, loading each object from the database by primary key and
then updating its state with the new state given.</p></li>
<li><p>An application is storing objects in an in-memory cache, shared by
many <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> objects simultaneously. <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a>
is used each time an object is retrieved from the cache to create
a local copy of it in each <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> which requests it.
The cached object remains detached; only its state is moved into
copies of itself that are local to individual <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>
objects.</p>
<p>In the caching use case, it’s common to use the <code class="docutils literal notranslate"><span class="pre">load=False</span></code>
flag to remove the overhead of reconciling the object’s state
with the database. There’s also a “bulk” version of
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a> called <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query.merge_result" title="sqlalchemy.orm.query.Query.merge_result"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge_result()</span></code></a>
that was designed to work with cache-extended <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><code class="xref py py-class docutils literal notranslate"><span class="pre">Query</span></code></a>
objects - see the section <a class="reference internal" href="examples.html#examples-caching"><span class="std std-ref">Dogpile Caching</span></a>.</p>
</li>
<li><p>An application wants to transfer the state of a series of objects
into a <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> maintained by a worker thread or other
concurrent system. <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a> makes a copy of each object
to be placed into this new <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>. At the end of the operation,
the parent thread/process maintains the objects it started with,
and the thread/worker can proceed with local copies of those objects.</p>
<p>In the “transfer between threads/processes” use case, the application
may want to use the <code class="docutils literal notranslate"><span class="pre">load=False</span></code> flag as well to avoid overhead and
redundant SQL queries as the data is transferred.</p>
</li>
</ul>
<div class="section" id="merge-tips">
<h3>Merge Tips<a class="headerlink" href="#merge-tips" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a> is an extremely useful method for many purposes. However,
it deals with the intricate border between objects that are transient/detached and
those that are persistent, as well as the automated transference of state.
The wide variety of scenarios that can present themselves here often require a
more careful approach to the state of objects. Common problems with merge usually involve
some unexpected state regarding the object being passed to <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a>.</p>
<p>Lets use the canonical example of the User and Address objects:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">User</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'user'</span>
<span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">(</span><span class="mi">50</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="n">addresses</span> <span class="o">=</span> <span class="n">relationship</span><span class="p">(</span><span class="s2">"Address"</span><span class="p">,</span> <span class="n">backref</span><span class="o">=</span><span class="s2">"user"</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">Address</span><span class="p">(</span><span class="n">Base</span><span class="p">):</span>
<span class="n">__tablename__</span> <span class="o">=</span> <span class="s1">'address'</span>
<span class="nb">id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">primary_key</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="n">email_address</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">String</span><span class="p">(</span><span class="mi">50</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
<span class="n">user_id</span> <span class="o">=</span> <span class="n">Column</span><span class="p">(</span><span class="n">Integer</span><span class="p">,</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="s1">'user.id'</span><span class="p">),</span> <span class="n">nullable</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span></pre></div>
</div>
<p>Assume a <code class="docutils literal notranslate"><span class="pre">User</span></code> object with one <code class="docutils literal notranslate"><span class="pre">Address</span></code>, already persistent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">u1</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'ed'</span><span class="p">,</span> <span class="n">addresses</span><span class="o">=</span><span class="p">[</span><span class="n">Address</span><span class="p">(</span><span class="n">email_address</span><span class="o">=</span><span class="s1">'ed@ed.com'</span><span class="p">)])</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">u1</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span></pre></div>
</div>
<p>We now create <code class="docutils literal notranslate"><span class="pre">a1</span></code>, an object outside the session, which we’d like
to merge on top of the existing <code class="docutils literal notranslate"><span class="pre">Address</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">existing_a1</span> <span class="o">=</span> <span class="n">u1</span><span class="o">.</span><span class="n">addresses</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">a1</span> <span class="o">=</span> <span class="n">Address</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">existing_a1</span><span class="o">.</span><span class="n">id</span><span class="p">)</span></pre></div>
</div>
<p>A surprise would occur if we said this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a1</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="n">u1</span>
<span class="gp">>>> </span><span class="n">a1</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="n">a1</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span>
<span class="go">sqlalchemy.orm.exc.FlushError: New instance <Address at 0x1298f50></span>
<span class="go">with identity key (<class '__main__.Address'>, (1,)) conflicts with</span>
<span class="go">persistent instance <Address at 0x12a25d0></span></pre></div>
</div>
<p>Why is that ? We weren’t careful with our cascades. The assignment
of <code class="docutils literal notranslate"><span class="pre">a1.user</span></code> to a persistent object cascaded to the backref of <code class="docutils literal notranslate"><span class="pre">User.addresses</span></code>
and made our <code class="docutils literal notranslate"><span class="pre">a1</span></code> object pending, as though we had added it. Now we have
<em>two</em> <code class="docutils literal notranslate"><span class="pre">Address</span></code> objects in the session:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a1</span> <span class="o">=</span> <span class="n">Address</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">a1</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="n">u1</span>
<span class="gp">>>> </span><span class="n">a1</span> <span class="ow">in</span> <span class="n">session</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">existing_a1</span> <span class="ow">in</span> <span class="n">session</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">a1</span> <span class="ow">is</span> <span class="n">existing_a1</span>
<span class="go">False</span></pre></div>
</div>
<p>Above, our <code class="docutils literal notranslate"><span class="pre">a1</span></code> is already pending in the session. The
subsequent <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a> operation essentially
does nothing. Cascade can be configured via the <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship.params.cascade" title="sqlalchemy.orm.relationship"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">cascade</span></code></a>
option on <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>, although in this case it
would mean removing the <code class="docutils literal notranslate"><span class="pre">save-update</span></code> cascade from the
<code class="docutils literal notranslate"><span class="pre">User.addresses</span></code> relationship - and usually, that behavior
is extremely convenient. The solution here would usually be to not assign
<code class="docutils literal notranslate"><span class="pre">a1.user</span></code> to an object already persistent in the target
session.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">cascade_backrefs=False</span></code> option of <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>
will also prevent the <code class="docutils literal notranslate"><span class="pre">Address</span></code> from
being added to the session via the <code class="docutils literal notranslate"><span class="pre">a1.user</span> <span class="pre">=</span> <span class="pre">u1</span></code> assignment.</p>
<p>Further detail on cascade operation is at <a class="reference internal" href="cascades.html#unitofwork-cascades"><span class="std std-ref">Cascades</span></a>.</p>
<p>Another example of unexpected state:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a1</span> <span class="o">=</span> <span class="n">Address</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">existing_a1</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">user_id</span><span class="o">=</span><span class="n">u1</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">assert</span> <span class="n">a1</span><span class="o">.</span><span class="n">user</span> <span class="ow">is</span> <span class="kc">None</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">a1</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="n">a1</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span>
<span class="go">sqlalchemy.exc.IntegrityError: (IntegrityError) address.user_id</span>
<span class="go">may not be NULL</span></pre></div>
</div>
<p>Here, we accessed a1.user, which returned its default value
of <code class="docutils literal notranslate"><span class="pre">None</span></code>, which as a result of this access, has been placed in the <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> of
our object <code class="docutils literal notranslate"><span class="pre">a1</span></code>. Normally, this operation creates no change event,
so the <code class="docutils literal notranslate"><span class="pre">user_id</span></code> attribute takes precedence during a
flush. But when we merge the <code class="docutils literal notranslate"><span class="pre">Address</span></code> object into the session, the operation
is equivalent to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">existing_a1</span><span class="o">.</span><span class="n">id</span> <span class="o">=</span> <span class="n">existing_a1</span><span class="o">.</span><span class="n">id</span>
<span class="gp">>>> </span><span class="n">existing_a1</span><span class="o">.</span><span class="n">user_id</span> <span class="o">=</span> <span class="n">u1</span><span class="o">.</span><span class="n">id</span>
<span class="gp">>>> </span><span class="n">existing_a1</span><span class="o">.</span><span class="n">user</span> <span class="o">=</span> <span class="kc">None</span></pre></div>
</div>
<p>Where above, both <code class="docutils literal notranslate"><span class="pre">user_id</span></code> and <code class="docutils literal notranslate"><span class="pre">user</span></code> are assigned to, and change events
are emitted for both. The <code class="docutils literal notranslate"><span class="pre">user</span></code> association
takes precedence, and None is applied to <code class="docutils literal notranslate"><span class="pre">user_id</span></code>, causing a failure.</p>
<p>Most <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.merge" title="sqlalchemy.orm.session.Session.merge"><code class="xref py py-meth docutils literal notranslate"><span class="pre">merge()</span></code></a> issues can be examined by first checking -
is the object prematurely in the session ?</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="o">>>></span> <span class="n">a1</span> <span class="o">=</span> <span class="n">Address</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">existing_a1</span><span class="p">,</span> <span class="n">user_id</span><span class="o">=</span><span class="n">user</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
<span class="o">>>></span> <span class="k">assert</span> <span class="n">a1</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">session</span>
<span class="o">>>></span> <span class="n">a1</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="n">a1</span><span class="p">)</span></pre></div>
</div>
<p>Or is there state on the object that we don’t want ? Examining <code class="docutils literal notranslate"><span class="pre">__dict__</span></code>
is a quick way to check:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a1</span> <span class="o">=</span> <span class="n">Address</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">existing_a1</span><span class="p">,</span> <span class="n">user_id</span><span class="o">=</span><span class="n">user</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">a1</span><span class="o">.</span><span class="n">user</span>
<span class="gp">>>> </span><span class="n">a1</span><span class="o">.</span><span class="vm">__dict__</span>
<span class="go">{'_sa_instance_state': <sqlalchemy.orm.state.InstanceState object at 0x1298d10>,</span>
<span class="go"> 'user_id': 1,</span>
<span class="go"> 'id': 1,</span>
<span class="go"> 'user': None}</span>
<span class="gp">>>> </span><span class="c1"># we don't want user=None merged, remove it</span>
<span class="gp">>>> </span><span class="k">del</span> <span class="n">a1</span><span class="o">.</span><span class="n">user</span>
<span class="gp">>>> </span><span class="n">a1</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="n">a1</span><span class="p">)</span>
<span class="gp">>>> </span><span class="c1"># success</span>
<span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span></pre></div>
</div>
</div>
</div>
<div class="section" id="expunging">
<h2>Expunging<a class="headerlink" href="#expunging" title="Permalink to this headline">¶</a></h2>
<p>Expunge removes an object from the Session, sending persistent instances to
the detached state, and pending instances to the transient state:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">expunge</span><span class="p">(</span><span class="n">obj1</span><span class="p">)</span></pre></div>
</div>
<p>To remove all items, call <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expunge_all" title="sqlalchemy.orm.session.Session.expunge_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">expunge_all()</span></code></a>
(this method was formerly known as <code class="docutils literal notranslate"><span class="pre">clear()</span></code>).</p>
</div>
<div class="section" id="refreshing-expiring">
<span id="session-expire"></span><h2>Refreshing / Expiring<a class="headerlink" href="#refreshing-expiring" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="../glossary.html#term-expiring"><span class="xref std std-term">Expiring</span></a> means that the database-persisted data held inside a series
of object attributes is erased, in such a way that when those attributes
are next accessed, a SQL query is emitted which will refresh that data from
the database.</p>
<p>When we talk about expiration of data we are usually talking about an object
that is in the <a class="reference internal" href="../glossary.html#term-persistent"><span class="xref std std-term">persistent</span></a> state. For example, if we load an object
as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">user</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">User</span><span class="p">)</span><span class="o">.</span><span class="n">filter_by</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'user1'</span><span class="p">)</span><span class="o">.</span><span class="n">first</span><span class="p">()</span></pre></div>
</div>
<p>The above <code class="docutils literal notranslate"><span class="pre">User</span></code> object is persistent, and has a series of attributes
present; if we were to look inside its <code class="docutils literal notranslate"><span class="pre">__dict__</span></code>, we’d see that state
loaded:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">user</span><span class="o">.</span><span class="vm">__dict__</span>
<span class="go">{</span>
<span class="go"> 'id': 1, 'name': u'user1',</span>
<span class="go"> '_sa_instance_state': <...>,</span>
<span class="go">}</span></pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre">id</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code> refer to those columns in the database.
<code class="docutils literal notranslate"><span class="pre">_sa_instance_state</span></code> is a non-database-persisted value used by SQLAlchemy
internally (it refers to the <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><code class="xref py py-class docutils literal notranslate"><span class="pre">InstanceState</span></code></a> for the instance.
While not directly relevant to this section, if we want to get at it,
we should use the <a class="reference internal" href="../core/inspection.html#sqlalchemy.inspection.inspect" title="sqlalchemy.inspection.inspect"><code class="xref py py-func docutils literal notranslate"><span class="pre">inspect()</span></code></a> function to access it).</p>
<p>At this point, the state in our <code class="docutils literal notranslate"><span class="pre">User</span></code> object matches that of the loaded
database row. But upon expiring the object using a method such as
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire()</span></code></a>, we see that the state is removed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">expire</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">user</span><span class="o">.</span><span class="vm">__dict__</span>
<span class="go">{'_sa_instance_state': <...>}</span></pre></div>
</div>
<p>We see that while the internal “state” still hangs around, the values which
correspond to the <code class="docutils literal notranslate"><span class="pre">id</span></code> and <code class="docutils literal notranslate"><span class="pre">name</span></code> columns are gone. If we were to access
one of these columns and are watching SQL, we’d see this:</p>
<div class="highlight-python+sql notranslate"><div class="highlight"><pre><span></span><span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">user</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<div class='show_sql'>SELECT user.id AS user_id, user.name AS user_name
FROM user
WHERE user.id = ?
(1,)
</div><span class="n">user1</span></pre></div>
</div>
<p>Above, upon accessing the expired attribute <code class="docutils literal notranslate"><span class="pre">user.name</span></code>, the ORM initiated
a <a class="reference internal" href="../glossary.html#term-lazy-load"><span class="xref std std-term">lazy load</span></a> to retrieve the most recent state from the database,
by emitting a SELECT for the user row to which this user refers. Afterwards,
the <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> is again populated:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">user</span><span class="o">.</span><span class="vm">__dict__</span>
<span class="go">{</span>
<span class="go"> 'id': 1, 'name': u'user1',</span>
<span class="go"> '_sa_instance_state': <...>,</span>
<span class="go">}</span></pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>While we are peeking inside of <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> in order to see a bit
of what SQLAlchemy does with object attributes, we <strong>should not modify</strong>
the contents of <code class="docutils literal notranslate"><span class="pre">__dict__</span></code> directly, at least as far as those attributes
which the SQLAlchemy ORM is maintaining (other attributes outside of SQLA’s
realm are fine). This is because SQLAlchemy uses <a class="reference internal" href="../glossary.html#term-descriptors"><span class="xref std std-term">descriptors</span></a> in
order to track the changes we make to an object, and when we modify <code class="docutils literal notranslate"><span class="pre">__dict__</span></code>
directly, the ORM won’t be able to track that we changed something.</p>
</div>
<p>Another key behavior of both <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">expire()</span></code></a> and <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a>
is that all un-flushed changes on an object are discarded. That is,
if we were to modify an attribute on our <code class="docutils literal notranslate"><span class="pre">User</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">user</span><span class="o">.</span><span class="n">name</span> <span class="o">=</span> <span class="s1">'user2'</span></pre></div>
</div>
<p>but then we call <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">expire()</span></code></a> without first calling <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.flush" title="sqlalchemy.orm.session.Session.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a>,
our pending value of <code class="docutils literal notranslate"><span class="pre">'user2'</span></code> is discarded:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">session</span><span class="o">.</span><span class="n">expire</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">user</span><span class="o">.</span><span class="n">name</span>
<span class="go">'user1'</span></pre></div>
</div>
<p>The <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">expire()</span></code></a> method can be used to mark as “expired” all ORM-mapped
attributes for an instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># expire all ORM-mapped attributes on obj1</span>
<span class="n">session</span><span class="o">.</span><span class="n">expire</span><span class="p">(</span><span class="n">obj1</span><span class="p">)</span></pre></div>
</div>
<p>it can also be passed a list of string attribute names, referring to specific
attributes to be marked as expired:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># expire only attributes obj1.attr1, obj1.attr2</span>
<span class="n">session</span><span class="o">.</span><span class="n">expire</span><span class="p">(</span><span class="n">obj1</span><span class="p">,</span> <span class="p">[</span><span class="s1">'attr1'</span><span class="p">,</span> <span class="s1">'attr2'</span><span class="p">])</span></pre></div>
</div>
<p>The <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a> method has a similar interface, but instead
of expiring, it emits an immediate SELECT for the object’s row immediately:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># reload all attributes on obj1</span>
<span class="n">session</span><span class="o">.</span><span class="n">refresh</span><span class="p">(</span><span class="n">obj1</span><span class="p">)</span></pre></div>
</div>
<p><a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a> also accepts a list of string attribute names,
but unlike <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">expire()</span></code></a>, expects at least one name to
be that of a column-mapped attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># reload obj1.attr1, obj1.attr2</span>
<span class="n">session</span><span class="o">.</span><span class="n">refresh</span><span class="p">(</span><span class="n">obj1</span><span class="p">,</span> <span class="p">[</span><span class="s1">'attr1'</span><span class="p">,</span> <span class="s1">'attr2'</span><span class="p">])</span></pre></div>
</div>
<p>The <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire_all()</span></code></a> method allows us to essentially call
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire()</span></code></a> on all objects contained within the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>
at once:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">session</span><span class="o">.</span><span class="n">expire_all</span><span class="p">()</span></pre></div>
</div>
<div class="section" id="what-actually-loads">
<h3>What Actually Loads<a class="headerlink" href="#what-actually-loads" title="Permalink to this headline">¶</a></h3>
<p>The SELECT statement that’s emitted when an object marked with <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">expire()</span></code></a>
or loaded with <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a> varies based on several factors, including:</p>
<ul class="simple">
<li><p>The load of expired attributes is triggered from <strong>column-mapped attributes only</strong>.
While any kind of attribute can be marked as expired, including a
<a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a> - mapped attribute, accessing an expired <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>
attribute will emit a load only for that attribute, using standard
relationship-oriented lazy loading. Column-oriented attributes, even if
expired, will not load as part of this operation, and instead will load when
any column-oriented attribute is accessed.</p></li>
<li><p><a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a>- mapped attributes will not load in response to
expired column-based attributes being accessed.</p></li>
<li><p>Regarding relationships, <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a> is more restrictive than
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">expire()</span></code></a> with regards to attributes that aren’t column-mapped.
Calling <a class="reference internal" href="events.html#sqlalchemy.orm.events.InstanceEvents.refresh" title="sqlalchemy.orm.events.InstanceEvents.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a> and passing a list of names that only includes
relationship-mapped attributes will actually raise an error.
In any case, non-eager-loading <a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a> attributes will not be
included in any refresh operation.</p></li>
<li><p><a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><code class="xref py py-func docutils literal notranslate"><span class="pre">relationship()</span></code></a> attributes configured as “eager loading” via the
<a class="reference internal" href="relationship_api.html#sqlalchemy.orm.relationship.params.lazy" title="sqlalchemy.orm.relationship"><code class="xref py py-paramref docutils literal notranslate"><span class="pre">lazy</span></code></a> parameter will load in the case of
<a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a>, if either no attribute names are specified, or
if their names are included in the list of attributes to be
refreshed.</p></li>
<li><p>Attributes that are configured as <a class="reference internal" href="loading_columns.html#sqlalchemy.orm.deferred" title="sqlalchemy.orm.deferred"><code class="xref py py-func docutils literal notranslate"><span class="pre">deferred()</span></code></a> will not normally load,
during either the expired-attribute load or during a refresh.
An unloaded attribute that’s <a class="reference internal" href="loading_columns.html#sqlalchemy.orm.deferred" title="sqlalchemy.orm.deferred"><code class="xref py py-func docutils literal notranslate"><span class="pre">deferred()</span></code></a> instead loads on its own when directly
accessed, or if part of a “group” of deferred attributes where an unloaded
attribute in that group is accessed.</p></li>
<li><p>For expired attributes that are loaded on access, a joined-inheritance table
mapping will emit a SELECT that typically only includes those tables for which
unloaded attributes are present. The action here is sophisticated enough
to load only the parent or child table, for example, if the subset of columns
that were originally expired encompass only one or the other of those tables.</p></li>
<li><p>When <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a> is used on a joined-inheritance table mapping,
the SELECT emitted will resemble that of when <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.query" title="sqlalchemy.orm.session.Session.query"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.query()</span></code></a> is
used on the target object’s class. This is typically all those tables that
are set up as part of the mapping.</p></li>
</ul>
</div>
<div class="section" id="when-to-expire-or-refresh">
<h3>When to Expire or Refresh<a class="headerlink" href="#when-to-expire-or-refresh" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a> uses the expiration feature automatically whenever
the transaction referred to by the session ends. Meaning, whenever <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.commit" title="sqlalchemy.orm.session.Session.commit"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.commit()</span></code></a>
or <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.rollback" title="sqlalchemy.orm.session.Session.rollback"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.rollback()</span></code></a> is called, all objects within the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>
are expired, using a feature equivalent to that of the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire_all()</span></code></a>
method. The rationale is that the end of a transaction is a
demarcating point at which there is no more context available in order to know
what the current state of the database is, as any number of other transactions
may be affecting it. Only when a new transaction starts can we again have access
to the current state of the database, at which point any number of changes
may have occurred.</p>
<div class="sidebar">
<p class="sidebar-title">Transaction Isolation</p>
<p>Of course, most databases are capable of handling
multiple transactions at once, even involving the same rows of data. When
a relational database handles multiple transactions involving the same
tables or rows, this is when the <a class="reference internal" href="../glossary.html#term-isolation"><span class="xref std std-term">isolation</span></a> aspect of the database comes
into play. The isolation behavior of different databases varies considerably
and even on a single database can be configured to behave in different ways
(via the so-called <span class="xref std std-term">isolation level</span> setting). In that sense, the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><code class="xref py py-class docutils literal notranslate"><span class="pre">Session</span></code></a>
can’t fully predict when the same SELECT statement, emitted a second time,
will definitely return the data we already have, or will return new data.
So as a best guess, it assumes that within the scope of a transaction, unless
it is known that a SQL expression has been emitted to modify a particular row,
there’s no need to refresh a row unless explicitly told to do so.</p>
</div>
<p>The <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire()</span></code></a> and <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.refresh()</span></code></a> methods are used in
those cases when one wants to force an object to re-load its data from the
database, in those cases when it is known that the current state of data
is possibly stale. Reasons for this might include:</p>
<ul class="simple">
<li><p>some SQL has been emitted within the transaction outside of the
scope of the ORM’s object handling, such as if a <a class="reference internal" href="../core/metadata.html#sqlalchemy.schema.Table.update" title="sqlalchemy.schema.Table.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Table.update()</span></code></a> construct
were emitted using the <a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.execute" title="sqlalchemy.orm.session.Session.execute"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.execute()</span></code></a> method;</p></li>
<li><p>if the application
is attempting to acquire data that is known to have been modified in a
concurrent transaction, and it is also known that the isolation rules in effect
allow this data to be visible.</p></li>
</ul>
<p>The second bullet has the important caveat that “it is also known that the isolation rules in effect
allow this data to be visible.” This means that it cannot be assumed that an
UPDATE that happened on another database connection will yet be visible here
locally; in many cases, it will not. This is why if one wishes to use
<a class="reference internal" href="events.html#sqlalchemy.orm.events.InstanceEvents.expire" title="sqlalchemy.orm.events.InstanceEvents.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">expire()</span></code></a> or <a class="reference internal" href="events.html#sqlalchemy.orm.events.InstanceEvents.refresh" title="sqlalchemy.orm.events.InstanceEvents.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">refresh()</span></code></a> in order to view data between ongoing
transactions, an understanding of the isolation behavior in effect is essential.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire" title="sqlalchemy.orm.session.Session.expire"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire()</span></code></a></p>
<p><a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.expire_all" title="sqlalchemy.orm.session.Session.expire_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.expire_all()</span></code></a></p>
<p><a class="reference internal" href="session_api.html#sqlalchemy.orm.session.Session.refresh" title="sqlalchemy.orm.session.Session.refresh"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Session.refresh()</span></code></a></p>
<p><a class="reference internal" href="../glossary.html#term-isolation"><span class="xref std std-term">isolation</span></a> - glossary explanation of isolation which includes links
to Wikipedia.</p>
<p><a class="reference external" href="http://techspot.zzzeek.org/2012/11/14/pycon-canada-the-sqlalchemy-session-in-depth/">The SQLAlchemy Session In-Depth</a> - a video + slides with an in-depth discussion of the object
lifecycle including the role of data expiration.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links, withsidebar">
Previous:
<a href="session_basics.html" title="previous chapter">Session Basics</a>
Next:
<a href="cascades.html" title="next chapter">Cascades</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2019, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
</div>
</div>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.2.19',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<!-- begin iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<!-- end iterate through sphinx environment script_files -->
<script type="text/javascript" src="../_static/detectmobile.js"></script>
<script type="text/javascript" src="../_static/init.js"></script>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
b0b6ffab06cbeede296e36ce94734bf8
>
files
>
868
