<!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>
Core Events
—
SQLAlchemy 0.8 Documentation
</title>
<!-- begin iterate through SQLA + 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 SQLA + sphinx environment css_files -->
<!-- begin layout.mako headers -->
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.8.7',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</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>
<!-- 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>
<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 0.8 Documentation" href="../index.html" />
<link rel="up" title="SQLAlchemy Core" href="index.html" />
<link rel="next" title="Custom SQL Constructs and Compilation Extension" href="compiler.html" />
<link rel="prev" title="Events" href="event.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">0.8.7</span> | Release Date: July 22, 2014
</div>
<h1>SQLAlchemy 0.8 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 0.8 Documentation</a></h3>
<p id="sidebar-paginate">
<a href="index.html" title="SQLAlchemy Core">Up</a> |
<a href="event.html" title="Events">Prev</a> |
<a href="compiler.html" title="Custom SQL Constructs and Compilation Extension">Next</a>
</p>
<p id="sidebar-topnav">
<a href="../index.html">Contents</a> |
<a href="../genindex.html">Index</a>
</p>
<div id="sidebar-search">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="12" /> <input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div id="docs-sidebar">
<h3><a href="#">
Core Events
</a></h3>
<ul>
<li><a class="reference internal" href="#">Core Events</a><ul>
<li><a class="reference internal" href="#connection-pool-events">Connection Pool Events</a></li>
<li><a class="reference internal" href="#sql-execution-and-connection-events">SQL Execution and Connection Events</a></li>
<li><a class="reference internal" href="#schema-events">Schema Events</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="docs-body" class="withsidebar" >
<div class="section" id="core-events">
<span id="core-event-toplevel"></span><h1>Core Events<a class="headerlink" href="#core-events" title="Permalink to this headline">¶</a></h1>
<p>This section describes the event interfaces provided in
SQLAlchemy Core.
For an introduction to the event listening API, see <a class="reference internal" href="event.html"><em>Events</em></a>.
ORM events are described in <a class="reference internal" href="../orm/events.html"><em>ORM Events</em></a>.</p>
<div class="versionadded">
<p><span>New in version 0.7: </span>The event system supersedes the previous system of “extension”, “listener”,
and “proxy” classes.</p>
</div>
<div class="section" id="connection-pool-events">
<h2>Connection Pool Events<a class="headerlink" href="#connection-pool-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.PoolEvents">
<em class="property">class </em><tt class="descclassname">sqlalchemy.events.</tt><tt class="descname">PoolEvents</tt><a class="headerlink" href="#sqlalchemy.events.PoolEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.event.Events</span></tt></p>
<p>Available events for <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a>.</p>
<p>The methods here define the name of an event as well
as the names of members that are passed to listener
functions.</p>
<p>e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
<span class="k">def</span> <span class="nf">my_on_checkout</span><span class="p">(</span><span class="n">dbapi_conn</span><span class="p">,</span> <span class="n">connection_rec</span><span class="p">,</span> <span class="n">connection_proxy</span><span class="p">):</span>
<span class="s">"handle an on checkout event"</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">Pool</span><span class="p">,</span> <span class="s">'checkout'</span><span class="p">,</span> <span class="n">my_on_checkout</span><span class="p">)</span></pre></div>
</div>
<p>In addition to accepting the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> class and
<a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> instances, <a class="reference internal" href="#sqlalchemy.events.PoolEvents" title="sqlalchemy.events.PoolEvents"><tt class="xref py py-class docutils literal"><span class="pre">PoolEvents</span></tt></a> also accepts
<a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> objects and the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> class as
targets, which will be resolved to the <tt class="docutils literal"><span class="pre">.pool</span></tt> attribute of the
given engine or the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> class:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">"postgresql://scott:tiger@localhost/test"</span><span class="p">)</span>
<span class="c"># will associate with engine.pool</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="s">'checkout'</span><span class="p">,</span> <span class="n">my_on_checkout</span><span class="p">)</span></pre></div>
</div>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.checkin">
<tt class="descname">checkin</tt><big>(</big><em>dbapi_connection</em>, <em>connection_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.checkin" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection returns to the pool.</p>
<p>Note that the connection may be closed, and may be None if the
connection has been invalidated. <tt class="docutils literal"><span class="pre">checkin</span></tt> will not be called
for detached connections. (They do not return to the pool.)</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.PoolEvents.checkin.params.dbapi_con"></span><strong>dbapi_con</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkin.params.dbapi_con">¶</a> – A raw DB-API connection</li>
<li><span class="target" id="sqlalchemy.events.PoolEvents.checkin.params.con_record"></span><strong>con_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkin.params.con_record">¶</a> – The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.checkout">
<tt class="descname">checkout</tt><big>(</big><em>dbapi_connection</em>, <em>connection_record</em>, <em>connection_proxy</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.checkout" title="Permalink to this definition">¶</a></dt>
<dd><p>Called when a connection is retrieved from the Pool.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.PoolEvents.checkout.params.dbapi_con"></span><strong>dbapi_con</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkout.params.dbapi_con">¶</a> – A raw DB-API connection</li>
<li><span class="target" id="sqlalchemy.events.PoolEvents.checkout.params.con_record"></span><strong>con_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkout.params.con_record">¶</a> – The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
<li><span class="target" id="sqlalchemy.events.PoolEvents.checkout.params.con_proxy"></span><strong>con_proxy</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.checkout.params.con_proxy">¶</a> – The <tt class="docutils literal"><span class="pre">_ConnectionFairy</span></tt> which manages the connection for the span of
the current checkout.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>If you raise a <a class="reference internal" href="exceptions.html#sqlalchemy.exc.DisconnectionError" title="sqlalchemy.exc.DisconnectionError"><tt class="xref py py-class docutils literal"><span class="pre">DisconnectionError</span></tt></a>, the current
connection will be disposed and a fresh connection retrieved.
Processing of all checkout listeners will abort and restart
using the new connection.</p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.connect">
<tt class="descname">connect</tt><big>(</big><em>dbapi_connection</em>, <em>connection_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called once for each new DB-API connection or Pool’s <tt class="docutils literal"><span class="pre">creator()</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.PoolEvents.connect.params.dbapi_con"></span><strong>dbapi_con</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.connect.params.dbapi_con">¶</a> – A newly connected raw DB-API connection (not a SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper).</li>
<li><span class="target" id="sqlalchemy.events.PoolEvents.connect.params.con_record"></span><strong>con_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.connect.params.con_record">¶</a> – The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.first_connect">
<tt class="descname">first_connect</tt><big>(</big><em>dbapi_connection</em>, <em>connection_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.first_connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called exactly once for the first DB-API connection.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.PoolEvents.first_connect.params.dbapi_con"></span><strong>dbapi_con</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.first_connect.params.dbapi_con">¶</a> – A newly connected raw DB-API connection (not a SQLAlchemy
<tt class="docutils literal"><span class="pre">Connection</span></tt> wrapper).</li>
<li><span class="target" id="sqlalchemy.events.PoolEvents.first_connect.params.con_record"></span><strong>con_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.first_connect.params.con_record">¶</a> – The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.PoolEvents.reset">
<tt class="descname">reset</tt><big>(</big><em>dbapi_con</em>, <em>con_record</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.PoolEvents.reset" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before the “reset” action occurs for a pooled connection.</p>
<p>This event represents
when the <tt class="docutils literal"><span class="pre">rollback()</span></tt> method is called on the DBAPI connection
before it is returned to the pool. The behavior of “reset” can
be controlled, including disabled, using the <tt class="docutils literal"><span class="pre">reset_on_return</span></tt>
pool argument.</p>
<p>The <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.reset()</span></tt></a> event is usually followed by the
<a class="reference internal" href="#sqlalchemy.events.PoolEvents.checkin" title="sqlalchemy.events.PoolEvents.checkin"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.checkin()</span></tt></a> event is called, except in those
cases where the connection is discarded immediately after reset.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.PoolEvents.reset.params.dbapi_con"></span><strong>dbapi_con</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.reset.params.dbapi_con">¶</a> – A raw DB-API connection</li>
<li><span class="target" id="sqlalchemy.events.PoolEvents.reset.params.con_record"></span><strong>con_record</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.PoolEvents.reset.params.con_record">¶</a> – The <tt class="docutils literal"><span class="pre">_ConnectionRecord</span></tt> that persistently manages the connection</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.8.</span></p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback" title="sqlalchemy.events.ConnectionEvents.rollback"><tt class="xref py py-meth docutils literal"><span class="pre">ConnectionEvents.rollback()</span></tt></a></p>
<p class="last"><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.commit" title="sqlalchemy.events.ConnectionEvents.commit"><tt class="xref py py-meth docutils literal"><span class="pre">ConnectionEvents.commit()</span></tt></a></p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="sql-execution-and-connection-events">
<h2>SQL Execution and Connection Events<a class="headerlink" href="#sql-execution-and-connection-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.ConnectionEvents">
<em class="property">class </em><tt class="descclassname">sqlalchemy.events.</tt><tt class="descname">ConnectionEvents</tt><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.event.Events</span></tt></p>
<p>Available events for <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><tt class="xref py py-class docutils literal"><span class="pre">Connectable</span></tt></a>, which includes
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> and <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>.</p>
<p>The methods here define the name of an event as well as the names of
members that are passed to listener functions.</p>
<p>An event listener can be associated with any <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><tt class="xref py py-class docutils literal"><span class="pre">Connectable</span></tt></a>
class or instance, such as an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span><span class="p">,</span> <span class="n">create_engine</span>
<span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span>
<span class="n">executemany</span><span class="p">):</span>
<span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s">"Received statement: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">statement</span><span class="p">)</span>
<span class="n">engine</span> <span class="o">=</span> <span class="n">create_engine</span><span class="p">(</span><span class="s">'postgresql://scott:tiger@localhost/test'</span><span class="p">)</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">engine</span><span class="p">,</span> <span class="s">"before_cursor_execute"</span><span class="p">,</span> <span class="n">before_cursor_execute</span><span class="p">)</span></pre></div>
</div>
<p>or with a specific <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">begin</span><span class="p">()</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
<span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="s">'before_cursor_execute'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span>
<span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
<span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s">"Received statement: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">statement</span><span class="p">)</span></pre></div>
</div>
<p>The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_execute()</span></tt></a> and <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_cursor_execute()</span></tt></a>
events can also be established with the <tt class="docutils literal"><span class="pre">retval=True</span></tt> flag, which
allows modification of the statement and parameters to be sent
to the database. The <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_cursor_execute()</span></tt></a> event is
particularly useful here to add ad-hoc string transformations, such
as comments, to all executions:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.engine</span> <span class="kn">import</span> <span class="n">Engine</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
<span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s">"before_cursor_execute"</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">comment_sql_calls</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span><span class="p">,</span>
<span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
<span class="n">statement</span> <span class="o">=</span> <span class="n">statement</span> <span class="o">+</span> <span class="s">" -- some comment"</span>
<span class="k">return</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span></pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionEvents</span></tt></a> can be established on any
combination of <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>, as well
as instances of each of those classes. Events across all
four scopes will fire off for a given instance of
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>. However, for performance reasons, the
<a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object determines at instantiation time
whether or not its parent <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> has event listeners
established. Event listeners added to the <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>
class or to an instance of <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> <em>after</em> the instantiation
of a dependent <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance will usually
<em>not</em> be available on that <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance. The newly
added listeners will instead take effect for <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>
instances created subsequent to those event listeners being
established on the parent <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> class or instance.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.events.ConnectionEvents.params.retval"></span><strong>retval=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.params.retval">¶</a> – Applies to the <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_execute()</span></tt></a> and
<a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_cursor_execute()</span></tt></a> events only. When True, the
user-defined event function must have a return value, which
is a tuple of parameters that replace the given statement
and parameters. See those methods for a description of
specific return arguments.</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span>Changed in version 0.8: </span><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionEvents</span></tt></a> can now be associated
with any <a class="reference internal" href="connections.html#sqlalchemy.engine.Connectable" title="sqlalchemy.engine.Connectable"><tt class="xref py py-class docutils literal"><span class="pre">Connectable</span></tt></a> including <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a>,
in addition to the existing support for <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>.</p>
</div>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.after_cursor_execute">
<tt class="descname">after_cursor_execute</tt><big>(</big><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>executemany</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept low-level cursor execute() events after execution.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.cursor"></span><strong>cursor</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.cursor">¶</a> – DBAPI cursor object. Will have results pending
if the statement was a SELECT, but these should not be consumed
as they will be needed by the <a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.statement"></span><strong>statement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.statement">¶</a> – string SQL statement</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.parameters"></span><strong>parameters</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.parameters">¶</a> – Dictionary, tuple, or list of parameters being
passed to the <tt class="docutils literal"><span class="pre">execute()</span></tt> or <tt class="docutils literal"><span class="pre">executemany()</span></tt> method of the
DBAPI <tt class="docutils literal"><span class="pre">cursor</span></tt>. In some cases may be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> object in use. May
be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.executemany"></span><strong>executemany</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute.params.executemany">¶</a> – boolean, if <tt class="docutils literal"><span class="pre">True</span></tt>, this is an <tt class="docutils literal"><span class="pre">executemany()</span></tt>
call, if <tt class="docutils literal"><span class="pre">False</span></tt>, this is an <tt class="docutils literal"><span class="pre">execute()</span></tt> call.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.after_execute">
<tt class="descname">after_execute</tt><big>(</big><em>conn</em>, <em>clauseelement</em>, <em>multiparams</em>, <em>params</em>, <em>result</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.after_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept high level execute() events after execute.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.clauseelement"></span><strong>clauseelement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.clauseelement">¶</a> – SQL expression construct, <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a>
instance, or string statement passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.multiparams"></span><strong>multiparams</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.multiparams">¶</a> – Multiple parameter sets, a list of dictionaries.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.params"></span><strong>params</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.params">¶</a> – Single parameter set, a single dictionary.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.after_execute.params.result"></span><strong>result</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.after_execute.params.result">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal"><span class="pre">ResultProxy</span></tt></a> generated by the execution.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.before_cursor_execute">
<tt class="descname">before_cursor_execute</tt><big>(</big><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>executemany</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept low-level cursor execute() events before execution,
receiving the string
SQL statement and DBAPI-specific parameter list to be invoked
against a cursor.</p>
<p>This event is a good choice for logging as well as late modifications
to the SQL string. It’s less ideal for parameter modifications except
for those which are specific to a target backend.</p>
<p>This event can be optionally established with the <tt class="docutils literal"><span class="pre">retval=True</span></tt>
flag. The <tt class="docutils literal"><span class="pre">statement</span></tt> and <tt class="docutils literal"><span class="pre">parameters</span></tt> arguments should be
returned as a two-tuple in this case:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s">"before_cursor_execute"</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">before_cursor_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">cursor</span><span class="p">,</span> <span class="n">statement</span><span class="p">,</span>
<span class="n">parameters</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="n">executemany</span><span class="p">):</span>
<span class="c"># do something with statement, parameters</span>
<span class="k">return</span> <span class="n">statement</span><span class="p">,</span> <span class="n">parameters</span></pre></div>
</div>
<p>See the example at <a class="reference internal" href="#sqlalchemy.events.ConnectionEvents" title="sqlalchemy.events.ConnectionEvents"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionEvents</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.cursor"></span><strong>cursor</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.cursor">¶</a> – DBAPI cursor object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.statement"></span><strong>statement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.statement">¶</a> – string SQL statement</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.parameters"></span><strong>parameters</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.parameters">¶</a> – Dictionary, tuple, or list of parameters being
passed to the <tt class="docutils literal"><span class="pre">execute()</span></tt> or <tt class="docutils literal"><span class="pre">executemany()</span></tt> method of the
DBAPI <tt class="docutils literal"><span class="pre">cursor</span></tt>. In some cases may be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> object in use. May
be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.executemany"></span><strong>executemany</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute.params.executemany">¶</a> – boolean, if <tt class="docutils literal"><span class="pre">True</span></tt>, this is an <tt class="docutils literal"><span class="pre">executemany()</span></tt>
call, if <tt class="docutils literal"><span class="pre">False</span></tt>, this is an <tt class="docutils literal"><span class="pre">execute()</span></tt> call.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>See also:</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="sqlalchemy.events.ConnectionEvents.before_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_execute()</span></tt></a></p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.after_cursor_execute" title="sqlalchemy.events.ConnectionEvents.after_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">after_cursor_execute()</span></tt></a></p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.before_execute">
<tt class="descname">before_execute</tt><big>(</big><em>conn</em>, <em>clauseelement</em>, <em>multiparams</em>, <em>params</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.before_execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept high level execute() events, receiving uncompiled
SQL constructs and other objects prior to rendering into SQL.</p>
<p>This event is good for debugging SQL compilation issues as well
as early manipulation of the parameters being sent to the database,
as the parameter lists will be in a consistent format here.</p>
<p>This event can be optionally established with the <tt class="docutils literal"><span class="pre">retval=True</span></tt>
flag. The <tt class="docutils literal"><span class="pre">clauseelement</span></tt>, <tt class="docutils literal"><span class="pre">multiparams</span></tt>, and <tt class="docutils literal"><span class="pre">params</span></tt>
arguments should be returned as a three-tuple in this case:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="nd">@event.listens_for</span><span class="p">(</span><span class="n">Engine</span><span class="p">,</span> <span class="s">"before_execute"</span><span class="p">,</span> <span class="n">retval</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">before_execute</span><span class="p">(</span><span class="n">conn</span><span class="p">,</span> <span class="n">conn</span><span class="p">,</span> <span class="n">clauseelement</span><span class="p">,</span> <span class="n">multiparams</span><span class="p">,</span> <span class="n">params</span><span class="p">):</span>
<span class="c"># do something with clauseelement, multiparams, params</span>
<span class="k">return</span> <span class="n">clauseelement</span><span class="p">,</span> <span class="n">multiparams</span><span class="p">,</span> <span class="n">params</span></pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_execute.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_execute.params.clauseelement"></span><strong>clauseelement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute.params.clauseelement">¶</a> – SQL expression construct, <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.Compiled" title="sqlalchemy.engine.interfaces.Compiled"><tt class="xref py py-class docutils literal"><span class="pre">Compiled</span></tt></a>
instance, or string statement passed to <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection.execute" title="sqlalchemy.engine.Connection.execute"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.execute()</span></tt></a>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_execute.params.multiparams"></span><strong>multiparams</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute.params.multiparams">¶</a> – Multiple parameter sets, a list of dictionaries.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.before_execute.params.params"></span><strong>params</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.before_execute.params.params">¶</a> – Single parameter set, a single dictionary.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>See also:</p>
<p><a class="reference internal" href="#sqlalchemy.events.ConnectionEvents.before_cursor_execute" title="sqlalchemy.events.ConnectionEvents.before_cursor_execute"><tt class="xref py py-meth docutils literal"><span class="pre">before_cursor_execute()</span></tt></a></p>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.begin">
<tt class="descname">begin</tt><big>(</big><em>conn</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.begin" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.events.ConnectionEvents.begin.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.begin.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.begin_twophase">
<tt class="descname">begin_twophase</tt><big>(</big><em>conn</em>, <em>xid</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.begin_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept begin_twophase() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.begin_twophase.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.begin_twophase.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.begin_twophase.params.xid"></span><strong>xid</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.begin_twophase.params.xid">¶</a> – two-phase XID identifier</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.commit">
<tt class="descname">commit</tt><big>(</big><em>conn</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.commit" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit() events, as initiated by a
<a class="reference internal" href="connections.html#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a>.</p>
<p>Note that the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> may also “auto-commit”
a DBAPI connection upon checkin, if the <tt class="docutils literal"><span class="pre">reset_on_return</span></tt>
flag is set to the value <tt class="docutils literal"><span class="pre">'commit'</span></tt>. To intercept this
commit, use the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.reset()</span></tt></a> hook.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.events.ConnectionEvents.commit.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.commit.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.commit_twophase">
<tt class="descname">commit_twophase</tt><big>(</big><em>conn</em>, <em>xid</em>, <em>is_prepared</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.commit_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept commit_twophase() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.commit_twophase.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.commit_twophase.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.commit_twophase.params.xid"></span><strong>xid</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.commit_twophase.params.xid">¶</a> – two-phase XID identifier</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.commit_twophase.params.is_prepared"></span><strong>is_prepared</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.commit_twophase.params.is_prepared">¶</a> – boolean, indicates if
<a class="reference internal" href="connections.html#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.TwoPhaseTransaction.prepare"><tt class="xref py py-meth docutils literal"><span class="pre">TwoPhaseTransaction.prepare()</span></tt></a> was called.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.dbapi_error">
<tt class="descname">dbapi_error</tt><big>(</big><em>conn</em>, <em>cursor</em>, <em>statement</em>, <em>parameters</em>, <em>context</em>, <em>exception</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.dbapi_error" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept a raw DBAPI error.</p>
<p>This event is called with the DBAPI exception instance
received from the DBAPI itself, <em>before</em> SQLAlchemy wraps the
exception with its own exception wrappers, and before any
other operations are performed on the DBAPI cursor; the
existing transaction remains in effect as well as any state
on the cursor.</p>
<p>The use case here is to inject low-level exception handling
into an <a class="reference internal" href="connections.html#sqlalchemy.engine.Engine" title="sqlalchemy.engine.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a>, typically for logging and
debugging purposes. In general, user code should <strong>not</strong> modify
any state or throw any exceptions here as this will
interfere with SQLAlchemy’s cleanup and error handling
routines.</p>
<p>Subsequent to this hook, SQLAlchemy may attempt any
number of operations on the connection/cursor, including
closing the cursor, rolling back of the transaction in the
case of connectionless execution, and disposing of the entire
connection pool if a “disconnect” was detected. The
exception is then wrapped in a SQLAlchemy DBAPI exception
wrapper and re-thrown.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.cursor"></span><strong>cursor</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.cursor">¶</a> – DBAPI cursor object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.statement"></span><strong>statement</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.statement">¶</a> – string SQL statement</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.parameters"></span><strong>parameters</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.parameters">¶</a> – Dictionary, tuple, or list of parameters being
passed to the <tt class="docutils literal"><span class="pre">execute()</span></tt> or <tt class="docutils literal"><span class="pre">executemany()</span></tt> method of the
DBAPI <tt class="docutils literal"><span class="pre">cursor</span></tt>. In some cases may be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> object in use. May
be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.dbapi_error.params.exception"></span><strong>exception</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.dbapi_error.params.exception">¶</a> – The <strong>unwrapped</strong> exception emitted directly from the
DBAPI. The class here is specific to the DBAPI module in use.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span>New in version 0.7.7.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.prepare_twophase">
<tt class="descname">prepare_twophase</tt><big>(</big><em>conn</em>, <em>xid</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.prepare_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept prepare_twophase() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.prepare_twophase.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.prepare_twophase.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.prepare_twophase.params.xid"></span><strong>xid</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.prepare_twophase.params.xid">¶</a> – two-phase XID identifier</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.release_savepoint">
<tt class="descname">release_savepoint</tt><big>(</big><em>conn</em>, <em>name</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.release_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept release_savepoint() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.release_savepoint.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.release_savepoint.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.release_savepoint.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.release_savepoint.params.name">¶</a> – specified name used for the savepoint.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.release_savepoint.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.release_savepoint.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> in use. May be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback">
<tt class="descname">rollback</tt><big>(</big><em>conn</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback() events, as initiated by a
<a class="reference internal" href="connections.html#sqlalchemy.engine.Transaction" title="sqlalchemy.engine.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a>.</p>
<p>Note that the <a class="reference internal" href="pooling.html#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> also “auto-rolls back”
a DBAPI connection upon checkin, if the <tt class="docutils literal"><span class="pre">reset_on_return</span></tt>
flag is set to its default value of <tt class="docutils literal"><span class="pre">'rollback'</span></tt>.
To intercept this
rollback, use the <a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.reset()</span></tt></a> hook.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="#sqlalchemy.events.PoolEvents.reset" title="sqlalchemy.events.PoolEvents.reset"><tt class="xref py py-meth docutils literal"><span class="pre">PoolEvents.reset()</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback_savepoint">
<tt class="descname">rollback_savepoint</tt><big>(</big><em>conn</em>, <em>name</em>, <em>context</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_savepoint() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.name">¶</a> – specified name used for the savepoint.</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.context"></span><strong>context</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_savepoint.params.context">¶</a> – <a class="reference internal" href="internals.html#sqlalchemy.engine.interfaces.ExecutionContext" title="sqlalchemy.engine.interfaces.ExecutionContext"><tt class="xref py py-class docutils literal"><span class="pre">ExecutionContext</span></tt></a> in use. May be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.rollback_twophase">
<tt class="descname">rollback_twophase</tt><big>(</big><em>conn</em>, <em>xid</em>, <em>is_prepared</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept rollback_twophase() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_twophase.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_twophase.params.xid"></span><strong>xid</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase.params.xid">¶</a> – two-phase XID identifier</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.rollback_twophase.params.is_prepared"></span><strong>is_prepared</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.rollback_twophase.params.is_prepared">¶</a> – boolean, indicates if
<a class="reference internal" href="connections.html#sqlalchemy.engine.TwoPhaseTransaction.prepare" title="sqlalchemy.engine.TwoPhaseTransaction.prepare"><tt class="xref py py-meth docutils literal"><span class="pre">TwoPhaseTransaction.prepare()</span></tt></a> was called.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.ConnectionEvents.savepoint">
<tt class="descname">savepoint</tt><big>(</big><em>conn</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.ConnectionEvents.savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Intercept savepoint() events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.savepoint.params.conn"></span><strong>conn</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.savepoint.params.conn">¶</a> – <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> object</li>
<li><span class="target" id="sqlalchemy.events.ConnectionEvents.savepoint.params.name"></span><strong>name</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.ConnectionEvents.savepoint.params.name">¶</a> – specified name used for the savepoint.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="schema-events">
<h2>Schema Events<a class="headerlink" href="#schema-events" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="sqlalchemy.events.DDLEvents">
<em class="property">class </em><tt class="descclassname">sqlalchemy.events.</tt><tt class="descname">DDLEvents</tt><a class="headerlink" href="#sqlalchemy.events.DDLEvents" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.event.Events</span></tt></p>
<p>Define event listeners for schema objects,
that is, <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a> and <tt class="xref py py-class docutils literal"><span class="pre">SchemaEvent</span></tt>
subclasses, including <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a>, <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>,
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>.</p>
<p><a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> and <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> support events
specifically regarding when CREATE and DROP
DDL is emitted to the database.</p>
<p>Attachment events are also provided to customize
behavior whenever a child schema element is associated
with a parent, such as, when a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> is associated
with its <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>, when a <a class="reference internal" href="constraints.html#sqlalchemy.schema.ForeignKeyConstraint" title="sqlalchemy.schema.ForeignKeyConstraint"><tt class="xref py py-class docutils literal"><span class="pre">ForeignKeyConstraint</span></tt></a>
is associated with a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>, etc.</p>
<p>Example using the <tt class="docutils literal"><span class="pre">after_create</span></tt> event:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">Table</span><span class="p">,</span> <span class="n">Column</span><span class="p">,</span> <span class="n">Metadata</span><span class="p">,</span> <span class="n">Integer</span>
<span class="n">m</span> <span class="o">=</span> <span class="n">MetaData</span><span class="p">()</span>
<span class="n">some_table</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span><span class="s">'some_table'</span><span class="p">,</span> <span class="n">m</span><span class="p">,</span> <span class="n">Column</span><span class="p">(</span><span class="s">'data'</span><span class="p">,</span> <span class="n">Integer</span><span class="p">))</span>
<span class="k">def</span> <span class="nf">after_create</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">connection</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
<span class="n">connection</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">"ALTER TABLE </span><span class="si">%s</span><span class="s"> SET name=foo_</span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span>
<span class="p">(</span><span class="n">target</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">target</span><span class="o">.</span><span class="n">name</span><span class="p">))</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="n">some_table</span><span class="p">,</span> <span class="s">"after_create"</span><span class="p">,</span> <span class="n">after_create</span><span class="p">)</span></pre></div>
</div>
<p>DDL events integrate closely with the
<a class="reference internal" href="ddl.html#sqlalchemy.schema.DDL" title="sqlalchemy.schema.DDL"><tt class="xref py py-class docutils literal"><span class="pre">DDL</span></tt></a> class and the <a class="reference internal" href="ddl.html#sqlalchemy.schema.DDLElement" title="sqlalchemy.schema.DDLElement"><tt class="xref py py-class docutils literal"><span class="pre">DDLElement</span></tt></a> hierarchy
of DDL clause constructs, which are themselves appropriate
as listener callables:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">DDL</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
<span class="n">some_table</span><span class="p">,</span>
<span class="s">"after_create"</span><span class="p">,</span>
<span class="n">DDL</span><span class="p">(</span><span class="s">"ALTER TABLE </span><span class="si">%(table)s</span><span class="s"> SET name=foo_</span><span class="si">%(table)s</span><span class="s">"</span><span class="p">)</span>
<span class="p">)</span></pre></div>
</div>
<p>The methods here define the name of an event as well
as the names of members that are passed to listener
functions.</p>
<p>See also:</p>
<blockquote>
<div><p><a class="reference internal" href="event.html"><em>Events</em></a></p>
<p><a class="reference internal" href="ddl.html#sqlalchemy.schema.DDLElement" title="sqlalchemy.schema.DDLElement"><tt class="xref py py-class docutils literal"><span class="pre">DDLElement</span></tt></a></p>
<p><a class="reference internal" href="ddl.html#sqlalchemy.schema.DDL" title="sqlalchemy.schema.DDL"><tt class="xref py py-class docutils literal"><span class="pre">DDL</span></tt></a></p>
<p><a class="reference internal" href="ddl.html#schema-ddl-sequences"><em>Controlling DDL Sequences</em></a></p>
</div></blockquote>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_create">
<tt class="descname">after_create</tt><big>(</big><em>target</em>, <em>connection</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after CREATE statements are emitted.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.DDLEvents.after_create.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_create.params.target">¶</a> – the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>
object which is the target of the event.</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.after_create.params.connection"></span><strong>connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_create.params.connection">¶</a> – the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> where the
CREATE statement or statements have been emitted.</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.after_create.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_create.params.**kw">¶</a> – additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_drop">
<tt class="descname">after_drop</tt><big>(</big><em>target</em>, <em>connection</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after DROP statements are emitted.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.DDLEvents.after_drop.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_drop.params.target">¶</a> – the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>
object which is the target of the event.</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.after_drop.params.connection"></span><strong>connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_drop.params.connection">¶</a> – the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> where the
DROP statement or statements have been emitted.</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.after_drop.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_drop.params.**kw">¶</a> – additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.after_parent_attach">
<tt class="descname">after_parent_attach</tt><big>(</big><em>target</em>, <em>parent</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.after_parent_attach" title="Permalink to this definition">¶</a></dt>
<dd><p>Called after a <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a> is associated with
a parent <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.DDLEvents.after_parent_attach.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_parent_attach.params.target">¶</a> – the target object</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.after_parent_attach.params.parent"></span><strong>parent</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_parent_attach.params.parent">¶</a> – the parent to which the target is being attached.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">event.listen()</span></tt></a> also accepts a modifier for this event:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.events.DDLEvents.after_parent_attach.params.propagate"></span><strong>propagate=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.after_parent_attach.params.propagate">¶</a> – When True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><tt class="xref py py-meth docutils literal"><span class="pre">Table.tometadata()</span></tt></a> is used.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_create">
<tt class="descname">before_create</tt><big>(</big><em>target</em>, <em>connection</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before CREATE statements are emitted.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.DDLEvents.before_create.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_create.params.target">¶</a> – the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>
object which is the target of the event.</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.before_create.params.connection"></span><strong>connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_create.params.connection">¶</a> – the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> where the
CREATE statement or statements will be emitted.</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.before_create.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_create.params.**kw">¶</a> – additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_drop">
<tt class="descname">before_drop</tt><big>(</big><em>target</em>, <em>connection</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_drop" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before DROP statements are emitted.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.DDLEvents.before_drop.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_drop.params.target">¶</a> – the <a class="reference internal" href="metadata.html#sqlalchemy.schema.MetaData" title="sqlalchemy.schema.MetaData"><tt class="xref py py-class docutils literal"><span class="pre">MetaData</span></tt></a> or <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>
object which is the target of the event.</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.before_drop.params.connection"></span><strong>connection</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_drop.params.connection">¶</a> – the <a class="reference internal" href="connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> where the
DROP statement or statements will be emitted.</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.before_drop.params.**kw"></span><strong>**kw</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_drop.params.**kw">¶</a> – additional keyword arguments relevant
to the event. The contents of this dictionary
may vary across releases, and include the
list of tables being generated for a metadata-level
event, the checkfirst flag, and other
elements used by internal events.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.before_parent_attach">
<tt class="descname">before_parent_attach</tt><big>(</big><em>target</em>, <em>parent</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.before_parent_attach" title="Permalink to this definition">¶</a></dt>
<dd><p>Called before a <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a> is associated with
a parent <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><span class="target" id="sqlalchemy.events.DDLEvents.before_parent_attach.params.target"></span><strong>target</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_parent_attach.params.target">¶</a> – the target object</li>
<li><span class="target" id="sqlalchemy.events.DDLEvents.before_parent_attach.params.parent"></span><strong>parent</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_parent_attach.params.parent">¶</a> – the parent to which the target is being attached.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal"><span class="pre">event.listen()</span></tt></a> also accepts a modifier for this event:</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><span class="target" id="sqlalchemy.events.DDLEvents.before_parent_attach.params.propagate"></span><strong>propagate=False</strong><a class="paramlink headerlink reference internal" href="#sqlalchemy.events.DDLEvents.before_parent_attach.params.propagate">¶</a> – When True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
<a class="reference internal" href="metadata.html#sqlalchemy.schema.Table.tometadata" title="sqlalchemy.schema.Table.tometadata"><tt class="xref py py-meth docutils literal"><span class="pre">Table.tometadata()</span></tt></a> is used.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="sqlalchemy.events.DDLEvents.column_reflect">
<tt class="descname">column_reflect</tt><big>(</big><em>inspector</em>, <em>table</em>, <em>column_info</em><big>)</big><a class="headerlink" href="#sqlalchemy.events.DDLEvents.column_reflect" title="Permalink to this definition">¶</a></dt>
<dd><p>Called for each unit of ‘column info’ retrieved when
a <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> is being reflected.</p>
<p>The dictionary of column information as returned by the
dialect is passed, and can be modified. The dictionary
is that returned in each element of the list returned
by <a class="reference internal" href="reflection.html#sqlalchemy.engine.reflection.Inspector.get_columns" title="sqlalchemy.engine.reflection.Inspector.get_columns"><tt class="xref py py-meth docutils literal"><span class="pre">reflection.Inspector.get_columns()</span></tt></a>.</p>
<p>The event is called before any action is taken against
this dictionary, and the contents can be modified.
The <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a> specific arguments <tt class="docutils literal"><span class="pre">info</span></tt>, <tt class="docutils literal"><span class="pre">key</span></tt>,
and <tt class="docutils literal"><span class="pre">quote</span></tt> can also be added to the dictionary and
will be passed to the constructor of <a class="reference internal" href="metadata.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal"><span class="pre">Column</span></tt></a>.</p>
<p>Note that this event is only meaningful if either
associated with the <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> class across the
board, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">sqlalchemy.schema</span> <span class="kn">import</span> <span class="n">Table</span>
<span class="kn">from</span> <span class="nn">sqlalchemy</span> <span class="kn">import</span> <span class="n">event</span>
<span class="k">def</span> <span class="nf">listen_for_reflect</span><span class="p">(</span><span class="n">inspector</span><span class="p">,</span> <span class="n">table</span><span class="p">,</span> <span class="n">column_info</span><span class="p">):</span>
<span class="s">"receive a column_reflect event"</span>
<span class="c"># ...</span>
<span class="n">event</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
<span class="n">Table</span><span class="p">,</span>
<span class="s">'column_reflect'</span><span class="p">,</span>
<span class="n">listen_for_reflect</span><span class="p">)</span></pre></div>
</div>
<p>...or with a specific <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a> instance using
the <tt class="docutils literal"><span class="pre">listeners</span></tt> argument:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">listen_for_reflect</span><span class="p">(</span><span class="n">inspector</span><span class="p">,</span> <span class="n">table</span><span class="p">,</span> <span class="n">column_info</span><span class="p">):</span>
<span class="s">"receive a column_reflect event"</span>
<span class="c"># ...</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">Table</span><span class="p">(</span>
<span class="s">'sometable'</span><span class="p">,</span>
<span class="n">autoload</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
<span class="n">listeners</span><span class="o">=</span><span class="p">[</span>
<span class="p">(</span><span class="s">'column_reflect'</span><span class="p">,</span> <span class="n">listen_for_reflect</span><span class="p">)</span>
<span class="p">])</span></pre></div>
</div>
<p>This because the reflection process initiated by <tt class="docutils literal"><span class="pre">autoload=True</span></tt>
completes within the scope of the constructor for <a class="reference internal" href="metadata.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="sqlalchemy.events.SchemaEventTarget">
<em class="property">class </em><tt class="descclassname">sqlalchemy.events.</tt><tt class="descname">SchemaEventTarget</tt><a class="headerlink" href="#sqlalchemy.events.SchemaEventTarget" title="Permalink to this definition">¶</a></dt>
<dd><p>Base class for elements that are the targets of <a class="reference internal" href="#sqlalchemy.events.DDLEvents" title="sqlalchemy.events.DDLEvents"><tt class="xref py py-class docutils literal"><span class="pre">DDLEvents</span></tt></a>
events.</p>
<p>This includes <a class="reference internal" href="metadata.html#sqlalchemy.schema.SchemaItem" title="sqlalchemy.schema.SchemaItem"><tt class="xref py py-class docutils literal"><span class="pre">SchemaItem</span></tt></a> as well as <a class="reference internal" href="types.html#sqlalchemy.types.SchemaType" title="sqlalchemy.types.SchemaType"><tt class="xref py py-class docutils literal"><span class="pre">SchemaType</span></tt></a>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div id="docs-bottom-navigation" class="docs-navigation-links">
Previous:
<a href="event.html" title="previous chapter">Events</a>
Next:
<a href="compiler.html" title="next chapter">Custom SQL Constructs and Compilation Extension</a>
<div id="docs-copyright">
© <a href="../copyright.html">Copyright</a> 2007-2014, the SQLAlchemy authors and contributors.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.2b1.
</div>
</div>
</div>
</body>
</html>
