Release v1.8

- Fix for PYFB-71 - New service support for backup and restore from/to local byte stream - New attribute fdb.schema.TableColumn.id (RDB$FIELD_ID) - New method fdb.BlobReader.get_info()
FirebirdSQL · Sep 20, 2017 · a92cd81 · a92cd81
1 parent e4d2c28
commit a92cd81
Show file tree

Hide file tree

Showing 23 changed files with 693 additions and 153 deletions.
diff --git a/docs/_sources/changelog.txt b/docs/_sources/changelog.txt
@@ -2,6 +2,7 @@
 Changelog
 #########
 
+* `Version 1.8`_ (20.9.2017)
 * `Version 1.7`_ (15.2.2017)
 * `Version 1.6.1`_ (30.11.2016)
 * `Version 1.6`_ (30.3.2016)
@@ -33,6 +34,14 @@ Changelog
 * `Version 0.7.1`_ (31.1.2012)
 * `Version 0.7`_ (21.12.2011)
 
+Version 1.8
+===========
+
+- In relation to (PYFB-71_) a better memory exhaustion safeguard was implemented for materialized blobs. See :ref:`Working with BLOBs <working_with_blobs>` for details.
+- Added service support for backup and restore from/to local byte stream. See :meth:`~fdb.services.Connection.local_backup()` and :meth:`~fdb.services.Connection.local_restore()` for details.
+- Added attribute :attr:`fdb.schema.TableColumn.id` (RDB$FIELD_ID)
+- Added method :meth:`fdb.BlobReader.get_info()`.
+
 Version 1.7
 ===========
 
@@ -436,6 +445,7 @@ What’s missing
 .. _PYFB-24: http://tracker.firebirdsql.org/browse/PYFB-24
 .. _PYFB-25: http://tracker.firebirdsql.org/browse/PYFB-25
 .. _PYFB-30: http://tracker.firebirdsql.org/browse/PYFB-30
+.. _PYFB-34: http://tracker.firebirdsql.org/browse/PYFB-34
 .. _PYFB-35: http://tracker.firebirdsql.org/browse/PYFB-35
 .. _PYFB-37: http://tracker.firebirdsql.org/browse/PYFB-37
 .. _PYFB-39: http://tracker.firebirdsql.org/browse/PYFB-39
@@ -460,3 +470,4 @@ What’s missing
 .. _PYFB-68: http://tracker.firebirdsql.org/browse/PYFB-68
 .. _PYFB-69: http://tracker.firebirdsql.org/browse/PYFB-69
 .. _PYFB-70: http://tracker.firebirdsql.org/browse/PYFB-70
+.. _PYFB-71: http://tracker.firebirdsql.org/browse/PYFB-71
diff --git a/docs/_sources/usage-guide.txt b/docs/_sources/usage-guide.txt
@@ -832,6 +832,25 @@ These drawbacks are addressed by `stream` BLOBs. Using BLOBs in `stream` mode is
 * For **input** values, simply use :ref:`parametrized statement <parametrized-statements>` and pass any `file-like` object in place of BLOB parameter. The `file-like` object must implement only the :meth:`~file.read` method, as no other metod is used.
 * For **output** values, you have to call :meth:`Cursor.set_stream_blob` (or :meth:`PreparedStatement.set_stream_blob`) method with specification of column name(s) that should be returned as `file-like` objects. FDB then returns :class:`BlobReader` instance instead string in place of returned BLOB value for these column(s).
 
