10
— SQLAlchemy 0.6.8 Documentation</title>
10
— SQLAlchemy 0.7 Documentation</title>
12
12
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
13
13
<link rel="stylesheet" href="../_static/docs.css" type="text/css" />
27
27
<link rel="index" title="Index" href="../genindex.html" />
28
28
<link rel="search" title="Search" href="../search.html" />
29
29
<link rel="copyright" title="Copyright" href="../copyright.html" />
30
<link rel="top" title="SQLAlchemy 0.6.8 Documentation" href="../index.html" />
30
<link rel="top" title="SQLAlchemy 0.7 Documentation" href="../index.html" />
31
31
<link rel="up" title="SQLAlchemy Core" href="index.html" />
32
32
<link rel="next" title="Schema Definition Language" href="schema.html" />
33
33
<link rel="prev" title="Working with Engines and Connections" href="connections.html" />
52
52
<div class="versionheader">
53
Version: <span class="versionnum">0.6.8</span> Last Updated: 06/05/2011 13:10:26
53
Release: <span class="versionnum">0.7.2</span> | Release Date: July 31, 2011
55
55
<div class="clearboth"></div>
90
90
<li><a class="reference internal" href="#using-a-custom-connection-function">Using a Custom Connection Function</a></li>
91
91
<li><a class="reference internal" href="#constructing-a-pool">Constructing a Pool</a></li>
92
92
<li><a class="reference internal" href="#pool-event-listeners">Pool Event Listeners</a></li>
93
<li><a class="reference internal" href="#builtin-pool-implementations">Builtin Pool Implementations</a></li>
93
<li><a class="reference internal" href="#api-documentation-available-pool-implementations">API Documentation - Available Pool Implementations</a></li>
94
94
<li><a class="reference internal" href="#pooling-plain-db-api-connections">Pooling Plain DB-API Connections</a></li>
130
130
<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://me@localhost/mydb'</span><span class="p">,</span>
131
131
<span class="n">pool_size</span><span class="o">=</span><span class="mi">20</span><span class="p">,</span> <span class="n">max_overflow</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span></pre></div>
133
<p>In the case of SQLite, a <a class="reference internal" href="#sqlalchemy.pool.SingletonThreadPool" title="sqlalchemy.pool.SingletonThreadPool"><tt class="xref py py-class docutils literal"><span class="pre">SingletonThreadPool</span></tt></a> is provided instead,
134
to provide compatibility with SQLite’s restricted threading model, as well
135
as to provide a reasonable default behavior to SQLite “memory” databases,
136
which maintain their entire dataset within the scope of a single connection.</p>
133
<p>In the case of SQLite, the <a class="reference internal" href="#sqlalchemy.pool.SingletonThreadPool" title="sqlalchemy.pool.SingletonThreadPool"><tt class="xref py py-class docutils literal"><span class="pre">SingletonThreadPool</span></tt></a> or
134
<a class="reference internal" href="#sqlalchemy.pool.NullPool" title="sqlalchemy.pool.NullPool"><tt class="xref py py-class docutils literal"><span class="pre">NullPool</span></tt></a> are selected by the dialect to provide
135
greater compatibility with SQLite’s threading and locking
136
model, as well as to provide a reasonable default behavior
137
to SQLite “memory” databases, which maintain their entire
138
dataset within the scope of a single connection.</p>
137
139
<p>All SQLAlchemy pool implementations have in common
138
140
that none of them “pre create” connections - all implementations wait
139
141
until first use before creating a connection. At that point, if
230
232
upon first connect, upon each new connection, and upon checkout and
231
233
checkin of connections. See <a class="reference internal" href="interfaces.html#sqlalchemy.interfaces.PoolListener" title="sqlalchemy.interfaces.PoolListener"><tt class="xref py py-class docutils literal"><span class="pre">PoolListener</span></tt></a> for details.</p>
233
<div class="section" id="builtin-pool-implementations">
234
<h2>Builtin Pool Implementations<a class="headerlink" href="#builtin-pool-implementations" title="Permalink to this headline">¶</a></h2>
235
<div class="section" id="api-documentation-available-pool-implementations">
236
<h2>API Documentation - Available Pool Implementations<a class="headerlink" href="#api-documentation-available-pool-implementations" title="Permalink to this headline">¶</a></h2>
235
237
<dl class="class">
236
238
<dt id="sqlalchemy.pool.Pool">
237
<em class="property">class </em><tt class="descclassname">sqlalchemy.pool.</tt><tt class="descname">Pool</tt><big>(</big><em>creator</em>, <em>recycle=-1</em>, <em>echo=None</em>, <em>use_threadlocal=False</em>, <em>logging_name=None</em>, <em>reset_on_return=True</em>, <em>listeners=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.Pool" title="Permalink to this definition">¶</a></dt>
239
<em class="property">class </em><tt class="descclassname">sqlalchemy.pool.</tt><tt class="descname">Pool</tt><big>(</big><em>creator</em>, <em>recycle=-1</em>, <em>echo=None</em>, <em>use_threadlocal=False</em>, <em>logging_name=None</em>, <em>reset_on_return=True</em>, <em>listeners=None</em>, <em>events=None</em>, <em>_dispatch=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.Pool" title="Permalink to this definition">¶</a></dt>
238
240
<dd><p>Abstract base class for connection pools.</p>
239
241
<dl class="method">
240
242
<dt id="sqlalchemy.pool.Pool.__init__">
241
<tt class="descname">__init__</tt><big>(</big><em>creator</em>, <em>recycle=-1</em>, <em>echo=None</em>, <em>use_threadlocal=False</em>, <em>logging_name=None</em>, <em>reset_on_return=True</em>, <em>listeners=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.Pool.__init__" title="Permalink to this definition">¶</a></dt>
243
<tt class="descname">__init__</tt><big>(</big><em>creator</em>, <em>recycle=-1</em>, <em>echo=None</em>, <em>use_threadlocal=False</em>, <em>logging_name=None</em>, <em>reset_on_return=True</em>, <em>listeners=None</em>, <em>events=None</em>, <em>_dispatch=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.Pool.__init__" title="Permalink to this definition">¶</a></dt>
242
244
<dd><p>Construct a Pool.</p>
243
245
<table class="docutils field-list" frame="void" rules="none">
244
246
<col class="field-name" />
273
275
connections returned to the pool. This is typically a
274
276
ROLLBACK to release locks and transaction resources.
275
277
Disable at your own peril. Defaults to True.</li>
276
<li><strong>listeners</strong> – A list of
278
<li><strong>events</strong> – a list of 2-tuples, each of the form
279
<tt class="docutils literal"><span class="pre">(callable,</span> <span class="pre">target)</span></tt> which will be passed to event.listen()
280
upon construction. Provided here so that event listeners
281
can be assigned via <tt class="docutils literal"><span class="pre">create_engine</span></tt> before dialect-level
282
listeners are applied.</li>
283
<li><strong>listeners</strong> – Deprecated. A list of
277
284
<a class="reference internal" href="interfaces.html#sqlalchemy.interfaces.PoolListener" title="sqlalchemy.interfaces.PoolListener"><tt class="xref py py-class docutils literal"><span class="pre">PoolListener</span></tt></a>-like objects or
278
285
dictionaries of callables that receive events when DB-API
279
286
connections are created, checked out and checked in to the
287
pool. This has been superseded by
288
<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">listen()</span></tt></a>.</li>
320
328
<dt id="sqlalchemy.pool.QueuePool">
321
329
<em class="property">class </em><tt class="descclassname">sqlalchemy.pool.</tt><tt class="descname">QueuePool</tt><big>(</big><em>creator</em>, <em>pool_size=5</em>, <em>max_overflow=10</em>, <em>timeout=30</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.QueuePool" title="Permalink to this definition">¶</a></dt>
322
330
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.pool.Pool</span></tt></a></p>
323
<p>A Pool that imposes a limit on the number of open connections.</p>
331
<p>A <a class="reference internal" href="#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> that imposes a limit on the number of open connections.</p>
332
<p><a class="reference internal" href="#sqlalchemy.pool.QueuePool" title="sqlalchemy.pool.QueuePool"><tt class="xref py py-class docutils literal"><span class="pre">QueuePool</span></tt></a> is the default pooling implementation used for
333
all <a class="reference internal" href="connections.html#sqlalchemy.engine.base.Engine" title="sqlalchemy.engine.base.Engine"><tt class="xref py py-class docutils literal"><span class="pre">Engine</span></tt></a> objects, unless the SQLite dialect is in use.</p>
324
334
<dl class="method">
325
335
<dt id="sqlalchemy.pool.QueuePool.__init__">
326
336
<tt class="descname">__init__</tt><big>(</big><em>creator</em>, <em>pool_size=5</em>, <em>max_overflow=10</em>, <em>timeout=30</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.QueuePool.__init__" title="Permalink to this definition">¶</a></dt>
397
407
<p>A Pool that maintains one connection per thread.</p>
398
408
<p>Maintains one connection per each thread, never moving a connection to a
399
409
thread other than the one which it was created in.</p>
400
<p>This is used for SQLite, which both does not handle multithreading by
401
default, and also requires a singleton connection if a :memory: database
403
410
<p>Options are the same as those of <a class="reference internal" href="#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a>, as well as:</p>
404
411
<table class="docutils field-list" frame="void" rules="none">
405
412
<col class="field-name" />
420
<p><a class="reference internal" href="#sqlalchemy.pool.SingletonThreadPool" title="sqlalchemy.pool.SingletonThreadPool"><tt class="xref py py-class docutils literal"><span class="pre">SingletonThreadPool</span></tt></a> is used by the SQLite dialect
421
automatically when a memory-based database is used.
422
See <a class="reference internal" href="../dialects/sqlite.html"><em>SQLite</em></a>.</p>
413
423
<dl class="method">
414
424
<dt id="sqlalchemy.pool.SingletonThreadPool.__init__">
415
425
<tt class="descname">__init__</tt><big>(</big><em>creator</em>, <em>pool_size=5</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.SingletonThreadPool.__init__" title="Permalink to this definition">¶</a></dt>
421
431
<dt id="sqlalchemy.pool.AssertionPool">
422
432
<em class="property">class </em><tt class="descclassname">sqlalchemy.pool.</tt><tt class="descname">AssertionPool</tt><big>(</big><em>*args</em>, <em>**kw</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.AssertionPool" title="Permalink to this definition">¶</a></dt>
423
433
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.pool.Pool</span></tt></a></p>
424
<p>A Pool that allows at most one checked out connection at any given
434
<p>A <a class="reference internal" href="#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">Pool</span></tt></a> that allows at most one checked out connection at any given
426
436
<p>This will raise an exception if more than one connection is checked out
427
437
at a time. Useful for debugging code that is using more connections
428
438
than desired.</p>
439
<p><a class="reference internal" href="#sqlalchemy.pool.AssertionPool" title="sqlalchemy.pool.AssertionPool"><tt class="xref py py-class docutils literal"><span class="pre">AssertionPool</span></tt></a> also logs a traceback of where
440
the original connection was checked out, and reports
441
this in the assertion error raised (new in 0.7).</p>
431
444
<dl class="class">
432
445
<dt id="sqlalchemy.pool.NullPool">
433
<em class="property">class </em><tt class="descclassname">sqlalchemy.pool.</tt><tt class="descname">NullPool</tt><big>(</big><em>creator</em>, <em>recycle=-1</em>, <em>echo=None</em>, <em>use_threadlocal=False</em>, <em>logging_name=None</em>, <em>reset_on_return=True</em>, <em>listeners=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.NullPool" title="Permalink to this definition">¶</a></dt>
446
<em class="property">class </em><tt class="descclassname">sqlalchemy.pool.</tt><tt class="descname">NullPool</tt><big>(</big><em>creator</em>, <em>recycle=-1</em>, <em>echo=None</em>, <em>use_threadlocal=False</em>, <em>logging_name=None</em>, <em>reset_on_return=True</em>, <em>listeners=None</em>, <em>events=None</em>, <em>_dispatch=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.NullPool" title="Permalink to this definition">¶</a></dt>
434
447
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.pool.Pool</span></tt></a></p>
435
448
<p>A Pool which does not pool connections.</p>
436
449
<p>Instead it literally opens and closes the underlying DB-API connection
438
451
<p>Reconnect-related functions such as <tt class="docutils literal"><span class="pre">recycle</span></tt> and connection
439
452
invalidation are not supported by this Pool implementation, since
440
453
no connections are held persistently.</p>
454
<p><a class="reference internal" href="#sqlalchemy.pool.NullPool" title="sqlalchemy.pool.NullPool"><tt class="xref py py-class docutils literal"><span class="pre">NullPool</span></tt></a> is used by the SQlite dilalect automatically
455
when a file-based database is used (as of SQLAlchemy 0.7).
456
See <a class="reference internal" href="../dialects/sqlite.html"><em>SQLite</em></a>.</p>
443
459
<dl class="class">
444
460
<dt id="sqlalchemy.pool.StaticPool">
445
<em class="property">class </em><tt class="descclassname">sqlalchemy.pool.</tt><tt class="descname">StaticPool</tt><big>(</big><em>creator</em>, <em>recycle=-1</em>, <em>echo=None</em>, <em>use_threadlocal=False</em>, <em>logging_name=None</em>, <em>reset_on_return=True</em>, <em>listeners=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.StaticPool" title="Permalink to this definition">¶</a></dt>
461
<em class="property">class </em><tt class="descclassname">sqlalchemy.pool.</tt><tt class="descname">StaticPool</tt><big>(</big><em>creator</em>, <em>recycle=-1</em>, <em>echo=None</em>, <em>use_threadlocal=False</em>, <em>logging_name=None</em>, <em>reset_on_return=True</em>, <em>listeners=None</em>, <em>events=None</em>, <em>_dispatch=None</em><big>)</big><a class="headerlink" href="#sqlalchemy.pool.StaticPool" title="Permalink to this definition">¶</a></dt>
446
462
<dd><p>Bases: <a class="reference internal" href="#sqlalchemy.pool.Pool" title="sqlalchemy.pool.Pool"><tt class="xref py py-class docutils literal"><span class="pre">sqlalchemy.pool.Pool</span></tt></a></p>
447
463
<p>A Pool of exactly one connection, used for all requests.</p>
448
464
<p>Reconnect-related functions such as <tt class="docutils literal"><span class="pre">recycle</span></tt> and connection
added
removed
doc/core/pooling.html
