<!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>FDB Reference — FDB 1.1 documentation</title>
<link rel="stylesheet" href="_static/fdbtheme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<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>
<link rel="top" title="FDB 1.1 documentation" href="index.html" />
<link rel="next" title="Changelog" href="changelog.html" />
<link rel="prev" title="Differences from KInterbasDB" href="differences-from-kdb.html" />
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&subset=latin" type="text/css" media="screen" charset="utf-8" />
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Nobile:regular,italic,bold,bolditalic&subset=latin" type="text/css" media="screen" charset="utf-8" />
<!--[if lte IE 6]>
<link rel="stylesheet" href="_static/ie6.css" type="text/css" media="screen" charset="utf-8" />
<![endif]-->
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="changelog.html" title="Changelog"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="differences-from-kdb.html" title="Differences from KInterbasDB"
accesskey="P">previous</a> |</li>
<li><a href="index.html">FDB 1.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-fdb">
<span id="fdb-reference"></span><h1>FDB Reference<a class="headerlink" href="#module-fdb" title="Permalink to this headline">¶</a></h1>
<div class="section" id="module-globals">
<h2>Module globals<a class="headerlink" href="#module-globals" title="Permalink to this headline">¶</a></h2>
<dl class="data">
<dt id="fdb.__version__">
<tt class="descclassname">fdb.</tt><tt class="descname">__version__</tt><a class="headerlink" href="#fdb.__version__" title="Permalink to this definition">¶</a></dt>
<dd><p>Current driver version, string.</p>
</dd></dl>
<dl class="data">
<dt id="fdb.apilevel">
<tt class="descclassname">fdb.</tt><tt class="descname">apilevel</tt><a class="headerlink" href="#fdb.apilevel" title="Permalink to this definition">¶</a></dt>
<dd><p>String constant stating the supported DB API level (2.0).</p>
</dd></dl>
<dl class="data">
<dt id="fdb.threadsafety">
<tt class="descclassname">fdb.</tt><tt class="descname">threadsafety</tt><a class="headerlink" href="#fdb.threadsafety" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer constant stating the level of thread safety the interface supports.</p>
<p>Curretly <cite>1</cite> = Threads may share the module, but not connections.</p>
</dd></dl>
<dl class="data">
<dt id="fdb.paramstyle">
<tt class="descclassname">fdb.</tt><tt class="descname">paramstyle</tt><a class="headerlink" href="#fdb.paramstyle" title="Permalink to this definition">¶</a></dt>
<dd><p>String constant stating the type of parameter marker
formatting expected by the interface.</p>
<p><cite>‘qmark’</cite> = Question mark style, e.g. ‘...WHERE name=?’</p>
</dd></dl>
<dl class="data">
<dt id="fdb.DESCRIPTION_NAME">
<tt class="descclassname">fdb.</tt><tt class="descname">DESCRIPTION_NAME</tt><a class="headerlink" href="#fdb.DESCRIPTION_NAME" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.DESCRIPTION_TYPE_CODE">
<tt class="descclassname">fdb.</tt><tt class="descname">DESCRIPTION_TYPE_CODE</tt><a class="headerlink" href="#fdb.DESCRIPTION_TYPE_CODE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.DESCRIPTION_DISPLAY_SIZE">
<tt class="descclassname">fdb.</tt><tt class="descname">DESCRIPTION_DISPLAY_SIZE</tt><a class="headerlink" href="#fdb.DESCRIPTION_DISPLAY_SIZE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.DESCRIPTION_INTERNAL_SIZE">
<tt class="descclassname">fdb.</tt><tt class="descname">DESCRIPTION_INTERNAL_SIZE</tt><a class="headerlink" href="#fdb.DESCRIPTION_INTERNAL_SIZE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.DESCRIPTION_PRECISION">
<tt class="descclassname">fdb.</tt><tt class="descname">DESCRIPTION_PRECISION</tt><a class="headerlink" href="#fdb.DESCRIPTION_PRECISION" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.DESCRIPTION_SCALE">
<tt class="descclassname">fdb.</tt><tt class="descname">DESCRIPTION_SCALE</tt><a class="headerlink" href="#fdb.DESCRIPTION_SCALE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.DESCRIPTION_NULL_OK">
<tt class="descclassname">fdb.</tt><tt class="descname">DESCRIPTION_NULL_OK</tt><a class="headerlink" href="#fdb.DESCRIPTION_NULL_OK" title="Permalink to this definition">¶</a></dt>
<dd><p>Helper constants for work with <a class="reference internal" href="#fdb.Cursor.description" title="fdb.Cursor.description"><tt class="xref py py-attr docutils literal"><span class="pre">Cursor.description</span></tt></a> content.</p>
</dd></dl>
</div>
<div class="section" id="exceptions">
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2>
<dl class="exception">
<dt id="fdb.Warning">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">Warning</tt><a class="headerlink" href="#fdb.Warning" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">exceptions.Exception</span></tt></p>
<p>Exception raised for important warnings like data
truncations while inserting, etc.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.Error">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">Error</tt><a class="headerlink" href="#fdb.Error" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">exceptions.Exception</span></tt></p>
<p>Exception that is the base class of all other error
exceptions. You can use this to catch all errors with one
single ‘except’ statement. Warnings are not considered
errors and thus should not use this class as base.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.InterfaceError">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">InterfaceError</tt><a class="headerlink" href="#fdb.InterfaceError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.Error</span></tt></p>
<p>Exception raised for errors that are related to the
database interface rather than the database itself.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.DatabaseError">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">DatabaseError</tt><a class="headerlink" href="#fdb.DatabaseError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.Error</span></tt></p>
<p>Exception raised for errors that are related to the database.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.DataError">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">DataError</tt><a class="headerlink" href="#fdb.DataError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.DatabaseError</span></tt></p>
<p>Exception raised for errors that are due to problems with
the processed data like division by zero, numeric value
out of range, etc.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.OperationalError">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">OperationalError</tt><a class="headerlink" href="#fdb.OperationalError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.DatabaseError</span></tt></p>
<p>Exception raised for errors that are related to the
database’s operation and not necessarily under the control
of the programmer, e.g. an unexpected disconnect occurs,
the data source name is not found, a transaction could not
be processed, a memory allocation error occurred during
processing, etc.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.IntegrityError">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">IntegrityError</tt><a class="headerlink" href="#fdb.IntegrityError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.DatabaseError</span></tt></p>
<p>Exception raised when the relational integrity of the
database is affected, e.g. a foreign key check fails.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.InternalError">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">InternalError</tt><a class="headerlink" href="#fdb.InternalError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.DatabaseError</span></tt></p>
<p>Exception raised when the database encounters an internal
error, e.g. the cursor is not valid anymore, the
transaction is out of sync, etc.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.ProgrammingError">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">ProgrammingError</tt><a class="headerlink" href="#fdb.ProgrammingError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.DatabaseError</span></tt></p>
<p>Exception raised for programming errors, e.g. table not
found or already exists, syntax error in the SQL
statement, wrong number of parameters specified, etc.</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.NotSupportedError">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">NotSupportedError</tt><a class="headerlink" href="#fdb.NotSupportedError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.DatabaseError</span></tt></p>
<p>Exception raised in case a method or database API was used
which is not supported by the database</p>
</dd></dl>
<dl class="exception">
<dt id="fdb.TransactionConflict">
<em class="property">exception </em><tt class="descclassname">fdb.</tt><tt class="descname">TransactionConflict</tt><a class="headerlink" href="#fdb.TransactionConflict" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">fdb.fbcore.DatabaseError</span></tt></p>
</dd></dl>
<p>This is the exception inheritance layout:</p>
<div class="highlight-python"><pre>StandardError
|__Warning
|__Error
|__InterfaceError
|__DatabaseError
|__DataError
|__OperationalError
|__IntegrityError
|__InternalError
|__ProgrammingError
|__NotSupportedError</pre>
</div>
</div>
<div class="section" id="functions">
<h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="fdb.connect">
<tt class="descclassname">fdb.</tt><tt class="descname">connect</tt><big>(</big><em>dsn=''</em>, <em>user=None</em>, <em>password=None</em>, <em>host=None</em>, <em>port=3050</em>, <em>database=None</em>, <em>sql_dialect=3</em>, <em>role=None</em>, <em>charset=None</em>, <em>buffers=None</em>, <em>force_write=None</em>, <em>no_reserve=None</em>, <em>db_key_scope=None</em>, <em>isolation_level='\x03\t\x06\x0f\x11'</em><big>)</big><a class="headerlink" href="#fdb.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Establish a connection to database.</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 simple">
<li><strong>dsn</strong> – Connection string in format [host[/port]]:database</li>
<li><strong>user</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – User name. If not specified, fdb attempts to use ISC_USER envar.</li>
<li><strong>password</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – User password. If not specified, fdb attempts to use ISC_PASSWORD envar.</li>
<li><strong>host</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Server host machine specification.</li>
<li><strong>port</strong> (<em>integer</em>) – Port used by Firebird server <strong>(not used)</strong>.</li>
<li><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database specification (file spec. or alias)</li>
<li><strong>sql_dialect</strong> – SQL Dialect for connection.</li>
<li><strong>role</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – User role.</li>
<li><strong>charset</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Character set for connection.</li>
<li><strong>buffers</strong> (<em>integer</em>) – Page case size override for connection.</li>
<li><strong>force_writes</strong> (<em>integer</em>) – Forced writes override for connection.</li>
<li><strong>no_reserve</strong> (<em>integer</em>) – Page space reservation override for connection.</li>
<li><strong>db_key_scope</strong> (<em>integer</em>) – DBKEY scope override for connection.</li>
<li><strong>isolation_level</strong> (<em>0, 1, 2 or 3</em>) – Default transaction isolation level for connection <strong>(not used)</strong>.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">Connection to database.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first"><a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ProgrammingError</strong> – For bad parameter values.</li>
<li><strong>DatabaseError</strong> – When connection cannot be established.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">You may specify the database using either <cite>dns</cite> or <cite>database</cite> (with optional <cite>host</cite>),
but not both.</p>
</div>
<p>Examples:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">dsn</span><span class="o">=</span><span class="s">'host:/path/database.fdb'</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'pass'</span><span class="p">,</span> <span class="n">charset</span><span class="o">=</span><span class="s">'UTF8'</span><span class="p">)</span>
<span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">host</span><span class="o">=</span><span class="s">'myhost'</span><span class="p">,</span> <span class="n">database</span><span class="o">=</span><span class="s">'/path/database.fdb'</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'pass'</span><span class="p">,</span> <span class="n">charset</span><span class="o">=</span><span class="s">'UTF8'</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="fdb.create_database">
<tt class="descclassname">fdb.</tt><tt class="descname">create_database</tt><big>(</big><em>sql</em>, <em>sql_dialect=3</em><big>)</big><a class="headerlink" href="#fdb.create_database" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a new database with the supplied “CREATE DATABASE” statement.</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 simple">
<li><strong>sql</strong> – “CREATE DATABASE” statement.</li>
<li><strong>sql_dialect</strong> (<em>1 or 3</em>) – SQL Dialect for newly created database.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">Connection to the newly created database.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first"><a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body"><p class="first last">When database creation fails.</p>
</td>
</tr>
</tbody>
</table>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">create_database</span><span class="p">(</span><span class="s">"create database '/temp/db.db' user 'sysdba' password 'pass'"</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="connection">
<h2>Connection<a class="headerlink" href="#connection" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.Connection">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">Connection</tt><big>(</big><em>db_handle</em>, <em>dpb=None</em>, <em>sql_dialect=3</em>, <em>charset=None</em><big>)</big><a class="headerlink" href="#fdb.Connection" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents a connection between the database client (the Python process)
and the database server.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">DO NOT create instances of this class directly! Use only
<a class="reference internal" href="#fdb.connect" title="fdb.connect"><tt class="xref py py-func docutils literal"><span class="pre">connect()</span></tt></a> or <a class="reference internal" href="#fdb.create_database" title="fdb.create_database"><tt class="xref py py-func docutils literal"><span class="pre">create_database()</span></tt></a> to get Connection instances.</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"><ul class="first last simple">
<li><strong>db_handle</strong> – Database handle provided by factory function.</li>
<li><strong>dpb</strong> – Database Parameter Block associated with database handle.</li>
<li><strong>sql_dialect</strong> (<em>integer</em>) – SQL Dialect associated with database handle.</li>
<li><strong>charset</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Character set associated with database handle.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<dl class="method">
<dt id="fdb.Connection.begin">
<tt class="descname">begin</tt><big>(</big><em>tpb=None</em><big>)</big><a class="headerlink" href="#fdb.Connection.begin" title="Permalink to this definition">¶</a></dt>
<dd><p>Starts a transaction explicitly.
Operates on <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">main_transaction</span></tt></a>.
See <a class="reference internal" href="#fdb.Transaction.begin" title="fdb.Transaction.begin"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.begin()</span></tt></a> for details.</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"><strong>tpb</strong> (<a class="reference internal" href="#fdb.TPB" title="fdb.TPB"><tt class="xref py py-class docutils literal"><span class="pre">TPB</span></tt></a> instance, list/tuple of <cite>isc_tpb_*</cite> constants
or <cite>bytestring</cite>) – (Optional) Transaction Parameter Buffer for newly started
transaction. If not specified, <a class="reference internal" href="#fdb.Connection.default_tpb" title="fdb.Connection.default_tpb"><tt class="xref py py-attr docutils literal"><span class="pre">default_tpb</span></tt></a> is used.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Connection.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Close the connection now (rather than whenever <cite>__del__</cite> is called).
The connection will be unusable from this point forward; an <a class="reference internal" href="#fdb.Error" title="fdb.Error"><tt class="xref py py-exc docutils literal"><span class="pre">Error</span></tt></a>
(or subclass) exception will be raised if any operation is attempted
with the connection. The same applies to all cursor and transaction
objects trying to use the connection.</p>
<p>Also closes all <a class="reference internal" href="#fdb.EventConduit" title="fdb.EventConduit"><tt class="xref py py-class docutils literal"><span class="pre">EventConduit</span></tt></a>, <a class="reference internal" href="#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> and <a class="reference internal" href="#fdb.Transaction" title="fdb.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a>
instances associated with this 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" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">When connection is a member of a <a class="reference internal" href="#fdb.ConnectionGroup" title="fdb.ConnectionGroup"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionGroup</span></tt></a>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.commit">
<tt class="descname">commit</tt><big>(</big><em>retaining=False</em><big>)</big><a class="headerlink" href="#fdb.Connection.commit" title="Permalink to this definition">¶</a></dt>
<dd><p>Commit pending transaction to the database.
Operates on <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">main_transaction</span></tt></a>.
See <a class="reference internal" href="#fdb.Transaction.commit" title="fdb.Transaction.commit"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.commit()</span></tt></a> for details.</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"><strong>retaining</strong> (<em>boolean</em>) – (Optional) Indicates whether the transactional
context of the transaction being resolved
should be recycled.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">If Connection is <a class="reference internal" href="#fdb.Connection.closed" title="fdb.Connection.closed"><tt class="xref py py-attr docutils literal"><span class="pre">closed</span></tt></a>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.cursor">
<tt class="descname">cursor</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Connection.cursor" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new <a class="reference internal" href="#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> instance using the connection
associated with <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">main_transaction</span></tt></a>.
See <a class="reference internal" href="#fdb.Transaction.cursor" title="fdb.Transaction.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.cursor()</span></tt></a> for details.</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" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">If Connection is <a class="reference internal" href="#fdb.Connection.closed" title="fdb.Connection.closed"><tt class="xref py py-attr docutils literal"><span class="pre">closed</span></tt></a>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.database_info">
<tt class="descname">database_info</tt><big>(</big><em>info_code</em>, <em>result_type</em><big>)</big><a class="headerlink" href="#fdb.Connection.database_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Wraps the Firebird C API function <cite>isc_database_info</cite>.</p>
<p>For documentation, see the IB 6 API Guide section entitled
“Requesting information about an attachment” (p. 51).</p>
<p>Note that this method is a VERY THIN wrapper around the FB C API
function <cite>isc_database_info</cite>. This method does NOT attempt to interpret
its results except with regard to whether they are a string or an
integer.</p>
<p>For example, requesting <cite>isc_info_user_names</cite> will return a string
containing a raw succession of length-name pairs. A thicker wrapper
might interpret those raw results and return a Python tuple, but it
would need to handle a multitude of special cases in order to cover
all possible isc_info_* items.</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 simple">
<li><strong>info_code</strong> (<em>integer</em>) – One of the <cite>isc_info_*</cite> constants.</li>
<li><strong>result_type</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Must be either ‘s’ if you expect a string result,
or ‘i’ if you expect an integer result.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned from server.</li>
<li><strong>OperationalError</strong> – When returned information is bigger than SHRT_MAX.</li>
<li><strong>InternalError</strong> – On unexpected processing condition.</li>
<li><strong>ValueError</strong> – On illegal <cite>result_type</cite> value.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">Extracting data with the database_info function is rather
clumsy. See <a class="reference internal" href="#fdb.Connection.db_info" title="fdb.Connection.db_info"><tt class="xref py py-meth docutils literal"><span class="pre">db_info()</span></tt></a> for higher-level means of accessing the
same information.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Some of the information available through this method would be
more easily retrieved with the Services API (see submodule
<a class="reference internal" href="#module-fdb.services" title="fdb.services: Submodule for work with Firebird Services"><tt class="xref py py-mod docutils literal"><span class="pre">fdb.services</span></tt></a>).</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.db_info">
<tt class="descname">db_info</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#fdb.Connection.db_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Higher-level convenience wrapper around the <a class="reference internal" href="#fdb.Connection.database_info" title="fdb.Connection.database_info"><tt class="xref py py-meth docutils literal"><span class="pre">database_info()</span></tt></a> method
that parses the output of <cite>database_info</cite> into Python-friendly objects
instead of returning raw binary buffers in the case of complex result types.</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"><p class="first"><strong>request</strong> – Single <cite>fdb.isc_info_*</cite> info request code or a sequence
of such codes.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">Mapping of (info request code -> result).</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ValueError</strong> – When requested code is not recognized.</li>
<li><strong>OperationalError</strong> – On unexpected processing condition.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.drop_database">
<tt class="descname">drop_database</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Connection.drop_database" title="Permalink to this definition">¶</a></dt>
<dd><p>Drops the database to which this connection is attached.</p>
<p>Unlike plain file deletion, this method behaves responsibly, in that
it removes shadow files and other ancillary files for this database.</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">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ProgrammingError</strong> – When connection is a member of a <a class="reference internal" href="#fdb.ConnectionGroup" title="fdb.ConnectionGroup"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionGroup</span></tt></a>.</li>
<li><strong>DatabaseError</strong> – When error is returned from server.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.event_conduit">
<tt class="descname">event_conduit</tt><big>(</big><em>event_names</em><big>)</big><a class="headerlink" href="#fdb.Connection.event_conduit" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a conduit through which database event notifications will
flow into the Python program.</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"><strong>event_names</strong> – A sequence of string event names.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">An <a class="reference internal" href="#fdb.EventConduit" title="fdb.EventConduit"><tt class="xref py py-class docutils literal"><span class="pre">EventConduit</span></tt></a> instance.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.execute_immediate">
<tt class="descname">execute_immediate</tt><big>(</big><em>sql</em><big>)</big><a class="headerlink" href="#fdb.Connection.execute_immediate" title="Permalink to this definition">¶</a></dt>
<dd><p>Executes a statement in context of <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">main_transaction</span></tt></a> without
caching its prepared form.</p>
<p>Automatically starts transaction if it’s not already started.</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"><strong>sql</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – SQL statement to execute.</td>
</tr>
</tbody>
</table>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last"><strong>The statement must not be of a type that returns a result set.</strong>
In most cases (especially cases in which the same statement – perhaps
a parameterized statement – is executed repeatedly), it is better to
create a cursor using the connection’s cursor method, then execute
the statement using one of the cursor’s execute methods.</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"><p class="first"><strong>sql</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – SQL statement to execute.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ProgrammingError</strong> – When connection is closed.</li>
<li><strong>DatabaseError</strong> – When error is returned from server.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.rollback">
<tt class="descname">rollback</tt><big>(</big><em>retaining=False</em>, <em>savepoint=None</em><big>)</big><a class="headerlink" href="#fdb.Connection.rollback" title="Permalink to this definition">¶</a></dt>
<dd><p>Causes the the database to roll back to the start of pending transaction.
Operates on <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">main_transaction</span></tt></a>.
See <a class="reference internal" href="#fdb.Transaction.rollback" title="fdb.Transaction.rollback"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.rollback()</span></tt></a> for details.</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 simple">
<li><strong>retaining</strong> (<em>boolean</em>) – (Optional) Indicates whether the transactional
context of the transaction being resolved
should be recycled.</li>
<li><strong>savepoint</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – (Optional) Causes the transaction to roll back
only as far as the designated savepoint, rather
than rolling back entirely.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body"><p class="first last">If Connection is <a class="reference internal" href="#fdb.Connection.closed" title="fdb.Connection.closed"><tt class="xref py py-attr docutils literal"><span class="pre">closed</span></tt></a>.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.savepoint">
<tt class="descname">savepoint</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#fdb.Connection.savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Establishes a named SAVEPOINT for current transaction.
Operates on <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">main_transaction</span></tt></a>.
See <a class="reference internal" href="#fdb.Transaction.savepoint" title="fdb.Transaction.savepoint"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.savepoint()</span></tt></a> for details.</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"><strong>name</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Name for savepoint.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">If Connection is <a class="reference internal" href="#fdb.Connection.closed" title="fdb.Connection.closed"><tt class="xref py py-attr docutils literal"><span class="pre">closed</span></tt></a>.</td>
</tr>
</tbody>
</table>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">con</span><span class="o">.</span><span class="n">savepoint</span><span class="p">(</span><span class="s">'BEGINNING_OF_SOME_SUBTASK'</span><span class="p">)</span>
<span class="o">...</span>
<span class="n">con</span><span class="o">.</span><span class="n">rollback</span><span class="p">(</span><span class="n">savepoint</span><span class="o">=</span><span class="s">'BEGINNING_OF_SOME_SUBTASK'</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.trans">
<tt class="descname">trans</tt><big>(</big><em>default_tpb=None</em><big>)</big><a class="headerlink" href="#fdb.Connection.trans" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a new <a class="reference internal" href="#fdb.Transaction" title="fdb.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a> that operates within the context
of this connection. Cursors can be created within that Transaction via
its <a class="reference internal" href="#fdb.Transaction.cursor" title="fdb.Transaction.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">cursor()</span></tt></a> method.</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"><strong>default_tpb</strong> (<a class="reference internal" href="#fdb.TPB" title="fdb.TPB"><tt class="xref py py-class docutils literal"><span class="pre">TPB</span></tt></a> instance, list/tuple of <cite>isc_tpb_*</cite> constants
or <cite>bytestring</cite>) – (optional) Transaction Parameter Block for newly created
Transaction. If not specified, <a class="reference internal" href="#fdb.Connection.default_tpb" title="fdb.Connection.default_tpb"><tt class="xref py py-attr docutils literal"><span class="pre">default_tpb</span></tt></a> is used.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">If Connection is <a class="reference internal" href="#fdb.Connection.closed" title="fdb.Connection.closed"><tt class="xref py py-attr docutils literal"><span class="pre">closed</span></tt></a>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.trans_info">
<tt class="descname">trans_info</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#fdb.Connection.trans_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Pythonic wrapper around <a class="reference internal" href="#fdb.Connection.transaction_info" title="fdb.Connection.transaction_info"><tt class="xref py py-meth docutils literal"><span class="pre">transaction_info()</span></tt></a> call.
Operates on <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">main_transaction</span></tt></a>.
See <a class="reference internal" href="#fdb.Transaction.trans_info" title="fdb.Transaction.trans_info"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.trans_info()</span></tt></a> for details.</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"><p class="first"><strong>request</strong> – One or more information request codes (see
<a class="reference internal" href="#fdb.Connection.transaction_info" title="fdb.Connection.transaction_info"><tt class="xref py py-meth docutils literal"><span class="pre">transaction_info()</span></tt></a> for details). Multiple codes
must be passed as tuple.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">Decoded response(s) for specified request code(s). When multiple
requests are passed, returns a dictionary where key is the
request code and value is the response from server.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ProgrammingError</strong> – When transaction is not active.</li>
<li><strong>OperationalError</strong> – When result is too large to fit into buffer of
size SHRT_MAX.</li>
<li><strong>InternalError</strong> – On unexpected processing condition.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Connection.transaction_info">
<tt class="descname">transaction_info</tt><big>(</big><em>info_code</em>, <em>result_type</em><big>)</big><a class="headerlink" href="#fdb.Connection.transaction_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns information about active transaction.
Thin wrapper around Firebird API <cite>isc_transaction_info</cite> call.
Operates on <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">main_transaction</span></tt></a>.
See <a class="reference internal" href="#fdb.Transaction.transaction_info" title="fdb.Transaction.transaction_info"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.transaction_info()</span></tt></a> for details.</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 simple">
<li><strong>info_code</strong> (<em>integer</em>) – <p>One from next constants:</p>
<ul>
<li>isc_info_tra_id</li>
<li>isc_info_tra_oldest_interesting</li>
<li>isc_info_tra_oldest_snapshot</li>
<li>isc_info_tra_oldest_active</li>
<li>isc_info_tra_isolation</li>
<li>isc_info_tra_access</li>
<li>isc_info_tra_lock_timeout</li>
</ul>
<p>See Firebird API Guide for details.</p>
</li>
<li><strong>result_type</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – <p>String code for result type:</p>
<ul>
<li>‘i’ for Integer</li>
<li>‘s’ fro String</li>
</ul>
</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">Decoded response(s) for specified request code(s). When multiple
requests are passed, returns a dictionary where key is the
request code and value is the response from server.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ProgrammingError</strong> – When transaction is not active.</li>
<li><strong>OperationalError</strong> – When result is too large to fit into buffer of
size SHRT_MAX.</li>
<li><strong>InternalError</strong> – On unexpected processing condition.</li>
<li><strong>ValueError</strong> – On illegal result_type value.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Connection.charset">
<tt class="descname">charset</tt><a class="headerlink" href="#fdb.Connection.charset" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (string) Connection Character set name.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Connection.closed">
<tt class="descname">closed</tt><a class="headerlink" href="#fdb.Connection.closed" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) True if connection is closed.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Connection.default_tpb">
<tt class="descname">default_tpb</tt><a class="headerlink" href="#fdb.Connection.default_tpb" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read/Write) Deafult Transaction Parameter Block used for all newly started transactions.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Connection.group">
<tt class="descname">group</tt><a class="headerlink" href="#fdb.Connection.group" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) <a class="reference internal" href="#fdb.ConnectionGroup" title="fdb.ConnectionGroup"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionGroup</span></tt></a> this Connection belongs to, or None.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Connection.main_transaction">
<tt class="descname">main_transaction</tt><a class="headerlink" href="#fdb.Connection.main_transaction" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) Main <a class="reference internal" href="#fdb.Transaction" title="fdb.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a> instance for this connection
Connection methods <a class="reference internal" href="#fdb.Connection.begin" title="fdb.Connection.begin"><tt class="xref py py-meth docutils literal"><span class="pre">begin()</span></tt></a>, <a class="reference internal" href="#fdb.Connection.savepoint" title="fdb.Connection.savepoint"><tt class="xref py py-meth docutils literal"><span class="pre">savepoint()</span></tt></a>, <a class="reference internal" href="#fdb.Connection.commit" title="fdb.Connection.commit"><tt class="xref py py-meth docutils literal"><span class="pre">commit()</span></tt></a> and
<a class="reference internal" href="#fdb.Connection.rollback" title="fdb.Connection.rollback"><tt class="xref py py-meth docutils literal"><span class="pre">rollback()</span></tt></a> are delegated to this transaction object.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Connection.server_version">
<tt class="descname">server_version</tt><a class="headerlink" href="#fdb.Connection.server_version" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (string) Version string returned by server for this connection.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Connection.sql_dialect">
<tt class="descname">sql_dialect</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.Connection.sql_dialect" title="Permalink to this definition">¶</a></dt>
<dd><p>(integer) sql_dialect for this connection, do not change.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Connection.transactions">
<tt class="descname">transactions</tt><a class="headerlink" href="#fdb.Connection.transactions" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (tuple) <a class="reference internal" href="#fdb.Transaction" title="fdb.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a> instances associated with this connection.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="cursor">
<h2>Cursor<a class="headerlink" href="#cursor" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.Cursor">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">Cursor</tt><big>(</big><em>connection</em>, <em>transaction</em><big>)</big><a class="headerlink" href="#fdb.Cursor" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents a database cursor, which is used to execute SQL statement and
manage the context of a fetch operation.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">DO NOT create instances of this class directly! Use only
<a class="reference internal" href="#fdb.Connection.cursor" title="fdb.Connection.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.cursor()</span></tt></a>, <a class="reference internal" href="#fdb.Transaction.cursor" title="fdb.Transaction.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.cursor()</span></tt></a> and
<a class="reference internal" href="#fdb.ConnectionGroup.cursor" title="fdb.ConnectionGroup.cursor"><tt class="xref py py-meth docutils literal"><span class="pre">ConnectionGroup.cursor()</span></tt></a> to get Cursor instances that operate in
desired context.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Cursor is actually a high-level wrapper around <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a>
instance(s) that handle the actual SQL statement execution and result
management. Cursor has an internal cache of PreparedStatements, so when
the same SQL statement is executed repeatedly, related PreparedStatement
is re-used, which enhances performance. This convenient enhancement has
a side effect: Cursor that was used to perform many different SQL statements
may hold very large cache of PerapedStatements. To clear the cache, you’ll
need to call <a class="reference internal" href="#fdb.Cursor.clear_cache" title="fdb.Cursor.clear_cache"><tt class="xref py py-meth docutils literal"><span class="pre">clear_cache()</span></tt></a>.</p>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">Cursor supports the iterator protocol, yielding tuples of values like
<a class="reference internal" href="#fdb.Cursor.fetchone" title="fdb.Cursor.fetchone"><tt class="xref py py-meth docutils literal"><span class="pre">fetchone()</span></tt></a>.</p>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">The association between a Cursor and its <a class="reference internal" href="#fdb.Transaction" title="fdb.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a> and
<a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> is set when the Cursor is created, and cannot be
changed during the lifetime of that Cursor.</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"><ul class="first last simple">
<li><strong>connection</strong> – <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance this cursor should be bound to.</li>
<li><strong>transaction</strong> – <a class="reference internal" href="#fdb.Transaction" title="fdb.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a> instance this cursor should be bound to.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<dl class="method">
<dt id="fdb.Cursor.callproc">
<tt class="descname">callproc</tt><big>(</big><em>procname</em>, <em>parameters=None</em><big>)</big><a class="headerlink" href="#fdb.Cursor.callproc" title="Permalink to this definition">¶</a></dt>
<dd><p>Call a stored database procedure with the given name.</p>
<p>The result of the call is available through the standard fetchXXX() methods.</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 simple">
<li><strong>procname</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Stored procedure name.</li>
<li><strong>parameters</strong> (<em>List or Tuple</em>) – (Optional) Sequence of parameters. Must contain one
entry for each argument that the procedure expects.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">parameters, as required by Python DB API 2.0 Spec.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>TypeError</strong> – When parameters is not List or Tuple.</li>
<li><strong>ProgrammingError</strong> – When more parameters than expected are suplied.</li>
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.clear_cache">
<tt class="descname">clear_cache</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.clear_cache" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the internal cache with <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> instances.</p>
<p>All prepared statements except current one are <strong>permanently</strong> closed,
and the cache is cleared.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Current prepared statement is still in its actual state, but it’s
removed from cache, so when next statement (even the same SQL command)
is executed, this current <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> instance is disposed.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Close the cursor now (rather than whenever <cite>__del__</cite> is called).</p>
<p>Closes any currently open <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a>. However, the cursor
is still bound to <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> and <a class="reference internal" href="#fdb.Transaction" title="fdb.Transaction"><tt class="xref py py-class docutils literal"><span class="pre">Transaction</span></tt></a>, so it
could be still used to execute SQL statements. Also the cache with
prepared statements is left intact.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>FDB’s implementation of Cursor somewhat violates the Python DB API 2.0,
which requires that cursor will be unusable after call to <cite>close</cite>; and
an Error (or subclass) exception should be raised if any operation is
attempted with the cursor.</p>
<p class="last">If you’ll take advantage of this anomaly, your code would be less
portable to other Python DB API 2.0 compliant drivers.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.execute">
<tt class="descname">execute</tt><big>(</big><em>operation</em>, <em>parameters=None</em><big>)</big><a class="headerlink" href="#fdb.Cursor.execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepare and execute a database operation (query or command).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Execution is handled by <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> that is either
supplied as <cite>operation</cite> parameter, or created internally when
<cite>operation</cite> is a string. Internally created PreparedStatements are
stored in cache for later reuse, when the same <cite>operation</cite> string is
used again.</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">Returns:</th><td class="field-body"><p class="first">self, so call to execute could be used as iterator.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>operation</strong> (string or <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> instance) – SQL command specification.</li>
<li><strong>parameters</strong> (<em>List or Tuple</em>) – (Optional) Sequence of parameters. Must contain one
entry for each argument that the operation expects.</li>
</ul>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ValueError</strong> – When operation PreparedStatement belongs to different
Cursor instance.</li>
<li><strong>TypeError</strong> – When parameters is not List or Tuple.</li>
<li><strong>ProgrammingError</strong> – When more parameters than expected are suplied.</li>
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.executemany">
<tt class="descname">executemany</tt><big>(</big><em>operation</em>, <em>seq_of_parameters</em><big>)</big><a class="headerlink" href="#fdb.Cursor.executemany" title="Permalink to this definition">¶</a></dt>
<dd><p>Prepare a database operation (query or command) and then execute it
against all parameter sequences or mappings found in the sequence
<cite>seq_of_parameters</cite>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function simply calls <a class="reference internal" href="#fdb.Cursor.execute" title="fdb.Cursor.execute"><tt class="xref py py-meth docutils literal"><span class="pre">execute()</span></tt></a> in a loop, feeding it with
parameters from <cite>seq_of_parameters</cite>. Because <cite>execute</cite> caches
<cite>PreparedStatements</cite>, calling <cite>executemany</cite> is equally efective as
direct use of prepared statement and calling <cite>execute</cite> in a loop
directly in application.</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"><ul class="first simple">
<li><strong>operation</strong> (string or <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> instance) – SQL command specification.</li>
<li><strong>seq_of_parameters</strong> (<em>List or Tuple</em>) – Sequence of sequences of parameters. Must contain
one sequence of parameters for each execution
that has one entry for each argument that the
operation expects.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ValueError</strong> – When operation PreparedStatement belongs to different
Cursor instance.</li>
<li><strong>TypeError</strong> – When seq_of_parameters is not List or Tuple.</li>
<li><strong>ProgrammingError</strong> – When there are more parameters in any sequence
than expected.</li>
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.fetchall">
<tt class="descname">fetchall</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.fetchall" title="Permalink to this definition">¶</a></dt>
<dd><p>Fetch all (remaining) rows of a query result.</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">Returns:</th><td class="field-body"><p class="first">List of tuples, where each tuple is one row of returned values.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
<li><strong>ProgrammingError</strong> – When underlying <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> is
closed, statement was not yet executed, or
unknown status is returned by fetch operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.fetchallmap">
<tt class="descname">fetchallmap</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.fetchallmap" title="Permalink to this definition">¶</a></dt>
<dd><p>Fetch all (remaining) rows of a query result like <a class="reference internal" href="#fdb.Cursor.fetchall" title="fdb.Cursor.fetchall"><tt class="xref py py-meth docutils literal"><span class="pre">fetchall()</span></tt></a>,
except that it returns a list of mappings of field name to field
value, rather than a list of tuples.</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">Returns:</th><td class="field-body"><p class="first">List of <a class="reference internal" href="#fdb.fbcore._RowMapping" title="fdb.fbcore._RowMapping"><tt class="xref py py-class docutils literal"><span class="pre">fbcore._RowMapping</span></tt></a> instances, one such instance for
each row.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
<li><strong>ProgrammingError</strong> – When underlying <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> is
closed, statement was not yet executed, or
unknown status is returned by fetch operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.fetchmany">
<tt class="descname">fetchmany</tt><big>(</big><em>size=1</em><big>)</big><a class="headerlink" href="#fdb.Cursor.fetchmany" title="Permalink to this definition">¶</a></dt>
<dd><p>Fetch the next set of rows of a query result, returning a sequence of
sequences (e.g. a list of tuples). An empty sequence is returned when no
more rows are available. The number of rows to fetch per call is specified
by the parameter. If it is not given, the cursor’s arraysize determines
the number of rows to be fetched. The method does try to fetch as many
rows as indicated by the size parameter. If this is not possible due to
the specified number of rows not being available, fewer rows may be
returned.</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"><p class="first"><strong>size</strong> (<em>integer</em>) – Max. number of rows to fetch.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">List of tuples, where each tuple is one row of returned values.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
<li><strong>ProgrammingError</strong> – When underlying <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> is
closed, statement was not yet executed, or
unknown status is returned by fetch operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.fetchmanymap">
<tt class="descname">fetchmanymap</tt><big>(</big><em>size=1</em><big>)</big><a class="headerlink" href="#fdb.Cursor.fetchmanymap" title="Permalink to this definition">¶</a></dt>
<dd><p>Fetch the next set of rows of a query result, like <a class="reference internal" href="#fdb.Cursor.fetchmany" title="fdb.Cursor.fetchmany"><tt class="xref py py-meth docutils literal"><span class="pre">fetchmany()</span></tt></a>,
except that it returns a list of mappings of field name to field
value, rather than a list of tuples.</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"><p class="first"><strong>size</strong> (<em>integer</em>) – Max. number of rows to fetch.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">List of <a class="reference internal" href="#fdb.fbcore._RowMapping" title="fdb.fbcore._RowMapping"><tt class="xref py py-class docutils literal"><span class="pre">fbcore._RowMapping</span></tt></a> instances, one such instance for
each row.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
<li><strong>ProgrammingError</strong> – When underlying <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> is
closed, statement was not yet executed, or
unknown status is returned by fetch operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.fetchone">
<tt class="descname">fetchone</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.fetchone" title="Permalink to this definition">¶</a></dt>
<dd><p>Fetch the next row of a query result set.</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">Returns:</th><td class="field-body"><p class="first">tuple of returned values, or None when no more data is available.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
<li><strong>ProgrammingError</strong> – When underlying <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> is
closed, statement was not yet executed, or
unknown status is returned by fetch operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.fetchonemap">
<tt class="descname">fetchonemap</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.fetchonemap" title="Permalink to this definition">¶</a></dt>
<dd><p>Fetch the next row of a query result set like <a class="reference internal" href="#fdb.Cursor.fetchone" title="fdb.Cursor.fetchone"><tt class="xref py py-meth docutils literal"><span class="pre">fetchone()</span></tt></a>,
except that it returns a mapping of field name to field value, rather
than a tuple.</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">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#fdb.fbcore._RowMapping" title="fdb.fbcore._RowMapping"><tt class="xref py py-class docutils literal"><span class="pre">fbcore._RowMapping</span></tt></a> of returned values, or None when
no more data is available.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
<li><strong>ProgrammingError</strong> – When underlying <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> is
closed, statement was not yet executed, or
unknown status is returned by fetch operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.iter">
<tt class="descname">iter</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.iter" title="Permalink to this definition">¶</a></dt>
<dd><p>Equivalent to the <a class="reference internal" href="#fdb.Cursor.fetchall" title="fdb.Cursor.fetchall"><tt class="xref py py-meth docutils literal"><span class="pre">fetchall()</span></tt></a>, except that it returns iterator
rather than materialized list.</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">Returns:</th><td class="field-body">Iterator that yields tuple of values like <a class="reference internal" href="#fdb.Cursor.fetchone" title="fdb.Cursor.fetchone"><tt class="xref py py-meth docutils literal"><span class="pre">fetchone()</span></tt></a>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.itermap">
<tt class="descname">itermap</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.itermap" title="Permalink to this definition">¶</a></dt>
<dd><p>Equivalent to the <a class="reference internal" href="#fdb.Cursor.fetchallmap" title="fdb.Cursor.fetchallmap"><tt class="xref py py-meth docutils literal"><span class="pre">fetchallmap()</span></tt></a>, except that it returns iterator
rather than materialized list.</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">Returns:</th><td class="field-body">Iterator that yields <a class="reference internal" href="#fdb.fbcore._RowMapping" title="fdb.fbcore._RowMapping"><tt class="xref py py-class docutils literal"><span class="pre">fbcore._RowMapping</span></tt></a> instance
like <a class="reference internal" href="#fdb.Cursor.fetchonemap" title="fdb.Cursor.fetchonemap"><tt class="xref py py-meth docutils literal"><span class="pre">fetchonemap()</span></tt></a>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Cursor.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the next item from the container. Part of <em>iterator protocol</em>.</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" colspan="2">Raises StopIteration:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">If there are no further items.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.prep">
<tt class="descname">prep</tt><big>(</big><em>operation</em><big>)</big><a class="headerlink" href="#fdb.Cursor.prep" title="Permalink to this definition">¶</a></dt>
<dd><p>Create prepared statement for repeated execution.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Returned <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> instance is bound to its Cursor
instance via strong reference, and is not stored in Cursor’s
internal cache of prepared statements.</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"><p class="first"><strong>operation</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – SQL command</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> instance.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
<li><strong>InternalError</strong> – On unexpected processing condition.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.set_stream_blob">
<tt class="descname">set_stream_blob</tt><big>(</big><em>blob_name</em><big>)</big><a class="headerlink" href="#fdb.Cursor.set_stream_blob" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify a BLOB column(s) to work in <cite>stream</cite> mode instead classic,
materialized mode for already executed statement.</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"><strong>blob_name</strong> (<em>string or sequence</em>) – Single name or sequence of column names. Name must
be in format as it’s stored in database (refer
to <a class="reference internal" href="#fdb.Cursor.description" title="fdb.Cursor.description"><tt class="xref py py-attr docutils literal"><span class="pre">description</span></tt></a> for real value).</td>
</tr>
</tbody>
</table>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">BLOB name is <strong>permanently</strong> added to the list of BLOBs handled
as <cite>stream</cite> BLOBs by current <a class="reference internal" href="#fdb.PreparedStatement" title="fdb.PreparedStatement"><tt class="xref py py-class docutils literal"><span class="pre">PreparedStatement</span></tt></a> instance.
If instance is stored in internal cache of prepared statements,
the same command executed repeatedly will retain this setting.</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"><strong>blob_name</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Name of BLOB column.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body"></td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.setinputsizes">
<tt class="descname">setinputsizes</tt><big>(</big><em>sizes</em><big>)</big><a class="headerlink" href="#fdb.Cursor.setinputsizes" title="Permalink to this definition">¶</a></dt>
<dd><p>Required by Python DB API 2.0, but pointless for Firebird, so it
does nothing.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.Cursor.setoutputsize">
<tt class="descname">setoutputsize</tt><big>(</big><em>size</em>, <em>column=None</em><big>)</big><a class="headerlink" href="#fdb.Cursor.setoutputsize" title="Permalink to this definition">¶</a></dt>
<dd><p>Required by Python DB API 2.0, but pointless for Firebird, so it
does nothing.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Cursor.arraysize">
<tt class="descname">arraysize</tt><em class="property"> = 1</em><a class="headerlink" href="#fdb.Cursor.arraysize" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read/Write) As required by the Python DB API 2.0 spec, the value of this
attribute is observed with respect to the <a class="reference internal" href="#fdb.Cursor.fetchmany" title="fdb.Cursor.fetchmany"><tt class="xref py py-meth docutils literal"><span class="pre">fetchmany()</span></tt></a> method. However,
changing the value of this attribute does not make any difference in fetch
efficiency because the database engine only supports fetching a single row
at a time.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Cursor.description">
<tt class="descname">description</tt><a class="headerlink" href="#fdb.Cursor.description" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) Sequence of 7-item sequences.
Each of these sequences contains information describing one result column:
(name, type_code, display_size,internal_size, precision, scale, null_ok)</p>
<p>If cursor doesn’t have a prepared statement, the value is None.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Cursor.name">
<tt class="descname">name</tt><a class="headerlink" href="#fdb.Cursor.name" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read/Write) (string) Name for the SQL cursor. This property can be
ignored entirely if you don’t need to use it.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Cursor.plan">
<tt class="descname">plan</tt><a class="headerlink" href="#fdb.Cursor.plan" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (string) A string representation of the execution plan
for last executed statement generated by the database engine’s optimizer.
<cite>None</cite> if no statement was executed.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Cursor.rowcount">
<tt class="descname">rowcount</tt><a class="headerlink" href="#fdb.Cursor.rowcount" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (integer) Specifies the number of rows that the last executeXXX()
produced (for DQL statements like select) or affected (for DML statements
like update or insert ).</p>
<p>The attribute is -1 in case no executeXXX() has been performed on the cursor
or the rowcount of the last operation is not determinable by the interface.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The database engine’s own support for the determination of
“rows affected”/”rows selected” is quirky. The database engine only
supports the determination of rowcount for INSERT, UPDATE, DELETE,
and SELECT statements. When stored procedures become involved, row
count figures are usually not available to the client. Determining
rowcount for SELECT statements is problematic: the rowcount is reported
as zero until at least one row has been fetched from the result set,
and the rowcount is misreported if the result set is larger than 1302
rows. The server apparently marshals result sets internally in batches
of 1302, and will misreport the rowcount for result sets larger than
1302 rows until the 1303rd row is fetched, result sets larger than 2604
rows until the 2605th row is fetched, and so on, in increments of 1302.</p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="transaction">
<h2>Transaction<a class="headerlink" href="#transaction" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.Transaction">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">Transaction</tt><big>(</big><em>connections</em>, <em>default_tpb=None</em>, <em>default_action='commit'</em><big>)</big><a class="headerlink" href="#fdb.Transaction" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents a transaction context, which is used to execute SQL statement.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">DO NOT create instances of this class directly! <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> and
<a class="reference internal" href="#fdb.ConnectionGroup" title="fdb.ConnectionGroup"><tt class="xref py py-class docutils literal"><span class="pre">ConnectionGroup</span></tt></a> manage Transaction internally, surfacing all
important methods directly in their interfaces. If you want additional
transactions independent from <a class="reference internal" href="#fdb.Connection.main_transaction" title="fdb.Connection.main_transaction"><tt class="xref py py-attr docutils literal"><span class="pre">Connection.main_transaction</span></tt></a>,
use <a class="reference internal" href="#fdb.Connection.trans" title="fdb.Connection.trans"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.trans()</span></tt></a> method to obtain such <cite>Transaction</cite> 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"><ul class="first simple">
<li><strong>connections</strong> (<em>iterable</em>) – Sequence of (up to 16) <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instances.</li>
<li><strong>default_tpb</strong> (<a class="reference internal" href="#fdb.TPB" title="fdb.TPB"><tt class="xref py py-class docutils literal"><span class="pre">TPB</span></tt></a> instance, list/tuple of <cite>isc_tpb_*</cite> constants
or <cite>bytestring</cite>) – Transaction Parameter Block for this transaction.
If <cite>None</cite> is specified, uses <cite>ISOLATION_LEVEL_READ_COMMITED</cite>.</li>
<li><strong>default_action</strong> (<em>string ‘commit’ or ‘rollback’</em>) – Action taken when active transaction is ended
automatically (during <a class="reference internal" href="#fdb.Transaction.close" title="fdb.Transaction.close"><tt class="xref py py-meth docutils literal"><span class="pre">close()</span></tt></a> or <a class="reference internal" href="#fdb.Transaction.begin" title="fdb.Transaction.begin"><tt class="xref py py-meth docutils literal"><span class="pre">begin()</span></tt></a>).</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body"><p class="first last">When zero or more than 16 connections are given.</p>
</td>
</tr>
</tbody>
</table>
<dl class="method">
<dt id="fdb.Transaction.begin">
<tt class="descname">begin</tt><big>(</big><em>tpb=None</em><big>)</big><a class="headerlink" href="#fdb.Transaction.begin" title="Permalink to this definition">¶</a></dt>
<dd><p>Starts a transaction explicitly.</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"><strong>tpb</strong> (<a class="reference internal" href="#fdb.TPB" title="fdb.TPB"><tt class="xref py py-class docutils literal"><span class="pre">TPB</span></tt></a> instance, list/tuple of <cite>isc_tpb_*</cite> constants
or <cite>bytestring</cite>) – (optional) Transaction Parameter Block for newly created
Transaction. If not specified, <a class="reference internal" href="#fdb.Transaction.default_tpb" title="fdb.Transaction.default_tpb"><tt class="xref py py-attr docutils literal"><span class="pre">default_tpb</span></tt></a> is used.</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Calling this method directly is never required; a transaction will be
started implicitly if necessary.</p>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">If the physical transaction is unresolved when this method is called,
a <a class="reference internal" href="#fdb.Transaction.commit" title="fdb.Transaction.commit"><tt class="xref py py-meth docutils literal"><span class="pre">commit()</span></tt></a> or <a class="reference internal" href="#fdb.Transaction.rollback" title="fdb.Transaction.rollback"><tt class="xref py py-meth docutils literal"><span class="pre">rollback()</span></tt></a> will be performed first, accordingly
to <a class="reference internal" href="#fdb.Transaction.default_action" title="fdb.Transaction.default_action"><tt class="xref py py-attr docutils literal"><span class="pre">default_action</span></tt></a> value.</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">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When error is returned by server.</li>
<li><strong>ProgrammingError</strong> – When TPB is in usupported format, or transaction
is permanently <a class="reference internal" href="#fdb.Transaction.closed" title="fdb.Transaction.closed"><tt class="xref py py-attr docutils literal"><span class="pre">closed</span></tt></a>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Transaction.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Permanently closes the Transaction object and severs its associations
with other objects (<a class="reference internal" href="#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> and <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instances).</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">If the physical transaction is unresolved when this method is called,
a <a class="reference internal" href="#fdb.Transaction.commit" title="fdb.Transaction.commit"><tt class="xref py py-meth docutils literal"><span class="pre">commit()</span></tt></a> or <a class="reference internal" href="#fdb.Transaction.rollback" title="fdb.Transaction.rollback"><tt class="xref py py-meth docutils literal"><span class="pre">rollback()</span></tt></a> will be performed first, accordingly
to <a class="reference internal" href="#fdb.Transaction.default_action" title="fdb.Transaction.default_action"><tt class="xref py py-attr docutils literal"><span class="pre">default_action</span></tt></a> value.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.commit">
<tt class="descname">commit</tt><big>(</big><em>retaining=False</em><big>)</big><a class="headerlink" href="#fdb.Transaction.commit" title="Permalink to this definition">¶</a></dt>
<dd><p>Commit any pending transaction to the database.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If transaction is not active, this method does nothing, because
the consensus among Python DB API experts is that transactions should
always be started implicitly, even if that means allowing a <cite>commit()</cite>
or <cite>rollback()</cite> without an actual transaction.</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"><strong>retaining</strong> (<em>boolean</em>) – Indicates whether the transactional context of
the transaction being resolved should be recycled.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises DatabaseError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When error is returned by server as response to commit.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.cursor">
<tt class="descname">cursor</tt><big>(</big><em>connection=None</em><big>)</big><a class="headerlink" href="#fdb.Transaction.cursor" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a new <a class="reference internal" href="#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> that will operate in the context of this
Transaction.</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"><strong>connection</strong> (<a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance) – <strong>Required only when</strong> Transaction is bound to multiple
<cite>Connections</cite>, to specify to which <cite>Connection</cite> the
returned Cursor should be bound.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When transaction operates on multiple <cite>Connections</cite>
and: <cite>connection</cite> parameter is not specified, or
specified <cite>connection</cite> is not among <cite>Connections</cite>
this Transaction is bound to.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.execute_immediate">
<tt class="descname">execute_immediate</tt><big>(</big><em>sql</em><big>)</big><a class="headerlink" href="#fdb.Transaction.execute_immediate" title="Permalink to this definition">¶</a></dt>
<dd><p>Executes a statement without caching its prepared form on
<strong>all connections</strong> this transaction is bound to.</p>
<p>Automatically starts transaction if it’s not already started.</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"><strong>sql</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – SQL statement to execute.</td>
</tr>
</tbody>
</table>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last"><strong>The statement must not be of a type that returns a result set.</strong>
In most cases (especially cases in which the same statement – perhaps
a parameterized statement – is executed repeatedly), it is better to
create a cursor using the connection’s cursor method, then execute
the statement using one of the cursor’s execute methods.</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"><strong>sql</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – SQL statement to execute.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises DatabaseError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When error is returned from server.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.prepare">
<tt class="descname">prepare</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.Transaction.prepare" title="Permalink to this definition">¶</a></dt>
<dd><p>Manually triggers the first phase of a two-phase commit (2PC).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Direct use of this method is optional; if preparation is not triggered
manually, it will be performed implicitly by <cite>commit()</cite> in a 2PC.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.rollback">
<tt class="descname">rollback</tt><big>(</big><em>retaining=False</em>, <em>savepoint=None</em><big>)</big><a class="headerlink" href="#fdb.Transaction.rollback" title="Permalink to this definition">¶</a></dt>
<dd><p>Rollback any pending transaction to the database.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If transaction is not active, this method does nothing, because
the consensus among Python DB API experts is that transactions should
always be started implicitly, even if that means allowing a <cite>commit()</cite>
or <cite>rollback()</cite> without an actual transaction.</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"><ul class="first simple">
<li><strong>retaining</strong> (<em>boolean</em>) – Indicates whether the transactional context of
the transaction being resolved should be recycled.
Mutually exclusive with ‘savepoint`.</li>
<li><strong>savepoint</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Savepoint name. Causes the transaction to roll
back only as far as the designated savepoint,
rather than rolling back entirely. Mutually
exclusive with ‘retaining`.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ProgrammingError</strong> – If both <cite>savepoint</cite> and <cite>retaining</cite> are specified.</li>
<li><strong>DatabaseError</strong> – When error is returned by server as response to rollback.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.savepoint">
<tt class="descname">savepoint</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#fdb.Transaction.savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Establishes a savepoint with the specified name.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If transaction is bound to multiple connections, savepoint is
created on all of them.</p>
</div>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">Because savepoint is created not through Firebird API (there is no
such API call), but by executing <cite>SAVEPOINT <name></cite> SQL statement,
calling this method starts the transaction if it was not yet started.</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"><strong>name</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Savepoint name.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.trans_info">
<tt class="descname">trans_info</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#fdb.Transaction.trans_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Pythonic wrapper around <a class="reference internal" href="#fdb.Transaction.transaction_info" title="fdb.Transaction.transaction_info"><tt class="xref py py-meth docutils literal"><span class="pre">transaction_info()</span></tt></a> call.</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"><strong>request</strong> – One or more information request codes (see
<a class="reference internal" href="#fdb.Transaction.transaction_info" title="fdb.Transaction.transaction_info"><tt class="xref py py-meth docutils literal"><span class="pre">transaction_info()</span></tt></a> for details). Multiple codes
must be passed as tuple.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">Decoded response(s) for specified request code(s). When
multiple requests are passed, returns a dictionary where key
is the request code and value is the response from server.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.Transaction.transaction_info">
<tt class="descname">transaction_info</tt><big>(</big><em>info_code</em>, <em>result_type</em><big>)</big><a class="headerlink" href="#fdb.Transaction.transaction_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Return information about active transaction.</p>
<p>This is very thin wrapper around Firebird API <cite>isc_transaction_info</cite> call.</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 simple">
<li><strong>info_code</strong> (<em>integer</em>) – One from the <cite>isc_info_tra_*</cite> constants.</li>
<li><strong>result_type</strong> (<em>string ‘s’ or ‘i’</em>) – Code for result type.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>ProgrammingError</strong> – If transaction is not active.</li>
<li><strong>OperationalError</strong> – When result is too large to fit into buffer of
size SHRT_MAX.</li>
<li><strong>InternalError</strong> – On unexpected processing condition.</li>
<li><strong>ValueError</strong> – When illegal result type code is specified.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Transaction.active">
<tt class="descname">active</tt><a class="headerlink" href="#fdb.Transaction.active" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) True if transaction is active.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Transaction.closed">
<tt class="descname">closed</tt><a class="headerlink" href="#fdb.Transaction.closed" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) True if transaction is closed.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Transaction.cursors">
<tt class="descname">cursors</tt><a class="headerlink" href="#fdb.Transaction.cursors" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) List of <a class="reference internal" href="#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> objects associated with this Transaction.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Transaction.default_action">
<tt class="descname">default_action</tt><a class="headerlink" href="#fdb.Transaction.default_action" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read/Write) (string) ‘commit’ or ‘rollback’, action to be
taken when physical transaction has to be ended automatically.
<strong>Default is ‘commit’</strong>.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.Transaction.default_tpb">
<tt class="descname">default_tpb</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.Transaction.default_tpb" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read/Write) Transaction Parameter Block.
<strong>Default is ISOLATION_LEVEL_READ_COMMITED</strong>.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="preparedstatement">
<h2>PreparedStatement<a class="headerlink" href="#preparedstatement" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.PreparedStatement">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">PreparedStatement</tt><big>(</big><em>operation</em>, <em>cursor</em>, <em>internal=True</em><big>)</big><a class="headerlink" href="#fdb.PreparedStatement" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents a prepared statement, an “inner” database cursor, which is used
to manage the SQL statement execution and context of a fetch operation.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">DO NOT create instances of this class directly! Use only <a class="reference internal" href="#fdb.Cursor.prep" title="fdb.Cursor.prep"><tt class="xref py py-meth docutils literal"><span class="pre">Cursor.prep()</span></tt></a>
to get PreparedStatement instances.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">PreparedStatements are bound to <a class="reference internal" href="#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> instance that created them,
and using them with other Cursor would report an error.</p>
</div>
<dl class="method">
<dt id="fdb.PreparedStatement.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.PreparedStatement.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Drops the resources associated with executed prepared statement, but
keeps it prepared for another execution.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.PreparedStatement.set_stream_blob">
<tt class="descname">set_stream_blob</tt><big>(</big><em>blob_name</em><big>)</big><a class="headerlink" href="#fdb.PreparedStatement.set_stream_blob" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify a BLOB column(s) to work in <cite>stream</cite> mode instead classic,
materialized mode.</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"><strong>blob_name</strong> (<em>string or sequence</em>) – Single name or sequence of column names. Name must
be in format as it’s stored in database (refer
to <a class="reference internal" href="#fdb.PreparedStatement.description" title="fdb.PreparedStatement.description"><tt class="xref py py-attr docutils literal"><span class="pre">description</span></tt></a> for real value).</td>
</tr>
</tbody>
</table>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">BLOB name is <strong>permanently</strong> added to the list of BLOBs handled
as <cite>stream</cite> BLOBs by this 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"><strong>blob_name</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Name of BLOB column.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.NO_FETCH_ATTEMPTED_YET">
<tt class="descname">NO_FETCH_ATTEMPTED_YET</tt><em class="property"> = -1</em><a class="headerlink" href="#fdb.PreparedStatement.NO_FETCH_ATTEMPTED_YET" title="Permalink to this definition">¶</a></dt>
<dd><p>Constant for internal use by this class.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.RESULT_SET_EXHAUSTED">
<tt class="descname">RESULT_SET_EXHAUSTED</tt><em class="property"> = 100</em><a class="headerlink" href="#fdb.PreparedStatement.RESULT_SET_EXHAUSTED" title="Permalink to this definition">¶</a></dt>
<dd><p>Constant for internal use by this class.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.closed">
<tt class="descname">closed</tt><a class="headerlink" href="#fdb.PreparedStatement.closed" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (boolean) True if closed. Note that closed means that PS
statement handle was closed for further fetching, releasing server resources,
but wasn’t dropped, and couldbe still used for another execution.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.cursor">
<tt class="descname">cursor</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.PreparedStatement.cursor" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> instance that manages this PreparedStatement.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.description">
<tt class="descname">description</tt><a class="headerlink" href="#fdb.PreparedStatement.description" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) Sequence of 7-item sequences.
Each of these sequences contains information describing one result column:
(name, type_code, display_size,internal_size, precision, scale, null_ok)</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.in_sqlda">
<tt class="descname">in_sqlda</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.PreparedStatement.in_sqlda" title="Permalink to this definition">¶</a></dt>
<dd><p>Internal XSQLDA structure for input values.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.in_sqlda_save">
<tt class="descname">in_sqlda_save</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.PreparedStatement.in_sqlda_save" title="Permalink to this definition">¶</a></dt>
<dd><p>Internal list to save original input SQLDA structures when they has
to temporarily augmented.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.n_input_params">
<tt class="descname">n_input_params</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.PreparedStatement.n_input_params" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of input parameters the statement requires.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.n_output_params">
<tt class="descname">n_output_params</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.PreparedStatement.n_output_params" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of output fields the statement produces.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.name">
<tt class="descname">name</tt><a class="headerlink" href="#fdb.PreparedStatement.name" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read/Write) (string) Name for the SQL cursor. This property can be
ignored entirely if you don’t need to use it.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.out_sqlda">
<tt class="descname">out_sqlda</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.PreparedStatement.out_sqlda" title="Permalink to this definition">¶</a></dt>
<dd><p>Internal XSQLDA structure for output values.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.plan">
<tt class="descname">plan</tt><a class="headerlink" href="#fdb.PreparedStatement.plan" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (string) A string representation of the execution plan generated
for this statement by the database engine’s optimizer.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.rowcount">
<tt class="descname">rowcount</tt><a class="headerlink" href="#fdb.PreparedStatement.rowcount" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (integer) Specifies the number of rows that the last execution
produced (for DQL statements like select) or affected (for DML statements
like update or insert ).</p>
<p>The attribute is -1 in case the statement was not yet executed
or the rowcount of the operation is not determinable by the interface.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.sql">
<tt class="descname">sql</tt><a class="headerlink" href="#fdb.PreparedStatement.sql" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (string) SQL command this PreparedStatement executes.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.PreparedStatement.statement_type">
<tt class="descname">statement_type</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.PreparedStatement.statement_type" title="Permalink to this definition">¶</a></dt>
<dd><p>(integer) An integer code that can be matched against the statement
type constants in the isc_info_sql_stmt_* series.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="connectiongroup">
<h2>ConnectionGroup<a class="headerlink" href="#connectiongroup" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.ConnectionGroup">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">ConnectionGroup</tt><big>(</big><em>connections=()</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup" title="Permalink to this definition">¶</a></dt>
<dd><p>Manager for distributed transactions, i.e. transactions that span multiple
databases.</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">ConnectionGroup supports <cite>in</cite> operator to check membership of connections.</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"><strong>connections</strong> (<em>iterable</em>) – Sequence of <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instances.</td>
</tr>
</tbody>
</table>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">See <a class="reference internal" href="#fdb.ConnectionGroup.add" title="fdb.ConnectionGroup.add"><tt class="xref py py-meth docutils literal"><span class="pre">add()</span></tt></a> for list of exceptions the constructor may throw.</p>
</div>
<dl class="method">
<dt id="fdb.ConnectionGroup.add">
<tt class="descname">add</tt><big>(</big><em>con</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.add" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds active connection to the group.</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"><p class="first"><strong>con</strong> – A <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance to add to this group.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>TypeError</strong> – When <cite>con</cite> is not <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance.</li>
<li><strong>ProgrammingError</strong> – When <cite>con</cite> is already member of this or another
group, or <a class="reference internal" href="#fdb.Connection.closed" title="fdb.Connection.closed"><tt class="xref py py-attr docutils literal"><span class="pre">closed</span></tt></a>.
When this group has unresolved transaction or
contains 16 connections.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.begin">
<tt class="descname">begin</tt><big>(</big><em>tpb=None</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.begin" title="Permalink to this definition">¶</a></dt>
<dd><p>Starts distributed transaction over member connections.</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"><strong>tpb</strong> (<a class="reference internal" href="#fdb.TPB" title="fdb.TPB"><tt class="xref py py-class docutils literal"><span class="pre">TPB</span></tt></a> instance, list/tuple of <cite>isc_tpb_*</cite> constants
or <cite>bytestring</cite>) – (Optional) Transaction Parameter Buffer for newly started
transaction. If not specified, <a class="reference internal" href="#fdb.ConnectionGroup.default_tpb" title="fdb.ConnectionGroup.default_tpb"><tt class="xref py py-attr docutils literal"><span class="pre">default_tpb</span></tt></a> is used.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When group is empty or has active transaction.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.clear">
<tt class="descname">clear</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Removes all connections from group.</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" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">When transaction is active.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.commit">
<tt class="descname">commit</tt><big>(</big><em>retaining=False</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.commit" title="Permalink to this definition">¶</a></dt>
<dd><p>Commits distributed transaction over member connections using 2PC.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If transaction is not active, this method does nothing, because
the consensus among Python DB API experts is that transactions should
always be started implicitly, even if that means allowing a <cite>commit()</cite>
or <cite>rollback()</cite> without an actual transaction.</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"><strong>retaining</strong> (<em>boolean</em>) – Indicates whether the transactional context of
the transaction being resolved should be recycled.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When group is empty.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.contains">
<tt class="descname">contains</tt><big>(</big><em>con</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns True if specified connection belong to this group.</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"><strong>con</strong> – <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.count">
<tt class="descname">count</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.count" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns number of <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> objects that belong to this group.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.cursor">
<tt class="descname">cursor</tt><big>(</big><em>connection</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.cursor" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a new <a class="reference internal" href="#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">Cursor</span></tt></a> that will operate in the context of
distributed transaction and specific <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> that belongs
to this group.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Automatically starts transaction if it’s not already started.</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"><strong>connection</strong> – <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When group is empty or specified <cite>connection</cite>
doesn’t belong to this group.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.disband">
<tt class="descname">disband</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.disband" title="Permalink to this definition">¶</a></dt>
<dd><p>Forcefully deletes all connections from connection group.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If transaction is active, it’s canceled (<strong>rollback</strong>).</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Any error during transaction finalization doesn’t stop the disband
process, however the exception catched is eventually reported.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.execute_immediate">
<tt class="descname">execute_immediate</tt><big>(</big><em>sql</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.execute_immediate" title="Permalink to this definition">¶</a></dt>
<dd><p>Executes a statement on all member connections without caching its
prepared form.</p>
<p>Automatically starts transaction if it’s not already started.</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"><strong>sql</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – SQL statement to execute.</td>
</tr>
</tbody>
</table>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last"><strong>The statement must not be of a type that returns a result set.</strong>
In most cases (especially cases in which the same statement – perhaps
a parameterized statement – is executed repeatedly), it is better to
create a cursor using the connection’s cursor method, then execute
the statement using one of the cursor’s execute methods.</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"><strong>sql</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – SQL statement to execute.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises DatabaseError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When error is returned from server.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.members">
<tt class="descname">members</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.members" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns list of connection objects that belong to this group.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.prepare">
<tt class="descname">prepare</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.prepare" title="Permalink to this definition">¶</a></dt>
<dd><p>Manually triggers the first phase of a two-phase commit (2PC). Use
of this method is optional; if preparation is not triggered manually,
it will be performed implicitly by commit() in a 2PC.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.remove">
<tt class="descname">remove</tt><big>(</big><em>con</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.remove" title="Permalink to this definition">¶</a></dt>
<dd><p>Removes specified connection from group.</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"><strong>con</strong> – A <a class="reference internal" href="#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">Connection</span></tt></a> instance to remove.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When <cite>con</cite> doesn’t belong to this group or
transaction is active.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.rollback">
<tt class="descname">rollback</tt><big>(</big><em>retaining=False</em>, <em>savepoint=None</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.rollback" title="Permalink to this definition">¶</a></dt>
<dd><p>Rollbacks distributed transaction over member connections.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If transaction is not active, this method does nothing, because
the consensus among Python DB API experts is that transactions should
always be started implicitly, even if that means allowing a <cite>commit()</cite>
or <cite>rollback()</cite> without an actual transaction.</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"><strong>retaining</strong> (<em>boolean</em>) – Indicates whether the transactional context of
the transaction being resolved should be recycled.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When group is empty.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.ConnectionGroup.savepoint">
<tt class="descname">savepoint</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#fdb.ConnectionGroup.savepoint" title="Permalink to this definition">¶</a></dt>
<dd><p>Establishes a named SAVEPOINT on all member connections.
See <a class="reference internal" href="#fdb.Transaction.savepoint" title="fdb.Transaction.savepoint"><tt class="xref py py-meth docutils literal"><span class="pre">Transaction.savepoint()</span></tt></a> for details.</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"><strong>name</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Name for savepoint.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When group is empty.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="attribute">
<dt id="fdb.ConnectionGroup.default_tpb">
<tt class="descname">default_tpb</tt><a class="headerlink" href="#fdb.ConnectionGroup.default_tpb" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read/Write) Deafult Transaction Parameter Block used for transactions.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="transactioncontext">
<h2>TransactionContext<a class="headerlink" href="#transactioncontext" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.TransactionContext">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">TransactionContext</tt><big>(</big><em>transaction</em><big>)</big><a class="headerlink" href="#fdb.TransactionContext" title="Permalink to this definition">¶</a></dt>
<dd><p>Context Manager that manages transaction for object passed to constructor.</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"><strong>transaction</strong> – Any object that supports <cite>begin()</cite>, <cite>commit()</cite> and
<cite>rollback()</cite>.</td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
<div class="section" id="eventconduit">
<h2>EventConduit<a class="headerlink" href="#eventconduit" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.EventConduit">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">EventConduit</tt><big>(</big><em>db_handle</em>, <em>event_names</em><big>)</big><a class="headerlink" href="#fdb.EventConduit" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents a conduit through which database event notifications will flow
into the Python program.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">DO NOT create instances of this class directly! Use only
<a class="reference internal" href="#fdb.Connection.event_conduit" title="fdb.Connection.event_conduit"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.event_conduit()</span></tt></a> to get EventConduit instances.</p>
</div>
<p>From the moment the conduit is created by the <a class="reference internal" href="#fdb.Connection.event_conduit" title="fdb.Connection.event_conduit"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.event_conduit()</span></tt></a>
method, notifications of any events that occur will accumulate asynchronously
within the conduit’s internal queue until the conduit is closed either
explicitly (via the <a class="reference internal" href="#fdb.EventConduit.close" title="fdb.EventConduit.close"><tt class="xref py py-meth docutils literal"><span class="pre">close()</span></tt></a> method) or implicitly (via garbage collection).</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><strong>db_handle</strong> – Database handle.</li>
<li><strong>event_names</strong> – List of strings that represent event names.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<dl class="method">
<dt id="fdb.EventConduit.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.EventConduit.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Cancels the standing request for this conduit to be notified of events.</p>
<p>After this method has been called, this EventConduit object is useless,
and should be discarded.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.EventConduit.flush">
<tt class="descname">flush</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.EventConduit.flush" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear any event notifications that have accumulated in the conduit’s
internal queue.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.EventConduit.wait">
<tt class="descname">wait</tt><big>(</big><em>timeout=None</em><big>)</big><a class="headerlink" href="#fdb.EventConduit.wait" title="Permalink to this definition">¶</a></dt>
<dd><p>Wait for events.</p>
<p>Blocks the calling thread until at least one of the events occurs, or
the specified timeout (if any) expires.</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"><strong>timeout</strong> (<em>integer or float</em>) – Number of seconds (use a float to indicate fractions of
seconds). If not even one of the relevant events has
occurred after timeout seconds, this method will unblock
and return None. The default timeout is infinite.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><cite>None</cite> if the wait timed out, otherwise a dictionary that maps
<cite>event_name -> event_occurrence_count</cite>.</td>
</tr>
</tbody>
</table>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="go">>>>conduit = connection.event_conduit( ('event_a', 'event_b') )</span>
<span class="go">>>>conduit.wait()</span>
<span class="go">{</span>
<span class="go"> 'event_a': 1,</span>
<span class="go"> 'event_b': 0</span>
<span class="go">}</span>
</pre></div>
</div>
<p>In the example above <cite>event_a</cite> occurred once and <cite>event_b</cite> did not occur
at all.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.EventConduit.closed">
<tt class="descname">closed</tt><a class="headerlink" href="#fdb.EventConduit.closed" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (boolean) True if conduit is closed.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="blobreader">
<h2>BlobReader<a class="headerlink" href="#blobreader" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.BlobReader">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">BlobReader</tt><big>(</big><em>blobid</em>, <em>db_handle</em>, <em>tr_handle</em>, <em>is_text</em>, <em>charset</em><big>)</big><a class="headerlink" href="#fdb.BlobReader" title="Permalink to this definition">¶</a></dt>
<dd><p>BlobReader is a “file-like” class, so it acts much like a file instance
opened in <cite>rb</cite> mode.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">DO NOT create instances of this class directly! BlobReader instances are
returned automatically in place of output BLOB values when <cite>stream</cite>
BLOB access is requested via <a class="reference internal" href="#fdb.PreparedStatement.set_stream_blob" title="fdb.PreparedStatement.set_stream_blob"><tt class="xref py py-meth docutils literal"><span class="pre">PreparedStatement.set_stream_blob()</span></tt></a>.</p>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">BlobReader supports iterator protocol, yielding lines like <a class="reference internal" href="#fdb.BlobReader.readline" title="fdb.BlobReader.readline"><tt class="xref py py-meth docutils literal"><span class="pre">readline()</span></tt></a>.</p>
</div>
<dl class="method">
<dt id="fdb.BlobReader.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.BlobReader.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Closes the Reader. Like <a class="reference external" href="http://docs.python.org/library/stdtypes.html#file.close" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">file.close()</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" colspan="2">Raises DatabaseError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">When error is returned by server.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.BlobReader.flush">
<tt class="descname">flush</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.BlobReader.flush" title="Permalink to this definition">¶</a></dt>
<dd><p>Flush the internal buffer. Like <a class="reference external" href="http://docs.python.org/library/stdtypes.html#file.flush" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">file.flush()</span></tt></a>. Does nothing as
it’s pointless for reader.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.BlobReader.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.BlobReader.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the next line from the BLOB. Part of <em>iterator protocol</em>.</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" colspan="2">Raises StopIteration:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">If there are no further lines.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.BlobReader.read">
<tt class="descname">read</tt><big>(</big><em>size=-1</em><big>)</big><a class="headerlink" href="#fdb.BlobReader.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Read at most size bytes from the file (less if the read hits EOF
before obtaining size bytes). If the size argument is negative or omitted,
read all data until EOF is reached. The bytes are returned as a string
object. An empty string is returned when EOF is encountered immediately.
Like <a class="reference external" href="http://docs.python.org/library/stdtypes.html#file.read" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">file.read()</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" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">When reader is closed.</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Performs automatic conversion to <cite>unicode</cite> for TEXT BLOBs, if used
Python is v3 or <cite>connection charset</cite> is defined.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.BlobReader.readline">
<tt class="descname">readline</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.BlobReader.readline" title="Permalink to this definition">¶</a></dt>
<dd><p>Read one entire line from the file. A trailing newline character is
kept in the string (but may be absent when a file ends with an incomplete
line). An empty string is returned when EOF is encountered immediately.
Like <a class="reference external" href="http://docs.python.org/library/stdtypes.html#file.readline" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">file.readline()</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" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">When reader is closed.</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Performs automatic conversion to <cite>unicode</cite> for TEXT BLOBs, if used
Python is v3 or <cite>connection charset</cite> is defined.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.BlobReader.readlines">
<tt class="descname">readlines</tt><big>(</big><em>sizehint=None</em><big>)</big><a class="headerlink" href="#fdb.BlobReader.readlines" title="Permalink to this definition">¶</a></dt>
<dd><p>Read until EOF using <a class="reference internal" href="#fdb.BlobReader.readline" title="fdb.BlobReader.readline"><tt class="xref py py-meth docutils literal"><span class="pre">readline()</span></tt></a> and return a list containing
the lines thus read. The optional sizehint argument (if present) is ignored.
Like <a class="reference external" href="http://docs.python.org/library/stdtypes.html#file.readlines" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">file.readlines()</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Performs automatic conversion to <cite>unicode</cite> for TEXT BLOBs, if used
Python is v3 or <cite>connection charset</cite> is defined.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.BlobReader.seek">
<tt class="descname">seek</tt><big>(</big><em>offset</em>, <em>whence=0</em><big>)</big><a class="headerlink" href="#fdb.BlobReader.seek" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the file’s current position, like stdio‘s <cite>fseek()</cite>.
See <a class="reference external" href="http://docs.python.org/library/stdtypes.html#file.seek" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">file.seek()</span></tt></a> details.</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 simple">
<li><strong>offset</strong> (<em>integer</em>) – Offset from specified position.</li>
<li><strong>whence</strong> (<em>os.SEEK_SET, os.SEEK_CUR or os.SEEK_END</em>) – (Optional) Context for offset.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body"><p class="first last">When reader is closed.</p>
</td>
</tr>
</tbody>
</table>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If BLOB was NOT CREATED as <cite>stream</cite> BLOB, this method raises
<a class="reference internal" href="#fdb.DatabaseError" title="fdb.DatabaseError"><tt class="xref py py-exc docutils literal"><span class="pre">DatabaseError</span></tt></a> exception. This constraint is set by Firebird.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.BlobReader.tell">
<tt class="descname">tell</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.BlobReader.tell" title="Permalink to this definition">¶</a></dt>
<dd><p>Return current position in BLOB, like stdio‘s <cite>ftell()</cite>
and <a class="reference external" href="http://docs.python.org/library/stdtypes.html#file.tell" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">file.tell()</span></tt></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.BlobReader.closed">
<tt class="descname">closed</tt><a class="headerlink" href="#fdb.BlobReader.closed" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (boolean) True is BlobReader is closed.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.BlobReader.mode">
<tt class="descname">mode</tt><a class="headerlink" href="#fdb.BlobReader.mode" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) (string) File mode - always “rb”</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="tpb">
<h2>TPB<a class="headerlink" href="#tpb" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="fdb.TPB">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">TPB</tt><a class="headerlink" href="#fdb.TPB" title="Permalink to this definition">¶</a></dt>
<dd><p>Helper class for convenient and safe construction of custom Transaction
Parameter Blocks.</p>
<dl class="method">
<dt id="fdb.TPB.copy">
<tt class="descname">copy</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TPB.copy" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a copy of self.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.TPB.render">
<tt class="descname">render</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TPB.render" title="Permalink to this definition">¶</a></dt>
<dd><p>Create valid <cite>transaction parameter block</cite> according to current
values of member attributes.</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">Returns:</th><td class="field-body">(string) TPB block.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="attribute">
<dt id="fdb.TPB.access_mode">
<tt class="descname">access_mode</tt><a class="headerlink" href="#fdb.TPB.access_mode" title="Permalink to this definition">¶</a></dt>
<dd><p>(integer) Required access mode (<cite>isc_tpb_read</cite> or <cite>isc_tpb_write</cite>).
<strong>Default:</strong> <cite>isc_tpb_write</cite></p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.TPB.isolation_level">
<tt class="descname">isolation_level</tt><a class="headerlink" href="#fdb.TPB.isolation_level" title="Permalink to this definition">¶</a></dt>
<dd><p>(integer or tuple) Required Transaction Isolation Level.
Single integer value equivalent to <cite>isc_tpb_concurrency</cite> or
<cite>isc_tpb_consistency</cite>, or tuple of exactly two integer values, where
the first one is <cite>isc_tpb_read_committed</cite> and second either
<cite>isc_tpb_rec_version</cite> or <cite>isc_tpb_no_rec_version</cite>.</p>
<p>When value <cite>isc_tpb_read_committed</cite> is assigned without suboption,
the <cite>isc_tpb_rec_version</cite> is assigned as default suboption.</p>
<p><strong>Default:</strong> <cite>isc_tpb_concurrency</cite></p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.TPB.lock_resolution">
<tt class="descname">lock_resolution</tt><a class="headerlink" href="#fdb.TPB.lock_resolution" title="Permalink to this definition">¶</a></dt>
<dd><p>(integer) Required lock resolution method. Either <cite>isc_tpb_wait</cite> or
<cite>isc_tpb_nowait</cite>.</p>
<p><strong>Default:</strong> <cite>isc_tpb_wait</cite></p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.TPB.lock_timeout">
<tt class="descname">lock_timeout</tt><a class="headerlink" href="#fdb.TPB.lock_timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>(integer) Required lock timeout or None.</p>
<p><strong>Default:</strong> <cite>None</cite></p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.TPB.table_reservation">
<tt class="descname">table_reservation</tt><a class="headerlink" href="#fdb.TPB.table_reservation" title="Permalink to this definition">¶</a></dt>
<dd><p>(<a class="reference internal" href="#fdb.TableReservation" title="fdb.TableReservation"><tt class="xref py py-class docutils literal"><span class="pre">TableReservation</span></tt></a>) Table reservation specification.</p>
<p><strong>Default:</strong> <cite>None</cite>.</p>
<p>Instead of changing the value of the TableReservation object itself, you
must change its elements by manipulating it as though it were a dictionary
that mapped “TABLE_NAME”: (sharingMode, accessMode) For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">tpb</span><span class="o">.</span><span class="n">table_reservation</span><span class="p">[</span><span class="s">"MY_TABLE"</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="n">fdb</span><span class="o">.</span><span class="n">isc_tpb_protected</span><span class="p">,</span> <span class="n">fdb</span><span class="o">.</span><span class="n">isc_tpb_lock_write</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
</dd></dl>
<div class="section" id="tablereservation">
<h3>TableReservation<a class="headerlink" href="#tablereservation" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="fdb.TableReservation">
<em class="property">class </em><tt class="descclassname">fdb.</tt><tt class="descname">TableReservation</tt><a class="headerlink" href="#fdb.TableReservation" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary-like helper class that maps
“TABLE_NAME”: (sharingMode, accessMode). It performs validation of values
assigned to keys.</p>
<dl class="method">
<dt id="fdb.TableReservation.copy">
<tt class="descname">copy</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TableReservation.copy" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.TableReservation.get">
<tt class="descname">get</tt><big>(</big><em>key</em>, <em>default=None</em><big>)</big><a class="headerlink" href="#fdb.TableReservation.get" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.TableReservation.items">
<tt class="descname">items</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TableReservation.items" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.TableReservation.iteritems">
<tt class="descname">iteritems</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TableReservation.iteritems" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.TableReservation.iterkeys">
<tt class="descname">iterkeys</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TableReservation.iterkeys" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.TableReservation.itervalues">
<tt class="descname">itervalues</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TableReservation.itervalues" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.TableReservation.keys">
<tt class="descname">keys</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TableReservation.keys" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.TableReservation.render">
<tt class="descname">render</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TableReservation.render" title="Permalink to this definition">¶</a></dt>
<dd><p>Create valid <cite>table access parameter block</cite> according to current
key/value pairs.</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">Returns:</th><td class="field-body">(string) Table access definition block.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.TableReservation.values">
<tt class="descname">values</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.TableReservation.values" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
</div>
</div>
<div class="section" id="module-fdb.fbcore">
<span id="internally-used-classes-exposed-to-driver-users"></span><h2>Internally used classes exposed to driver users<a class="headerlink" href="#module-fdb.fbcore" title="Permalink to this headline">¶</a></h2>
<div class="section" id="rowmapping">
<h3>RowMapping<a class="headerlink" href="#rowmapping" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="fdb.fbcore._RowMapping">
<em class="property">class </em><tt class="descclassname">fdb.fbcore.</tt><tt class="descname">_RowMapping</tt><big>(</big><em>description</em>, <em>row</em><big>)</big><a class="headerlink" href="#fdb.fbcore._RowMapping" title="Permalink to this definition">¶</a></dt>
<dd><p>An internal dictionary-like class that wraps a row of results in order to
map field name to field value.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>We make ABSOLUTELY NO GUARANTEES about the return value of the
<cite>fetch(one|many|all)</cite> methods except that it is a sequence indexed by field
position, and no guarantees about the return value of the
<cite>fetch(one|many|all)map</cite> methods except that it is a mapping of field name
to field value.</p>
<p class="last">Therefore, client programmers should NOT rely on the return value being
an instance of a particular class or type.</p>
</div>
<dl class="method">
<dt id="fdb.fbcore._RowMapping.get">
<tt class="descname">get</tt><big>(</big><em>fieldName</em>, <em>defaultValue=None</em><big>)</big><a class="headerlink" href="#fdb.fbcore._RowMapping.get" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.fbcore._RowMapping.items">
<tt class="descname">items</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.fbcore._RowMapping.items" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.fbcore._RowMapping.iteritems">
<tt class="descname">iteritems</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.fbcore._RowMapping.iteritems" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.fbcore._RowMapping.iterkeys">
<tt class="descname">iterkeys</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.fbcore._RowMapping.iterkeys" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.fbcore._RowMapping.itervalues">
<tt class="descname">itervalues</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.fbcore._RowMapping.itervalues" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.fbcore._RowMapping.keys">
<tt class="descname">keys</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.fbcore._RowMapping.keys" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="fdb.fbcore._RowMapping.values">
<tt class="descname">values</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.fbcore._RowMapping.values" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
</div>
</div>
<div class="section" id="module-fdb.services">
<span id="services"></span><span id="services-api"></span><h2>Services<a class="headerlink" href="#module-fdb.services" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id1">
<h3>Module globals<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<dl class="data">
<dt id="fdb.services.SHUT_NORMAL">
<tt class="descclassname">fdb.services.</tt><tt class="descname">SHUT_NORMAL</tt><a class="headerlink" href="#fdb.services.SHUT_NORMAL" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.SHUT_MULTI">
<tt class="descclassname">fdb.services.</tt><tt class="descname">SHUT_MULTI</tt><a class="headerlink" href="#fdb.services.SHUT_MULTI" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.SHUT_SINGLE">
<tt class="descclassname">fdb.services.</tt><tt class="descname">SHUT_SINGLE</tt><a class="headerlink" href="#fdb.services.SHUT_SINGLE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.SHUT_FULL">
<tt class="descclassname">fdb.services.</tt><tt class="descname">SHUT_FULL</tt><a class="headerlink" href="#fdb.services.SHUT_FULL" title="Permalink to this definition">¶</a></dt>
<dd><p>These constants are to be passed as the <cite>shutdown_mode</cite> parameter to <a class="reference internal" href="#fdb.services.Connection.shutdown" title="fdb.services.Connection.shutdown"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.shutdown()</span></tt></a></p>
</dd></dl>
<dl class="data">
<dt id="fdb.services.SHUT_FORCE">
<tt class="descclassname">fdb.services.</tt><tt class="descname">SHUT_FORCE</tt><a class="headerlink" href="#fdb.services.SHUT_FORCE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.SHUT_DENY_NEW_TRANSACTIONS">
<tt class="descclassname">fdb.services.</tt><tt class="descname">SHUT_DENY_NEW_TRANSACTIONS</tt><a class="headerlink" href="#fdb.services.SHUT_DENY_NEW_TRANSACTIONS" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.SHUT_DENY_NEW_ATTACHMENTS">
<tt class="descclassname">fdb.services.</tt><tt class="descname">SHUT_DENY_NEW_ATTACHMENTS</tt><a class="headerlink" href="#fdb.services.SHUT_DENY_NEW_ATTACHMENTS" title="Permalink to this definition">¶</a></dt>
<dd><p>These constants are to be passed as the <cite>shutdown_method</cite> parameter to <a class="reference internal" href="#fdb.services.Connection.shutdown" title="fdb.services.Connection.shutdown"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.shutdown()</span></tt></a></p>
</dd></dl>
<dl class="data">
<dt id="fdb.services.WRITE_FORCED">
<tt class="descclassname">fdb.services.</tt><tt class="descname">WRITE_FORCED</tt><a class="headerlink" href="#fdb.services.WRITE_FORCED" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.WRITE_BUFFERED">
<tt class="descclassname">fdb.services.</tt><tt class="descname">WRITE_BUFFERED</tt><a class="headerlink" href="#fdb.services.WRITE_BUFFERED" title="Permalink to this definition">¶</a></dt>
<dd><p>These constants are to be passed as the <cite>mode</cite> parameter to <tt class="xref py py-meth docutils literal"><span class="pre">Connection.setWriteMode()</span></tt></p>
</dd></dl>
<dl class="data">
<dt id="fdb.services.ACCESS_READ_WRITE">
<tt class="descclassname">fdb.services.</tt><tt class="descname">ACCESS_READ_WRITE</tt><a class="headerlink" href="#fdb.services.ACCESS_READ_WRITE" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.ACCESS_READ_ONLY">
<tt class="descclassname">fdb.services.</tt><tt class="descname">ACCESS_READ_ONLY</tt><a class="headerlink" href="#fdb.services.ACCESS_READ_ONLY" title="Permalink to this definition">¶</a></dt>
<dd><p>These constants are to be passed as the <cite>mode</cite> parameter to <tt class="xref py py-meth docutils literal"><span class="pre">Connection.setAccessMode()</span></tt></p>
</dd></dl>
<dl class="data">
<dt id="fdb.services.CAPABILITY_MULTI_CLIENT">
<tt class="descclassname">fdb.services.</tt><tt class="descname">CAPABILITY_MULTI_CLIENT</tt><a class="headerlink" href="#fdb.services.CAPABILITY_MULTI_CLIENT" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.CAPABILITY_REMOTE_HOP">
<tt class="descclassname">fdb.services.</tt><tt class="descname">CAPABILITY_REMOTE_HOP</tt><a class="headerlink" href="#fdb.services.CAPABILITY_REMOTE_HOP" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.CAPABILITY_SERVER_CONFIG">
<tt class="descclassname">fdb.services.</tt><tt class="descname">CAPABILITY_SERVER_CONFIG</tt><a class="headerlink" href="#fdb.services.CAPABILITY_SERVER_CONFIG" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.CAPABILITY_QUOTED_FILENAME">
<tt class="descclassname">fdb.services.</tt><tt class="descname">CAPABILITY_QUOTED_FILENAME</tt><a class="headerlink" href="#fdb.services.CAPABILITY_QUOTED_FILENAME" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="data">
<dt id="fdb.services.CAPABILITY_NO_SERVER_SHUTDOWN">
<tt class="descclassname">fdb.services.</tt><tt class="descname">CAPABILITY_NO_SERVER_SHUTDOWN</tt><a class="headerlink" href="#fdb.services.CAPABILITY_NO_SERVER_SHUTDOWN" title="Permalink to this definition">¶</a></dt>
<dd><p>These constants are return values of <a class="reference internal" href="#fdb.services.Connection.get_server_capabilities" title="fdb.services.Connection.get_server_capabilities"><tt class="xref py py-meth docutils literal"><span class="pre">Connection.get_server_capabilities()</span></tt></a></p>
</dd></dl>
</div>
<div class="section" id="id2">
<h3>Functions<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="fdb.services.connect">
<tt class="descclassname">fdb.services.</tt><tt class="descname">connect</tt><big>(</big><em>host='service_mgr'</em>, <em>user='sysdba'</em>, <em>password=None</em><big>)</big><a class="headerlink" href="#fdb.services.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Establishes a connection to the Services Manager.</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><strong>host</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – (optional) Host machine specification. Local by default.</li>
<li><strong>user</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – (optional) Administrative user name. Defaults to content
of environment variable <cite>‘ISC_USER’</cite> or <cite>‘SYSDBA’</cite>.</li>
<li><strong>password</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Administrative user password. Default is content
of environment variable <cite>‘ISC_PASSWORD’</cite>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">By definition, a Services Manager connection is bound to a particular
host. Therefore, the database specified as a parameter to methods such as
<cite>getStatistics</cite> MUST NOT include the host name of the database server.</p>
</div>
</dd></dl>
</div>
<div class="section" id="id3">
<h3>Connection<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="fdb.services.Connection">
<em class="property">class </em><tt class="descclassname">fdb.services.</tt><tt class="descname">Connection</tt><big>(</big><em>host</em>, <em>user</em>, <em>password</em>, <em>charset=None</em><big>)</big><a class="headerlink" href="#fdb.services.Connection" title="Permalink to this definition">¶</a></dt>
<dd><p>Represents a sevice connection between the database client (the Python process)
and the database server.</p>
<div class="admonition important">
<p class="first admonition-title">Important</p>
<p class="last">DO NOT create instances of this class directly! Use only <a class="reference internal" href="#fdb.services.connect" title="fdb.services.connect"><tt class="xref py py-func docutils literal"><span class="pre">connect()</span></tt></a>
to get Connection instances.</p>
</div>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">Connection supports the iterator protocol, yielding lines of result like
<a class="reference internal" href="#fdb.services.Connection.readline" title="fdb.services.Connection.readline"><tt class="xref py py-meth docutils literal"><span class="pre">readline()</span></tt></a>.</p>
</div>
<dl class="method">
<dt id="fdb.services.Connection.activate_shadow">
<tt class="descname">activate_shadow</tt><big>(</big><em>database</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.activate_shadow" title="Permalink to this definition">¶</a></dt>
<dd><p>Activate Database Shadow(s).</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"><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.add_user">
<tt class="descname">add_user</tt><big>(</big><em>user</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.add_user" title="Permalink to this definition">¶</a></dt>
<dd><p>Add new user.</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"><strong>user</strong> (<a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a>) – Instance of <a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a> with <strong>at least</strong> its
<a class="reference internal" href="#fdb.services.User.name" title="fdb.services.User.name"><tt class="xref py py-attr docutils literal"><span class="pre">name</span></tt></a> and <a class="reference internal" href="#fdb.services.User.password" title="fdb.services.User.password"><tt class="xref py py-attr docutils literal"><span class="pre">password</span></tt></a> attributes specified
as non-empty values. All other attributes are optional.</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This method ignores the <a class="reference internal" href="#fdb.services.User.user_id" title="fdb.services.User.user_id"><tt class="xref py py-attr docutils literal"><span class="pre">user_id</span></tt></a> and <a class="reference internal" href="#fdb.services.User.group_id" title="fdb.services.User.group_id"><tt class="xref py py-attr docutils literal"><span class="pre">group_id</span></tt></a>
attributes of <a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a> regardless of their values.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.backup">
<tt class="descname">backup</tt><big>(</big><em>source_database</em>, <em>dest_filenames</em>, <em>dest_file_sizes=()</em>, <em>ignore_checksums=0</em>, <em>ignore_limbo_transactions=0</em>, <em>metadata_only=0</em>, <em>collect_garbage=1</em>, <em>transportable=1</em>, <em>convert_external_tables_to_internal=0</em>, <em>compressed=1</em>, <em>no_db_triggers=0</em>, <em>callback=None</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.backup" title="Permalink to this definition">¶</a></dt>
<dd><p>Request logical (GBAK) database backup. <strong>(ASYNC service)</strong></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><strong>source_database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Source database specification.</li>
<li><strong>dest_filenames</strong> (<em>string or tuple of strings</em>) – Backup file(s) specification.</li>
<li><strong>dest_file_sizes</strong> (<em>tuple of integers</em>) – (optional) specification of backup file max. sizes.</li>
<li><strong>ignore_checksums</strong> (<em>integer</em>) – <cite>1</cite> to ignore checksums.</li>
<li><strong>ignore_limbo_transactions</strong> (<em>integer</em>) – <cite>1</cite> to ignore limbo transactions.</li>
<li><strong>metadata_only</strong> (<em>integer</em>) – <cite>1</cite> to create only metadata backup.</li>
<li><strong>collect_garbage</strong> (<em>integer</em>) – <cite>0</cite> to skip garbage collection.</li>
<li><strong>transportable</strong> (<em>integer</em>) – <cite>0</cite> to do not create transportable backup.</li>
<li><strong>convert_external_tables_to_internal</strong> (<em>integer</em>) – <cite>1</cite> to convert
external table to internal ones.</li>
<li><strong>compressed</strong> (<em>integer</em>) – <cite>0</cite> to create uncompressed backup.</li>
<li><strong>no_db_triggers</strong> (<em>integer</em>) – <cite>1</cite> to disable database triggers temporarily.</li>
<li><strong>callback</strong> (<em>function</em>) – Function to call back with each output line.
Function must accept only one parameter: line of output.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>If <cite>callback</cite> is not specified, backup log could be retrieved through
<a class="reference internal" href="#fdb.services.Connection.readline" title="fdb.services.Connection.readline"><tt class="xref py py-meth docutils literal"><span class="pre">readline()</span></tt></a>, <a class="reference internal" href="#fdb.services.Connection.readlines" title="fdb.services.Connection.readlines"><tt class="xref py py-meth docutils literal"><span class="pre">readlines()</span></tt></a>, iteration over <cite>Connection</cite> or
ignored via call to <a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Until backup report is not fully fetched from service (or ignored via
<a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>), any attempt to start another asynchronous service will
fail with exception.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.bring_online">
<tt class="descname">bring_online</tt><big>(</big><em>database</em>, <em>online_mode=0</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.bring_online" title="Permalink to this definition">¶</a></dt>
<dd><p>Bring previously shut down database back online.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>online_mode</strong> (<em>integer</em>) – (Optional) One from following constants:
<a class="reference internal" href="#fdb.services.SHUT_SINGLE" title="fdb.services.SHUT_SINGLE"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_SINGLE</span></tt></a>, <a class="reference internal" href="#fdb.services.SHUT_MULTI" title="fdb.services.SHUT_MULTI"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_MULTI</span></tt></a>
or <a class="reference internal" href="#fdb.services.SHUT_NORMAL" title="fdb.services.SHUT_NORMAL"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_NORMAL</span></tt></a> (<strong>Default</strong>).</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">See also <a class="reference internal" href="#fdb.services.Connection.shutdown" title="fdb.services.Connection.shutdown"><tt class="xref py py-meth docutils literal"><span class="pre">shutdown()</span></tt></a> method.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Close the connection now (rather than whenever <cite>__del__</cite> is called).
The connection will be unusable from this point forward; an <tt class="xref py py-exc docutils literal"><span class="pre">Error</span></tt>
(or subclass) exception will be raised if any operation is attempted
with the connection.</p>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.commit_limbo_transaction">
<tt class="descname">commit_limbo_transaction</tt><big>(</big><em>database</em>, <em>transaction_id</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.commit_limbo_transaction" title="Permalink to this definition">¶</a></dt>
<dd><p>Resolve limbo transaction with commit.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>transaction_id</strong> (<em>integer</em>) – ID of Transaction to resolve.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_architecture">
<tt class="descname">get_architecture</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_architecture" title="Permalink to this definition">¶</a></dt>
<dd><p>Get Firebird Server architecture.</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">Returns string:</th><td class="field-body">Architecture (example: ‘Firebird/linux AMD64’).</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_attached_database_names">
<tt class="descname">get_attached_database_names</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_attached_database_names" title="Permalink to this definition">¶</a></dt>
<dd><p>Get list of attached databases.</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">Returns list:</th><td class="field-body">Filenames of attached databases.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_connection_count">
<tt class="descname">get_connection_count</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_connection_count" title="Permalink to this definition">¶</a></dt>
<dd><p>Get number of attachments to server.</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" colspan="2">Returns integer:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">Directory path.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_home_directory">
<tt class="descname">get_home_directory</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_home_directory" title="Permalink to this definition">¶</a></dt>
<dd><p>Get Firebird Home (installation) Directory.</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">Returns string:</th><td class="field-body">Directory path.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_limbo_transaction_ids">
<tt class="descname">get_limbo_transaction_ids</tt><big>(</big><em>database</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_limbo_transaction_ids" title="Permalink to this definition">¶</a></dt>
<dd><p>Get list of transactions in limbo.</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"><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns list:</th><td class="field-body">Transaction IDs.</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2">Raises InternalError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">When can’t process the result buffer.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_lock_file_directory">
<tt class="descname">get_lock_file_directory</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_lock_file_directory" title="Permalink to this definition">¶</a></dt>
<dd><p>Get directory location for Firebird lock files.</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">Returns string:</th><td class="field-body">Directory path.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_log">
<tt class="descname">get_log</tt><big>(</big><em>callback=None</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_log" title="Permalink to this definition">¶</a></dt>
<dd><p>Request content of Firebird Server log. <strong>(ASYNC service)</strong></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"><strong>callback</strong> (<em>function</em>) – Function to call back with each output line.
Function must accept only one parameter: line of output.</td>
</tr>
</tbody>
</table>
<p>If <cite>callback</cite> is not specified, log content could be retrieved through
<a class="reference internal" href="#fdb.services.Connection.readline" title="fdb.services.Connection.readline"><tt class="xref py py-meth docutils literal"><span class="pre">readline()</span></tt></a>, <a class="reference internal" href="#fdb.services.Connection.readlines" title="fdb.services.Connection.readlines"><tt class="xref py py-meth docutils literal"><span class="pre">readlines()</span></tt></a>, iteration over <cite>Connection</cite> or
ignored via call to <a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Until log content is not fully fetched from service (or ignored via
<a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>), any attempt to start another asynchronous service will
fail with exception.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_message_file_directory">
<tt class="descname">get_message_file_directory</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_message_file_directory" title="Permalink to this definition">¶</a></dt>
<dd><p>Get directory with Firebird message file.</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">Returns string:</th><td class="field-body">Directory path.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_security_database_path">
<tt class="descname">get_security_database_path</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_security_database_path" title="Permalink to this definition">¶</a></dt>
<dd><p>Get full path to Firebird security database.</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">Returns string:</th><td class="field-body">Path (path+filename) to security database.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_server_capabilities">
<tt class="descname">get_server_capabilities</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_server_capabilities" title="Permalink to this definition">¶</a></dt>
<dd><p>Get list of Firebird capabilities.</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">Returns tuple:</th><td class="field-body">Capability info codes for each capability reported by
server.</td>
</tr>
</tbody>
</table>
<p>Next fdb.services constants define possible info codes returned:</p>
<div class="highlight-python"><pre>:data:`CAPABILITY_MULTI_CLIENT`
:data:`CAPABILITY_REMOTE_HOP`
:data:`CAPABILITY_SERVER_CONFIG`
:data:`CAPABILITY_QUOTED_FILENAME`
:data:`CAPABILITY_NO_SERVER_SHUTDOWN`</pre>
</div>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="go">>>>fdb.services.CAPABILITY_REMOTE_HOP in svc.get_server_capabilities()</span>
<span class="go">True</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_server_version">
<tt class="descname">get_server_version</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_server_version" title="Permalink to this definition">¶</a></dt>
<dd><p>Get Firebird version.</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">Returns string:</th><td class="field-body">Firebird version (example: ‘LI-V2.5.2.26536 Firebird 2.5’).</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_service_manager_version">
<tt class="descname">get_service_manager_version</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_service_manager_version" title="Permalink to this definition">¶</a></dt>
<dd><p>Get Firebird Service Manager version number.</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" colspan="2">Returns integer:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">Version number.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_statistics">
<tt class="descname">get_statistics</tt><big>(</big><em>database</em>, <em>show_only_db_log_pages=0</em>, <em>show_only_db_header_pages=0</em>, <em>show_user_data_pages=1</em>, <em>show_user_index_pages=1</em>, <em>show_system_tables_and_indexes=0</em>, <em>show_record_versions=0</em>, <em>callback=None</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_statistics" title="Permalink to this definition">¶</a></dt>
<dd><p>Request database statisctics. <strong>(ASYNC service)</strong></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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database specification.</li>
<li><strong>show_only_db_log_pages</strong> (<em>integer</em>) – <cite>1</cite> to analyze only log pages.</li>
<li><strong>show_only_db_header_pages</strong> (<em>integer</em>) – <cite>1</cite> to analyze only database
header. When set, all other parameters are ignored.</li>
<li><strong>show_user_data_pages</strong> (<em>integer</em>) – <cite>0</cite> to skip user data analysis.</li>
<li><strong>show_user_index_pages</strong> (<em>integer</em>) – <cite>0</cite> to skip user index analysis.</li>
<li><strong>show_system_tables_and_indexes</strong> (<em>integer</em>) – <cite>1</cite> to analyze system
tables and indices.</li>
<li><strong>show_record_versions</strong> (<em>integer</em>) – <cite>1</cite> to analyze record versions.</li>
<li><strong>callback</strong> (<em>function</em>) – Function to call back with each output line.
Function must accept only one parameter: line of output.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>If <cite>callback</cite> is not specified, statistical report could be retrieved
through <a class="reference internal" href="#fdb.services.Connection.readline" title="fdb.services.Connection.readline"><tt class="xref py py-meth docutils literal"><span class="pre">readline()</span></tt></a>, <a class="reference internal" href="#fdb.services.Connection.readlines" title="fdb.services.Connection.readlines"><tt class="xref py py-meth docutils literal"><span class="pre">readlines()</span></tt></a>, iteration over <cite>Connection</cite>
or ignored via call to <a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Until report is not fully fetched from service (or ignored via
<a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>), any attempt to start another asynchronous service will
fail with exception.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.get_users">
<tt class="descname">get_users</tt><big>(</big><em>user_name=None</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.get_users" title="Permalink to this definition">¶</a></dt>
<dd><p>Get information about user(s).</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"><strong>user_name</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – (Optional) When specified, returns information
only about user with specified user name.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns list:</th><td class="field-body"><a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a> instances.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.isrunning">
<tt class="descname">isrunning</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.isrunning" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns True if service is running.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Some services like <a class="reference internal" href="#fdb.services.Connection.backup" title="fdb.services.Connection.backup"><tt class="xref py py-meth docutils literal"><span class="pre">backup()</span></tt></a> or <a class="reference internal" href="#fdb.services.Connection.sweep" title="fdb.services.Connection.sweep"><tt class="xref py py-meth docutils literal"><span class="pre">sweep()</span></tt></a> may take time to
comlete, so they’re called asynchronously. Until they’re finished,
no other async service could be started.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.modify_user">
<tt class="descname">modify_user</tt><big>(</big><em>user</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.modify_user" title="Permalink to this definition">¶</a></dt>
<dd><p>Modify user information.</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"><strong>user</strong> (<a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a>) – Instance of <a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a> with <strong>at least</strong> its
<a class="reference internal" href="#fdb.services.User.name" title="fdb.services.User.name"><tt class="xref py py-attr docutils literal"><span class="pre">name</span></tt></a> attribute specified as non-empty value.</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This method sets <a class="reference internal" href="#fdb.services.User.first_name" title="fdb.services.User.first_name"><tt class="xref py py-attr docutils literal"><span class="pre">first_name</span></tt></a>, <a class="reference internal" href="#fdb.services.User.middle_name" title="fdb.services.User.middle_name"><tt class="xref py py-attr docutils literal"><span class="pre">middle_name</span></tt></a>
and <a class="reference internal" href="#fdb.services.User.last_name" title="fdb.services.User.last_name"><tt class="xref py py-attr docutils literal"><span class="pre">last_name</span></tt></a> to their actual values, and ignores
the <a class="reference internal" href="#fdb.services.User.user_id" title="fdb.services.User.user_id"><tt class="xref py py-attr docutils literal"><span class="pre">user_id</span></tt></a> and <a class="reference internal" href="#fdb.services.User.group_id" title="fdb.services.User.group_id"><tt class="xref py py-attr docutils literal"><span class="pre">group_id</span></tt></a> attributes
regardless of their values. <a class="reference internal" href="#fdb.services.User.password" title="fdb.services.User.password"><tt class="xref py py-attr docutils literal"><span class="pre">password</span></tt></a> is set <strong>only</strong>
when it has value.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.nbackup">
<tt class="descname">nbackup</tt><big>(</big><em>source_database</em>, <em>dest_filename</em>, <em>nbackup_level=0</em>, <em>no_db_triggers=0</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.nbackup" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform physical (NBACKUP) database backup.</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><strong>source_database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Source database specification.</li>
<li><strong>dest_filename</strong> – Backup file specification.</li>
<li><strong>nbackup_level</strong> (<em>integer</em>) – Incremental backup level.</li>
<li><strong>no_db_triggers</strong> (<em>integer</em>) – <cite>1</cite> to disable database triggers temporarily.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Method call will not return until action is finished.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the next result line from service manager. Part of <em>iterator
protocol</em>.</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" colspan="2">Raises StopIteration:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">If there are no further lines.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.nrestore">
<tt class="descname">nrestore</tt><big>(</big><em>source_filenames</em>, <em>dest_filename</em>, <em>no_db_triggers=0</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.nrestore" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform restore from physical (NBACKUP) database backup.</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><strong>source_filenames</strong> (<em>string or tuple of strings</em>) – Backup file(s) specification.</li>
<li><strong>dest_filename</strong> – Database file specification.</li>
<li><strong>no_db_triggers</strong> (<em>integer</em>) – <cite>1</cite> to disable database triggers temporarily.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Method call will not return until action is finished.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.readline">
<tt class="descname">readline</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.readline" title="Permalink to this definition">¶</a></dt>
<dd><p>Get next line of textual output from last service query.</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">Returns string:</th><td class="field-body">Output line.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.readlines">
<tt class="descname">readlines</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.readlines" title="Permalink to this definition">¶</a></dt>
<dd><p>Get list of remaining output lines from last service query.</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">Returns list:</th><td class="field-body">Service output.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises ProgrammingError:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">When service is not in <a class="reference internal" href="#fdb.services.Connection.fetching" title="fdb.services.Connection.fetching"><tt class="xref py py-attr docutils literal"><span class="pre">fetching</span></tt></a> mode.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.remove_user">
<tt class="descname">remove_user</tt><big>(</big><em>user</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.remove_user" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove user.</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"><strong>user</strong> (string or <a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a>) – User name or Instance of <a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a> with <strong>at least</strong> its
<a class="reference internal" href="#fdb.services.User.name" title="fdb.services.User.name"><tt class="xref py py-attr docutils literal"><span class="pre">name</span></tt></a> attribute specified as non-empty value.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.repair">
<tt class="descname">repair</tt><big>(</big><em>database</em>, <em>read_only_validation=0</em>, <em>ignore_checksums=0</em>, <em>kill_unavailable_shadows=0</em>, <em>mend_database=0</em>, <em>validate_database=1</em>, <em>validate_record_fragments=1</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.repair" title="Permalink to this definition">¶</a></dt>
<dd><p>Database Validation and Repair.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>read_only_validation</strong> (<em>integer</em>) – <cite>1</cite> to prevent any database changes.</li>
<li><strong>ignore_checksums</strong> (<em>integer</em>) – <cite>1</cite> to ignore page checksum errors.</li>
<li><strong>kill_unavailable_shadows</strong> (<em>integer</em>) – <cite>1</cite> to kill unavailable shadows.</li>
<li><strong>mend_database</strong> (<em>integer</em>) – <cite>1</cite> to fix database for backup.</li>
<li><strong>validate_database</strong> (<em>integer</em>) – <cite>0</cite> to skip database validation.</li>
<li><strong>validate_record_fragments</strong> (<em>integer</em>) – <cite>0</cite> to skip validation of
record fragments.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Method call will not return until action is finished.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.restore">
<tt class="descname">restore</tt><big>(</big><em>source_filenames</em>, <em>dest_filenames</em>, <em>dest_file_pages=()</em>, <em>page_size=None</em>, <em>cache_buffers=None</em>, <em>access_mode_read_only=0</em>, <em>replace=0</em>, <em>deactivate_indexes=0</em>, <em>do_not_restore_shadows=0</em>, <em>do_not_enforce_constraints=0</em>, <em>commit_after_each_table=0</em>, <em>use_all_page_space=0</em>, <em>no_db_triggers=0</em>, <em>metadata_only=0</em>, <em>callback=None</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.restore" title="Permalink to this definition">¶</a></dt>
<dd><p>Request database restore from logical (GBAK) backup. <strong>(ASYNC service)</strong></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><strong>source_filenames</strong> (<em>string or tuple of strings</em>) – Backup file(s) specification.</li>
<li><strong>dest_filenames</strong> (<em>string or tuple of strings</em>) – Database file(s) specification.</li>
<li><strong>dest_file_pages</strong> (<em>tuple of integers</em>) – (optional) specification of database file max.
# of pages.</li>
<li><strong>page_size</strong> (<em>integer</em>) – (optional) Page size.</li>
<li><strong>cache_buffers</strong> (<em>integer</em>) – (optional) Size of page-cache for this
database.</li>
<li><strong>access_mode_read_only</strong> (<em>integer</em>) – <cite>1</cite> to create R/O database.</li>
<li><strong>replace</strong> (<em>integer</em>) – <cite>1</cite> to replace existing database.</li>
<li><strong>deactivate_indexes</strong> (<em>integer</em>) – <cite>1</cite> to do not activate indices.</li>
<li><strong>do_not_restore_shadows</strong> (<em>integer</em>) – <cite>1</cite> to do not restore shadows.</li>
<li><strong>do_not_enforce_constraints</strong> (<em>integer</em>) – <cite>1</cite> to do not enforce
constraints during restore.</li>
<li><strong>commit_after_each_table</strong> (<em>integer</em>) – <cite>1</cite> to commit after each table
is restored.</li>
<li><strong>use_all_page_space</strong> (<em>integer</em>) – <cite>1</cite> to use all space on data pages.</li>
<li><strong>no_db_triggers</strong> (<em>integer</em>) – <cite>1</cite> to disable database triggers temporarily.</li>
<li><strong>metadata_only</strong> (<em>integer</em>) – <cite>1</cite> to restore only database metadata.</li>
<li><strong>callback</strong> (<em>function</em>) – Function to call back with each output line.
Function must accept only one parameter: line of output.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>If <cite>callback</cite> is not specified, restore log could be retrieved through
<a class="reference internal" href="#fdb.services.Connection.readline" title="fdb.services.Connection.readline"><tt class="xref py py-meth docutils literal"><span class="pre">readline()</span></tt></a>, <a class="reference internal" href="#fdb.services.Connection.readlines" title="fdb.services.Connection.readlines"><tt class="xref py py-meth docutils literal"><span class="pre">readlines()</span></tt></a>, iteration over <cite>Connection</cite> or
ignored via call to <a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Until restore report is not fully fetched from service (or ignored via
<a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>), any attempt to start another asynchronous service will
fail with exception.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.rollback_limbo_transaction">
<tt class="descname">rollback_limbo_transaction</tt><big>(</big><em>database</em>, <em>transaction_id</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.rollback_limbo_transaction" title="Permalink to this definition">¶</a></dt>
<dd><p>Resolve limbo transaction with rollback.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>transaction_id</strong> (<em>integer</em>) – ID of Transaction to resolve.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.set_access_mode">
<tt class="descname">set_access_mode</tt><big>(</big><em>database</em>, <em>mode</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.set_access_mode" title="Permalink to this definition">¶</a></dt>
<dd><p>Set Database Access mode: Read Only or Read/Write</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>mode</strong> (<em>integer</em>) – One from following constants:
<a class="reference internal" href="#fdb.services.ACCESS_READ_WRITE" title="fdb.services.ACCESS_READ_WRITE"><tt class="xref py py-data docutils literal"><span class="pre">ACCESS_READ_WRITE</span></tt></a> or
<a class="reference internal" href="#fdb.services.ACCESS_READ_ONLY" title="fdb.services.ACCESS_READ_ONLY"><tt class="xref py py-data docutils literal"><span class="pre">ACCESS_READ_ONLY</span></tt></a></li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.set_default_page_buffers">
<tt class="descname">set_default_page_buffers</tt><big>(</big><em>database</em>, <em>n</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.set_default_page_buffers" title="Permalink to this definition">¶</a></dt>
<dd><p>Set individual page cache size for Database.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>n</strong> (<em>integer</em>) – Number of pages.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.set_reserve_page_space">
<tt class="descname">set_reserve_page_space</tt><big>(</big><em>database</em>, <em>reserve_space</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.set_reserve_page_space" title="Permalink to this definition">¶</a></dt>
<dd><p>Set data page space reservation policy.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>reserve_space</strong> (<em>boolean</em>) – <cite>True</cite> to reserve space, <cite>False</cite> to do not.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.set_sql_dialect">
<tt class="descname">set_sql_dialect</tt><big>(</big><em>database</em>, <em>dialect</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.set_sql_dialect" title="Permalink to this definition">¶</a></dt>
<dd><p>Set SQL Dialect for Database.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>dialect</strong> (<em>integer</em>) – <cite>1</cite> or <cite>3</cite>.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.set_sweep_interval">
<tt class="descname">set_sweep_interval</tt><big>(</big><em>database</em>, <em>n</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.set_sweep_interval" title="Permalink to this definition">¶</a></dt>
<dd><p>Set treshold for automatic sweep.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>n</strong> (<em>integer</em>) – Sweep treshold, or <cite>0</cite> to disable automatic sweep.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.set_write_mode">
<tt class="descname">set_write_mode</tt><big>(</big><em>database</em>, <em>mode</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.set_write_mode" title="Permalink to this definition">¶</a></dt>
<dd><p>Set Disk Write Mode: Sync (forced writes) or Async (buffered).</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>mode</strong> (<em>integer</em>) – One from following constants:
<a class="reference internal" href="#fdb.services.WRITE_FORCED" title="fdb.services.WRITE_FORCED"><tt class="xref py py-data docutils literal"><span class="pre">WRITE_FORCED</span></tt></a> or
<a class="reference internal" href="#fdb.services.WRITE_BUFFERED" title="fdb.services.WRITE_BUFFERED"><tt class="xref py py-data docutils literal"><span class="pre">WRITE_BUFFERED</span></tt></a></li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.shutdown">
<tt class="descname">shutdown</tt><big>(</big><em>database</em>, <em>shutdown_mode</em>, <em>shutdown_method</em>, <em>timeout</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.shutdown" title="Permalink to this definition">¶</a></dt>
<dd><p>Database shutdown.</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><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</li>
<li><strong>shutdown_mode</strong> (<em>integer</em>) – One from following constants:
<a class="reference internal" href="#fdb.services.SHUT_SINGLE" title="fdb.services.SHUT_SINGLE"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_SINGLE</span></tt></a>, <a class="reference internal" href="#fdb.services.SHUT_MULTI" title="fdb.services.SHUT_MULTI"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_MULTI</span></tt></a>
or <a class="reference internal" href="#fdb.services.SHUT_FULL" title="fdb.services.SHUT_FULL"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_FULL</span></tt></a>.</li>
<li><strong>shutdown_method</strong> (<em>integer</em>) – One from following constants:
<a class="reference internal" href="#fdb.services.SHUT_FORCE" title="fdb.services.SHUT_FORCE"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_FORCE</span></tt></a>,
<a class="reference internal" href="#fdb.services.SHUT_DENY_NEW_TRANSACTIONS" title="fdb.services.SHUT_DENY_NEW_TRANSACTIONS"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_DENY_NEW_TRANSACTIONS</span></tt></a>
or <a class="reference internal" href="#fdb.services.SHUT_DENY_NEW_ATTACHMENTS" title="fdb.services.SHUT_DENY_NEW_ATTACHMENTS"><tt class="xref py py-data docutils literal"><span class="pre">SHUT_DENY_NEW_ATTACHMENTS</span></tt></a>.</li>
<li><strong>timeout</strong> (<em>integer</em>) – Time in seconds, that the shutdown must complete in.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">See also <a class="reference internal" href="#fdb.services.Connection.bring_online" title="fdb.services.Connection.bring_online"><tt class="xref py py-meth docutils literal"><span class="pre">bring_online()</span></tt></a> method.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.sweep">
<tt class="descname">sweep</tt><big>(</big><em>database</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.sweep" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform Database Sweep.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Method call will not return until sweep is finished.</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"><strong>database</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Database filename or alias.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.trace_list">
<tt class="descname">trace_list</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.trace_list" title="Permalink to this definition">¶</a></dt>
<dd><p>Get information about existing trace sessions.</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" colspan="2">Returns dictionary:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body"><p class="first">Mapping <cite>SESSION_ID -> SESSION_PARAMS</cite></p>
<p>Session parameters is another dictionary with next keys:</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">name:</th><td class="field-body">(string) (optional) Session name if specified.</td>
</tr>
<tr class="field-even field"><th class="field-name">date:</th><td class="field-body">(datetime.datetime) Session start date and time.</td>
</tr>
<tr class="field-odd field"><th class="field-name">user:</th><td class="field-body">(string) Trace user name.</td>
</tr>
<tr class="field-even field"><th class="field-name">flags:</th><td class="field-body">(list of strings) Session flags.</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2">Raises OperationalError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body"><p class="first last">When server can’t perform requested operation.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.trace_resume">
<tt class="descname">trace_resume</tt><big>(</big><em>trace_id</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.trace_resume" title="Permalink to this definition">¶</a></dt>
<dd><p>Resume trace session.</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"><p class="first"><strong>trace_id</strong> (<em>integer</em>) – Trace session ID.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns string:</th><td class="field-body"><p class="first">Text with confirmation that session was resumed.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When trace session is not resumed.</li>
<li><strong>OperationalError</strong> – When server can’t perform requested operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.trace_start">
<tt class="descname">trace_start</tt><big>(</big><em>config</em>, <em>name=None</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.trace_start" title="Permalink to this definition">¶</a></dt>
<dd><p>Start new trace session. <strong>(ASYNC service)</strong></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 simple">
<li><strong>config</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – Trace session configuration.</li>
<li><strong>name</strong> (<a class="reference external" href="http://docs.python.org/library/string.html#string" title="(in Python v2.7)"><em>string</em></a>) – (optional) Trace session name.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Returns integer:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body"><p class="first">Trace session ID.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name" colspan="2">Raises DatabaseError:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body"><p class="first last">When session ID is not returned on start.</p>
</td>
</tr>
</tbody>
</table>
<p>Trace session output could be retrieved through <a class="reference internal" href="#fdb.services.Connection.readline" title="fdb.services.Connection.readline"><tt class="xref py py-meth docutils literal"><span class="pre">readline()</span></tt></a>,
<a class="reference internal" href="#fdb.services.Connection.readlines" title="fdb.services.Connection.readlines"><tt class="xref py py-meth docutils literal"><span class="pre">readlines()</span></tt></a>, iteration over <cite>Connection</cite> or ignored via call to
<a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Until session output is not fully fetched from service (or ignored
via <a class="reference internal" href="#fdb.services.Connection.wait" title="fdb.services.Connection.wait"><tt class="xref py py-meth docutils literal"><span class="pre">wait()</span></tt></a>), any attempt to start another asynchronous service
including call to any <cite>trace_</cite> method will fail with exception.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.trace_stop">
<tt class="descname">trace_stop</tt><big>(</big><em>trace_id</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.trace_stop" title="Permalink to this definition">¶</a></dt>
<dd><p>Stop trace session.</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"><p class="first"><strong>trace_id</strong> (<em>integer</em>) – Trace session ID.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns string:</th><td class="field-body"><p class="first">Text with confirmation that session was stopped.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When trace session is not stopped.</li>
<li><strong>OperationalError</strong> – When server can’t perform requested operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.trace_suspend">
<tt class="descname">trace_suspend</tt><big>(</big><em>trace_id</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.trace_suspend" title="Permalink to this definition">¶</a></dt>
<dd><p>Suspend trace session.</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"><p class="first"><strong>trace_id</strong> (<em>integer</em>) – Trace session ID.</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns string:</th><td class="field-body"><p class="first">Text with confirmation that session was paused.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><ul class="first last simple">
<li><strong>DatabaseError</strong> – When trace session is not paused.</li>
<li><strong>OperationalError</strong> – When server can’t perform requested operation.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.user_exists">
<tt class="descname">user_exists</tt><big>(</big><em>user</em><big>)</big><a class="headerlink" href="#fdb.services.Connection.user_exists" title="Permalink to this definition">¶</a></dt>
<dd><p>Check for user’s existence.</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"><strong>user</strong> (string or <a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a>) – User name or Instance of <a class="reference internal" href="#fdb.services.User" title="fdb.services.User"><tt class="xref py py-class docutils literal"><span class="pre">User</span></tt></a> with <strong>at least</strong> its
<a class="reference internal" href="#fdb.services.User.name" title="fdb.services.User.name"><tt class="xref py py-attr docutils literal"><span class="pre">name</span></tt></a> attribute specified as non-empty value.</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Returns boolean:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body"><cite>True</cite> when the specified user exists.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="fdb.services.Connection.wait">
<tt class="descname">wait</tt><big>(</big><big>)</big><a class="headerlink" href="#fdb.services.Connection.wait" title="Permalink to this definition">¶</a></dt>
<dd><p>Wait until running service completes.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.services.Connection.QUERY_TYPE_PLAIN_INTEGER">
<tt class="descname">QUERY_TYPE_PLAIN_INTEGER</tt><em class="property"> = 1</em><a class="headerlink" href="#fdb.services.Connection.QUERY_TYPE_PLAIN_INTEGER" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="fdb.services.Connection.QUERY_TYPE_PLAIN_STRING">
<tt class="descname">QUERY_TYPE_PLAIN_STRING</tt><em class="property"> = 2</em><a class="headerlink" href="#fdb.services.Connection.QUERY_TYPE_PLAIN_STRING" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="fdb.services.Connection.QUERY_TYPE_RAW">
<tt class="descname">QUERY_TYPE_RAW</tt><em class="property"> = 3</em><a class="headerlink" href="#fdb.services.Connection.QUERY_TYPE_RAW" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="attribute">
<dt id="fdb.services.Connection.closed">
<tt class="descname">closed</tt><a class="headerlink" href="#fdb.services.Connection.closed" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) <cite>True</cite> if connection is closed.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.services.Connection.fetching">
<tt class="descname">fetching</tt><a class="headerlink" href="#fdb.services.Connection.fetching" title="Permalink to this definition">¶</a></dt>
<dd><p>(Read Only) <cite>True</cite> if connection is fetching result.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="user">
<h3>User<a class="headerlink" href="#user" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="fdb.services.User">
<em class="property">class </em><tt class="descclassname">fdb.services.</tt><tt class="descname">User</tt><big>(</big><em>name=None</em><big>)</big><a class="headerlink" href="#fdb.services.User" title="Permalink to this definition">¶</a></dt>
<dd><dl class="attribute">
<dt id="fdb.services.User.first_name">
<tt class="descname">first_name</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.services.User.first_name" title="Permalink to this definition">¶</a></dt>
<dd><p>First name.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.services.User.group_id">
<tt class="descname">group_id</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.services.User.group_id" title="Permalink to this definition">¶</a></dt>
<dd><p>User group ID</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.services.User.last_name">
<tt class="descname">last_name</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.services.User.last_name" title="Permalink to this definition">¶</a></dt>
<dd><p>Last name</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.services.User.middle_name">
<tt class="descname">middle_name</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.services.User.middle_name" title="Permalink to this definition">¶</a></dt>
<dd><p>Middle name</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.services.User.name">
<tt class="descname">name</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.services.User.name" title="Permalink to this definition">¶</a></dt>
<dd><p>User <cite>login</cite> name (username).</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.services.User.password">
<tt class="descname">password</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.services.User.password" title="Permalink to this definition">¶</a></dt>
<dd><p>Password. Not returned by user output methods, but must be
specified to add a user.</p>
</dd></dl>
<dl class="attribute">
<dt id="fdb.services.User.user_id">
<tt class="descname">user_id</tt><em class="property"> = None</em><a class="headerlink" href="#fdb.services.User.user_id" title="Permalink to this definition">¶</a></dt>
<dd><p>User ID</p>
</dd></dl>
</dd></dl>
</div>
</div>
<div class="section" id="ctypes-interface-to-firebird-client-library">
<h2>ctypes interface to Firebird client library<a class="headerlink" href="#ctypes-interface-to-firebird-client-library" title="Permalink to this headline">¶</a></h2>
<p><a class="reference external" href="http://docs.python.org/whatsnew/2.5.html#module-ctypes" title="(in Python v2.7)"><em class="xref std std-ref">ctypes</em></a> interface to <cite>fbclient.so/dll</cite> is defined in submodule <a class="reference internal" href="#module-fdb.ibase" title="fdb.ibase: Python ctypes interface to Firebird client library"><tt class="xref py py-mod docutils literal"><span class="pre">fdb.ibase</span></tt></a>.</p>
<span class="target" id="module-fdb.ibase"></span></div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">FDB Reference</a><ul>
<li><a class="reference internal" href="#module-globals">Module globals</a></li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
<li><a class="reference internal" href="#functions">Functions</a></li>
<li><a class="reference internal" href="#connection">Connection</a></li>
<li><a class="reference internal" href="#cursor">Cursor</a></li>
<li><a class="reference internal" href="#transaction">Transaction</a></li>
<li><a class="reference internal" href="#preparedstatement">PreparedStatement</a></li>
<li><a class="reference internal" href="#connectiongroup">ConnectionGroup</a></li>
<li><a class="reference internal" href="#transactioncontext">TransactionContext</a></li>
<li><a class="reference internal" href="#eventconduit">EventConduit</a></li>
<li><a class="reference internal" href="#blobreader">BlobReader</a></li>
<li><a class="reference internal" href="#tpb">TPB</a><ul>
<li><a class="reference internal" href="#tablereservation">TableReservation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-fdb.fbcore">Internally used classes exposed to driver users</a><ul>
<li><a class="reference internal" href="#rowmapping">RowMapping</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-fdb.services">Services</a><ul>
<li><a class="reference internal" href="#id1">Module globals</a></li>
<li><a class="reference internal" href="#id2">Functions</a></li>
<li><a class="reference internal" href="#id3">Connection</a></li>
<li><a class="reference internal" href="#user">User</a></li>
</ul>
</li>
<li><a class="reference internal" href="#ctypes-interface-to-firebird-client-library">ctypes interface to Firebird client library</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="differences-from-kdb.html"
title="previous chapter">Differences from KInterbasDB</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="changelog.html"
title="next chapter">Changelog</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="changelog.html" title="Changelog"
>next</a> |</li>
<li class="right" >
<a href="differences-from-kdb.html" title="Differences from KInterbasDB"
>previous</a> |</li>
<li><a href="index.html">FDB 1.1 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2012, David Rushby, Pavel Cisar.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