+.. important::
+
+   **Before FDB version 1.8** load of materialized blob with multiple segments (i.e. larger than 64K) failed with error (SQLCODE: 101 - segment buffer length shorter than expected). This was an artefact of backward
+   compatibility with KInterbasDB that prevented them to exhaust your memory
+   with very large materialized blobs.
+
+   **Since FDB version 1.8** this memory exhaustion safeguard was enhanced in
+   more convenient (but backward incompatible) way. New methods
+   :meth:`PreparedStatement.set_stream_blob_treshold()` and :meth:`Cursor.set_stream_blob_treshold()` were introduced to
+   control the maximum size of materialized blobs. When particular blob value exceeds this threshold, an instance of :class:`BlobReader` is
+   returned instead string value, so your application has to be prepared to handle BLOBs in both incarnations. 
+
+   Zero value effectively forces all blobs to be returned as stream blobs.
+   Negative value means no size limit for materialized blobs (use at your
+   own risk). **The default treshold value is 64K.**
+
+   Blob size treshold has effect only on materialized blob columns, i.e. columns not explicitly requested to be returned as streamed ones using :meth:`PreparedStatement.set_stream_blob` that are always returned as stream blobs.
+
+
 The :class:`BlobReader` instance is bound to particular BLOB value returned by server, so its life time is limited. The actual BLOB value is not opened initially, so no additonal API calls to server are made if you'll decide to ignore the value completely. You also don't need to open the BLOB value explicitly, as BLOB is opened automatically on first call to :meth:`~BlobReader.next`, :meth:`~BlobReader.read`, :meth:`~BlobReader.readline`, :meth:`~BlobReader.readlines` or :meth:`~BlobReader.seek`. However, it's good practice to :meth:`~BlobReader.close` the reader once you're finished reading, as it's likely that Python's garbage collector would call the `__del__` method too late, when fetch context is already gone, and closing the reader would cause an error.
 
 .. warning::

diff --git a/docs/changelog.html b/docs/changelog.html
@@ -6,15 +6,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Changelog &mdash; FDB 1.7 documentation</title>
+    <title>Changelog &mdash; FDB 1.8 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.7',
+        VERSION:     '1.8',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -23,7 +23,7 @@
     <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.7 documentation" href="index.html" />
+    <link rel="top" title="FDB 1.8 documentation" href="index.html" />
     <link rel="next" title="LICENSE" href="license.html" />
     <link rel="prev" title="FDB Reference" href="reference.html" />
 <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
@@ -50,7 +50,7 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="reference.html" title="FDB Reference"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.7 documentation</a> &raquo;</li> 
+        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.8 documentation</a> &raquo;</li> 
       </ul>
     </div>  
 
@@ -62,6 +62,7 @@ <h3>Navigation</h3>
   <div class="section" id="changelog">
 <h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this headline">¶</a></h1>
 <ul class="simple">
+<li><a class="reference internal" href="#version-1-8">Version 1.8</a> (20.9.2017)</li>
 <li><a class="reference internal" href="#version-1-7">Version 1.7</a> (15.2.2017)</li>
 <li><a class="reference internal" href="#version-1-6-1">Version 1.6.1</a> (30.11.2016)</li>
 <li><a class="reference internal" href="#version-1-6">Version 1.6</a> (30.3.2016)</li>
@@ -93,6 +94,15 @@ <h1>Changelog<a class="headerlink" href="#changelog" title="Permalink to this he
 <li><a class="reference internal" href="#version-0-7-1">Version 0.7.1</a> (31.1.2012)</li>
 <li><a class="reference internal" href="#version-0-7">Version 0.7</a> (21.12.2011)</li>
 </ul>
+<div class="section" id="version-1-8">
+<h2>Version 1.8<a class="headerlink" href="#version-1-8" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>In relation to (<a class="reference external" href="http://tracker.firebirdsql.org/browse/PYFB-71">PYFB-71</a>) a better memory exhaustion safeguard was implemented for materialized blobs. See <a class="reference internal" href="usage-guide.html#working-with-blobs"><span>Working with BLOBs</span></a> for details.</li>
+<li>Added service support for backup and restore from/to local byte stream. See <a class="reference internal" href="reference.html#fdb.services.Connection.local_backup" title="fdb.services.Connection.local_backup"><code class="xref py py-meth docutils literal"><span class="pre">local_backup()</span></code></a> and <a class="reference internal" href="reference.html#fdb.services.Connection.local_restore" title="fdb.services.Connection.local_restore"><code class="xref py py-meth docutils literal"><span class="pre">local_restore()</span></code></a> for details.</li>
+<li>Added attribute <a class="reference internal" href="reference.html#fdb.schema.TableColumn.id" title="fdb.schema.TableColumn.id"><code class="xref py py-attr docutils literal"><span class="pre">fdb.schema.TableColumn.id</span></code></a> (RDB$FIELD_ID)</li>
+<li>Added method <a class="reference internal" href="reference.html#fdb.BlobReader.get_info" title="fdb.BlobReader.get_info"><code class="xref py py-meth docutils literal"><span class="pre">fdb.BlobReader.get_info()</span></code></a>.</li>
+</ul>
+</div>
 <div class="section" id="version-1-7">
 <h2>Version 1.7<a class="headerlink" href="#version-1-7" title="Permalink to this headline">¶</a></h2>
 <ul class="simple">
