<!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>Compliance to Python Database API 2.0 — 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="Differences from KInterbasDB" href="differences-from-kdb.html" /> <link rel="prev" title="Usage Guide" href="usage-guide.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="differences-from-kdb.html" title="Differences from KInterbasDB" accesskey="N">next</a> |</li> <li class="right" > <a href="usage-guide.html" title="Usage Guide" 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="compliance-to-python-database-api-2-0"> <h1>Compliance to Python Database API 2.0<a class="headerlink" href="#compliance-to-python-database-api-2-0" title="Permalink to this headline">¶</a></h1> <p>Full text of Python Database API 2.0 (PEP 249) is available at <a class="reference external" href="http://www.python.org/dev/peps/pep-0249/">http://www.python.org/dev/peps/pep-0249/</a></p> <div class="section" id="unsupported-optional-features"> <h2>Unsupported Optional Features<a class="headerlink" href="#unsupported-optional-features" title="Permalink to this headline">¶</a></h2> <p><tt class="xref py py-meth docutils literal"><span class="pre">fdb.Cursor.nextset()</span></tt></p> <blockquote> <div>This method is not implemented because the database engine does not support opening multiple result sets simultaneously with a single cursor.</div></blockquote> </div> <div class="section" id="nominally-supported-optional-features"> <h2>Nominally Supported Optional Features<a class="headerlink" href="#nominally-supported-optional-features" title="Permalink to this headline">¶</a></h2> <p><a class="reference internal" href="reference.html#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">fdb.Cursor</span></tt></a></p> <blockquote> <div><p><a class="reference internal" href="reference.html#fdb.Cursor.arraysize" title="fdb.Cursor.arraysize"><tt class="xref py py-attr docutils literal"><span class="pre">arraysize</span></tt></a></p> <blockquote> <div>As required by the spec, the value of this attribute is observed with respect to the <cite>fetchmany</cite> 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.</div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Cursor.setinputsizes" title="fdb.Cursor.setinputsizes"><tt class="xref py py-meth docutils literal"><span class="pre">setinputsizes()</span></tt></a></p> <blockquote> <div>Although this method is present, it does nothing, as allowed by the spec.</div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Cursor.setoutputsize" title="fdb.Cursor.setoutputsize"><tt class="xref py py-meth docutils literal"><span class="pre">setoutputsize()</span></tt></a></p> <blockquote> <div>Although this method is present, it does nothing, as allowed by the spec.</div></blockquote> </div></blockquote> </div> <div class="section" id="extensions-and-caveats"> <h2>Extensions and Caveats<a class="headerlink" href="#extensions-and-caveats" title="Permalink to this headline">¶</a></h2> <p>FDB offers a large feature set beyond the minimal requirements of the Python DB API. This section attempts to document only those features that overlap with the DB API, or are too insignificant to warrant their own subsection elsewhere.</p> <p><a class="reference internal" href="reference.html#fdb.connect" title="fdb.connect"><tt class="xref py py-func docutils literal"><span class="pre">fdb.connect()</span></tt></a></p> <blockquote> <div><p>This function supports the following optional keyword arguments in addition to those required by the spec:</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">role:</th><td class="field-body">For connecting to a database with a specific SQL role.</td> </tr> </tbody> </table> <p><em>Example:</em></p> <div class="highlight-python"><div class="highlight"><pre><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.db'</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s">'limited_user'</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">role</span><span class="o">=</span><span class="s">'MORE_POWERFUL_ROLE'</span><span class="p">)</span> </pre></div> </div> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">charset:</th><td class="field-body">For explicitly specifying the character set of the connection. See Firebird Documentation for a list of available character sets, and <cite>Unicode Fields and FDB</cite> section for information on handling extended character sets with FDB.</td> </tr> </tbody> </table> <p><em>Example:</em></p> <div class="highlight-python"><div class="highlight"><pre><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.db'</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> <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">sql_dialect:</th><td class="field-body">The SQL dialect is feature for backward compatibility with Interbase® 5.5 or earlier. The default dialect is <cite>3</cite> (the most featureful dialect, default for Firebird). If you want to connect to <cite>legacy</cite> databases, you must explicitly set this argument’s value to <cite>1</cite>. Dialect <cite>2</cite> is a transitional dialect that is normally used only during ports from IB < 6 to IB >= 6 or Firebird. See Firebird documentation for more information about SQL Dialects.</td> </tr> </tbody> </table> <p><em>Example:</em></p> <div class="highlight-python"><div class="highlight"><pre><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.db'</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">dialect</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> </pre></div> </div> </div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Connection" title="fdb.Connection"><tt class="xref py py-class docutils literal"><span class="pre">fdb.Connection</span></tt></a></p> <blockquote> <div><p><a class="reference internal" href="reference.html#fdb.Connection.charset" title="fdb.Connection.charset"><tt class="xref py py-attr docutils literal"><span class="pre">charset</span></tt></a></p> <blockquote> <div><em>(read-only)</em> The character set of the connection (set via the <cite>charset</cite> parameter of <a class="reference internal" href="reference.html#fdb.connect" title="fdb.connect"><tt class="xref py py-func docutils literal"><span class="pre">fdb.connect()</span></tt></a>). See Firebird Documentation for a list of available character sets, and <cite>Unicode Fields and FDB</cite> section for information on handling extended character sets with FDB.</div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Connection.sql_dialect" title="fdb.Connection.sql_dialect"><tt class="xref py py-attr docutils literal"><span class="pre">sql_dialect</span></tt></a></p> <blockquote> <div>This integer attribute indicates which SQL dialect the connection is using. You should not change a connection’s dialect; instead, discard the connection and establish a new one with the desired dialect. For more information, see the documentation of the <cite>sql_dialect</cite> argument of the <cite>connect</cite> function.</div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Connection.server_version" title="fdb.Connection.server_version"><tt class="xref py py-attr docutils literal"><span class="pre">server_version</span></tt></a></p> <blockquote> <div><em>(read-only)</em> The version string of the database server to which this connection is connected.</div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Connection.execute_immediate" title="fdb.Connection.execute_immediate"><tt class="xref py py-meth docutils literal"><span class="pre">execute_immediate()</span></tt></a></p> <blockquote> <div><p>Executes a statement without caching its prepared form. The statement must <em>not</em> be of a type that returns a result set. 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 <cite>cursor</cite> method, then execute the statement using one of the cursor’s execute methods.</p> <p>Arguments:</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">sql:</th><td class="field-body">String containing the SQL statement to execute.</td> </tr> </tbody> </table> </div></blockquote> <p><tt class="xref py py-meth docutils literal"><span class="pre">commit(retaining=False)()</span></tt> <tt class="xref py py-meth docutils literal"><span class="pre">rollback(retaining=False,</span> <span class="pre">savepoint=None)()</span></tt></p> <blockquote> <div>The <cite>commit</cite> and <cite>rollback</cite> methods accept an optional boolean parameter <cite>retaining</cite> (default <cite>False</cite>) that indicates whether the transactional context of the transaction being resolved should be recycled. For details, see the Advanced Transaction Control: Retaining Operations section of this document. The <cite>rollback</cite> method accepts an optional string parameter <cite>savepoint</cite> that causes the transaction to roll back only as far as the designated savepoint, rather than rolling back entirely. For details, see the Advanced Transaction Control: Savepoints section of this document.</div></blockquote> </div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Cursor" title="fdb.Cursor"><tt class="xref py py-class docutils literal"><span class="pre">fdb.Cursor</span></tt></a></p> <blockquote> <div><p><a class="reference internal" href="reference.html#fdb.Cursor.description" title="fdb.Cursor.description"><tt class="xref py py-attr docutils literal"><span class="pre">description</span></tt></a></p> <blockquote> <div><p>FDB makes absolutely no guarantees about <cite>description</cite> except those required by the Python Database API Specification 2.0 (that is, <cite>description</cite> is either <cite>None</cite> or a sequence of 7-element sequences). Therefore, client programmers should <em>not</em> rely on <cite>description</cite> being an instance of a particular class or type. FDB provides several named positional constants to be used as indices into a given element of <cite>description</cite> . The contents of all <cite>description</cite> elements are defined by the DB API spec; these constants are provided merely for convenience.</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">DESCRIPTION_NAME</span> <span class="n">DESCRIPTION_TYPE_CODE</span> <span class="n">DESCRIPTION_DISPLAY_SIZE</span> <span class="n">DESCRIPTION_INTERNAL_SIZE</span> <span class="n">DESCRIPTION_PRECISION</span> <span class="n">DESCRIPTION_SCALE</span> <span class="n">DESCRIPTION_NULL_OK</span> </pre></div> </div> <p>Here is an example of accessing the <em>name</em> of the first field in the <cite>description</cite> of cursor <cite>cur</cite>:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">nameOfFirstField</span> <span class="o">=</span> <span class="n">cur</span><span class="o">.</span><span class="n">description</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="n">fdb</span><span class="o">.</span><span class="n">DESCRIPTION_NAME</span><span class="p">]</span> </pre></div> </div> <p>For more information, see the documentation of Cursor.description in the <a class="reference external" href="Python-DB-API-2.0.html">DB API Specification</a>.</p> </div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Cursor.rowcount" title="fdb.Cursor.rowcount"><tt class="xref py py-attr docutils literal"><span class="pre">rowcount</span></tt></a></p> <blockquote> <div>Although FDB’s <cite>Cursor`s implement this attribute, 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</cite>, <cite>UPDATE</cite>, <cite>DELETE</cite>, and <cite>SELECT</cite> statements. When stored procedures become involved, row count figures are usually not available to the client. Determining rowcount for <cite>SELECT</cite> 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. As required by the Python DB API Spec, the rowcount attribute “is -1 in case no executeXX() has been performed on the cursor or the rowcount of the last operation is not determinable by the interface”.</div></blockquote> <p><a class="reference internal" href="reference.html#fdb.Cursor.fetchone" title="fdb.Cursor.fetchone"><tt class="xref py py-meth docutils literal"><span class="pre">fetchone()</span></tt></a></p> <p><a class="reference internal" href="reference.html#fdb.Cursor.fetchmany" title="fdb.Cursor.fetchmany"><tt class="xref py py-meth docutils literal"><span class="pre">fetchmany()</span></tt></a></p> <p><a class="reference internal" href="reference.html#fdb.Cursor.fetchall" title="fdb.Cursor.fetchall"><tt class="xref py py-meth docutils literal"><span class="pre">fetchall()</span></tt></a></p> <blockquote> <div>FDB makes absolutely no guarantees about the return value of the <cite>fetchone</cite> / <cite>fetchmany</cite> / <cite>fetchall</cite> methods except that it is a sequence indexed by field position. FDB makes absolutely no guarantees about the return value of the <cite>fetchonemap</cite> / <cite>fetchmanymap</cite> / <cite>fetchallmap</cite> methods (documented below) except that it is a mapping of field name to field value. Therefore, client programmers should <em>not</em> rely on the return value being an instance of a particular class or type.</div></blockquote> </div></blockquote> </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="#">Compliance to Python Database API 2.0</a><ul> <li><a class="reference internal" href="#unsupported-optional-features">Unsupported Optional Features</a></li> <li><a class="reference internal" href="#nominally-supported-optional-features">Nominally Supported Optional Features</a></li> <li><a class="reference internal" href="#extensions-and-caveats">Extensions and Caveats</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="usage-guide.html" title="previous chapter">Usage Guide</a></p> <h4>Next topic</h4> <p class="topless"><a href="differences-from-kdb.html" title="next chapter">Differences from KInterbasDB</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="differences-from-kdb.html" title="Differences from KInterbasDB" >next</a> |</li> <li class="right" > <a href="usage-guide.html" title="Usage Guide" >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>