@@ -382,7 +392,7 @@ <h2>Version 1.1.1<a class="headerlink" href="#version-1-1-1" title="Permalink to
 <h3>Bugs Fixed<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h3>
 <ul class="simple">
 <li><a class="reference external" href="http://tracker.firebirdsql.org/browse/PYFB-35">PYFB-35</a> - Call to fetch after a sql statement without a result should raise exception</li>
-<li><a href="#id29"><span class="problematic" id="id30">PYFB-34_</span></a> - Server resources not released on PreparedStatement destruction</li>
+<li><a class="reference external" href="http://tracker.firebirdsql.org/browse/PYFB-34">PYFB-34</a> - Server resources not released on PreparedStatement destruction</li>
 </ul>
 </div>
 </div>
@@ -540,6 +550,7 @@ <h3>What’s missing<a class="headerlink" href="#whats-missing" title="Permalink
   <h3><a href="index.html">Table Of Contents</a></h3>
   <ul>
 <li><a class="reference internal" href="#">Changelog</a><ul>
+<li><a class="reference internal" href="#version-1-8">Version 1.8</a></li>
 <li><a class="reference internal" href="#version-1-7">Version 1.7</a></li>
 <li><a class="reference internal" href="#version-1-6-1">Version 1.6.1</a></li>
 <li><a class="reference internal" href="#version-1-6">Version 1.6</a></li>
@@ -682,7 +693,7 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="reference.html" title="FDB Reference"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.7 documentation</a> &raquo;</li> 
+        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.8 documentation</a> &raquo;</li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">

diff --git a/docs/differences-from-kdb.html b/docs/differences-from-kdb.html
@@ -6,15 +6,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Differences from KInterbasDB &mdash; FDB 1.7 documentation</title>
+    <title>Differences from KInterbasDB &mdash; FDB 1.8 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.7',
+        VERSION:     '1.8',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -23,7 +23,7 @@
     <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.7 documentation" href="index.html" />
+    <link rel="top" title="FDB 1.8 documentation" href="index.html" />
     <link rel="next" title="FDB Reference" href="reference.html" />
     <link rel="prev" title="Compliance to Python Database API 2.0" href="python-db-api-compliance.html" />
 <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
@@ -50,7 +50,7 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="python-db-api-compliance.html" title="Compliance to Python Database API 2.0"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.7 documentation</a> &raquo;</li> 
+        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.8 documentation</a> &raquo;</li> 
       </ul>
     </div>  
 
@@ -198,7 +198,7 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="python-db-api-compliance.html" title="Compliance to Python Database API 2.0"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.7 documentation</a> &raquo;</li> 
+        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.8 documentation</a> &raquo;</li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">

diff --git a/docs/genindex.html b/docs/genindex.html
@@ -7,15 +7,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Index &mdash; FDB 1.7 documentation</title>
+    <title>Index &mdash; FDB 1.8 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.7',
+        VERSION:     '1.8',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -24,7 +24,7 @@
     <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.7 documentation" href="index.html" />
+    <link rel="top" title="FDB 1.8 documentation" href="index.html" />
 <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&amp;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&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
 <!--[if lte IE 6]>
@@ -43,7 +43,7 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.7 documentation</a> &raquo;</li> 
+        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.8 documentation</a> &raquo;</li> 
       </ul>
     </div>  
 
@@ -2569,6 +2569,10 @@ <h2 id="G">G</h2>
   </dt>
 
 
+  <dt><a href="reference.html#fdb.BlobReader.get_info">get_info() (fdb.BlobReader method)</a>
+  </dt>
+
+
   <dt><a href="reference.html#fdb.services.Connection.get_limbo_transaction_ids">get_limbo_transaction_ids() (fdb.services.Connection method)</a>
   </dt>
 
@@ -2580,12 +2584,12 @@ <h2 id="G">G</h2>
   <dt><a href="reference.html#fdb.services.Connection.get_log">get_log() (fdb.services.Connection method)</a>
   </dt>
 
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
 
   <dt><a href="reference.html#fdb.services.Connection.get_message_file_directory">get_message_file_directory() (fdb.services.Connection method)</a>
   </dt>
 
-  </dl></td>
-  <td style="width: 33%" valign="top"><dl>
 
   <dt><a href="reference.html#fdb.schema.Schema.get_metadata_ddl">get_metadata_ddl() (fdb.schema.Schema method)</a>
   </dt>
@@ -3046,6 +3050,10 @@ <h2 id="I">I</h2>
   </dt>
 
 
+  <dt><a href="reference.html#fdb.schema.TableColumn.id">(fdb.schema.TableColumn attribute)</a>
+  </dt>
+
+
   <dt><a href="reference.html#fdb.schema.View.id">(fdb.schema.View attribute)</a>
   </dt>
 
@@ -3813,8 +3821,6 @@ <h2 id="L">L</h2>
   <dt><a href="reference.html#fdb.monitor.CallStackInfo.line">line (fdb.monitor.CallStackInfo attribute)</a>
   </dt>
 
-  </dl></td>
-  <td style="width: 33%" valign="top"><dl>
 
   <dt><a href="reference.html#fdb.ConnectionWithSchema.linger">linger (fdb.ConnectionWithSchema attribute)</a>
   </dt>
@@ -3825,6 +3831,8 @@ <h2 id="L">L</h2>
   </dt>
 
       </dl></dd>
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
 
   <dt><a href="reference.html#fdb.load_api">load_api() (in module fdb)</a>
   </dt>
@@ -3834,6 +3842,14 @@ <h2 id="L">L</h2>
   </dt>
 
 
+  <dt><a href="reference.html#fdb.services.Connection.local_backup">local_backup() (fdb.services.Connection method)</a>
+  </dt>
+
+
+  <dt><a href="reference.html#fdb.services.Connection.local_restore">local_restore() (fdb.services.Connection method)</a>
+  </dt>
+
+
   <dt><a href="reference.html#fdb.TPB.lock_resolution">lock_resolution (fdb.TPB attribute)</a>
   </dt>
 
@@ -5336,6 +5352,16 @@ <h2 id="S">S</h2>
 
       </dl></dd>
 
+  <dt><a href="reference.html#fdb.Cursor.set_stream_blob_treshold">set_stream_blob_treshold() (fdb.Cursor method)</a>
+  </dt>
+
+      <dd><dl>
+
+  <dt><a href="reference.html#fdb.PreparedStatement.set_stream_blob_treshold">(fdb.PreparedStatement method)</a>
+  </dt>
+
+      </dl></dd>
+
   <dt><a href="reference.html#fdb.services.Connection.set_sweep_interval">set_sweep_interval() (fdb.services.Connection method)</a>
   </dt>
 
@@ -6419,7 +6445,7 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.7 documentation</a> &raquo;</li> 
+        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.8 documentation</a> &raquo;</li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">

diff --git a/docs/getting-started.html b/docs/getting-started.html
@@ -6,15 +6,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Getting Started with FDB &mdash; FDB 1.7 documentation</title>
+    <title>Getting Started with FDB &mdash; FDB 1.8 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.7',
+        VERSION:     '1.8',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -23,7 +23,7 @@
     <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.7 documentation" href="index.html" />
+    <link rel="top" title="FDB 1.8 documentation" href="index.html" />
     <link rel="next" title="Usage Guide" href="usage-guide.html" />
     <link rel="prev" title="Welcome to FDB’s documentation!" href="index.html" />
 <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
@@ -50,7 +50,7 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="index.html" title="Welcome to FDB’s documentation!"
              accesskey="P">previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.7 documentation</a> &raquo;</li> 
+        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.8 documentation</a> &raquo;</li> 
       </ul>
     </div>  
 
@@ -355,7 +355,7 @@ <h3>Navigation</h3>
         <li class="right" >
           <a href="index.html" title="Welcome to FDB’s documentation!"
              >previous</a> |</li>
-        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.7 documentation</a> &raquo;</li> 
+        <li class="nav-item nav-item-0"><a href="index.html">FDB 1.8 documentation</a> &raquo;</li> 
       </ul>
     </div>
     <div class="footer" role="contentinfo">