PageRenderTime 76ms CodeModel.GetById 37ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/html/cursor.html

https://github.com/hhru/lucid-python-psycopg2
HTML | 637 lines | 600 code | 37 blank | 0 comment | 0 complexity | 2a937c81f5b34b3527a2bf9077f37e4a MD5 | raw file
    

  1. 

  2. 

  3. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    4. 

  4.   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    5. 

  5. 

  6. <html xmlns="http://www.w3.org/1999/xhtml">
    7. 

  7.   <head>
    8. 

  8.     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    9. 

  9.     
    10. 

  10.     <title>The cursor class &mdash; Psycopg v2.4.2 documentation</title>
    11. 

  11.     <link rel="stylesheet" href="_static/psycopg.css" type="text/css" />
    12. 

  12.     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    13. 

  13.     <script type="text/javascript">
    14. 

  14.       var DOCUMENTATION_OPTIONS = {
    15. 

  15.         URL_ROOT:    '',
    16. 

  16.         VERSION:     '2.4.2',
    17. 

  17.         COLLAPSE_INDEX: false,
    18. 

  18.         FILE_SUFFIX: '.html',
    19. 

  19.         HAS_SOURCE:  true
    20. 

  20.       };
    21. 

  21.     </script>
    22. 

  22.     <script type="text/javascript" src="_static/jquery.js"></script>
    23. 

  23.     <script type="text/javascript" src="_static/underscore.js"></script>
    24. 

  24.     <script type="text/javascript" src="_static/doctools.js"></script>
    25. 

  25.     <link rel="top" title="Psycopg v2.4.2 documentation" href="index.html" />
    26. 

  26.     <link rel="next" title="More advanced topics" href="advanced.html" />
    27. 

  27.     <link rel="prev" title="The connection class" href="connection.html" /> 
    28. 

  28.   </head>
    29. 

  29.   <body>
    30. 

  30.     <div class="related">
    31. 

  31.       <h3>Navigation</h3>
    32. 

  32.       <ul>
    33. 

  33.         <li class="right" style="margin-right: 10px">
    34. 

  34.           <a href="genindex.html" title="General Index"
    35. 

  35.              accesskey="I">index</a></li>
    36. 

  36.         <li class="right" >
    37. 

  37.           <a href="py-modindex.html" title="Python Module Index"
    38. 

  38.              >modules</a> |</li>
    39. 

  39.         <li class="right" >
    40. 

  40.           <a href="advanced.html" title="More advanced topics"
    41. 

  41.              accesskey="N">next</a> |</li>
    42. 

  42.         <li class="right" >
    43. 

  43.           <a href="connection.html" title="The connection class"
    44. 

  44.              accesskey="P">previous</a> |</li>
    45. 

  45.         <li><a href="index.html">Psycopg v2.4.2 documentation</a> &raquo;</li> 
    46. 

  46.       </ul>
    47. 

  47.     </div>  
    48. 

  48. 

  49.     <div class="document">
    50. 

  50.       <div class="documentwrapper">
    51. 

  51.         <div class="bodywrapper">
    52. 

  52.           <div class="body">
    53. 

  53.             
    54. 

  54.   <div class="section" id="the-cursor-class">
    55. 

  55. <h1>The <tt class="docutils literal"><span class="pre">cursor</span></tt> class<a class="headerlink" href="#the-cursor-class" title="Permalink to this headline"></a></h1>
    56. 

  56. <dl class="class">
    57. 

  57. <dt id="cursor">
    58. 

  58. <em class="property">class </em><tt class="descname">cursor</tt><a class="headerlink" href="#cursor" title="Permalink to this definition"></a></dt>
    59. 

  59. <dd><p>Allows Python code to execute PostgreSQL command in a database session.
    60. 

  60. Cursors are created by the <a class="reference internal" href="connection.html#connection.cursor" title="connection.cursor"><tt class="xref py py-obj docutils literal"><span class="pre">connection.cursor()</span></tt></a> method: they are
    61. 

  61. bound to the connection for the entire lifetime and all the commands are
    62. 

  62. executed in the context of the database session wrapped by the connection.</p>
    63. 

  63. <p>Cursors created from the same connection are not isolated, i.e., any
    64. 

  64. changes done to the database by a cursor are immediately visible by the
    65. 

  65. other cursors. Cursors created from different connections can or can not
    66. 

  66. be isolated, depending on the connections&#8217; <a class="reference internal" href="usage.html#transactions-control"><em>isolation level</em></a>. See also <a class="reference internal" href="connection.html#connection.rollback" title="connection.rollback"><tt class="xref py py-obj docutils literal"><span class="pre">rollback()</span></tt></a> and
    67. 

  67. <a class="reference internal" href="connection.html#connection.commit" title="connection.commit"><tt class="xref py py-obj docutils literal"><span class="pre">commit()</span></tt></a> methods.</p>
    68. 

  68. <p>Cursors are <em>not</em> thread safe: a multithread application can create
    69. 

  69. many cursors from the same connection and should use each cursor from
    70. 

  70. a single thread. See <a class="reference internal" href="usage.html#thread-safety"><em>Thread and process safety</em></a> for details.</p>
    71. 

  71. <dl class="attribute">
    72. 

  72. <dt id="cursor.description">
    73. 

  73. <tt class="descname">description</tt><a class="headerlink" href="#cursor.description" title="Permalink to this definition"></a></dt>
    74. 

  74. <dd><p>This read-only attribute is a sequence of 7-item sequences.</p>
    75. 

  75. <p>Each of these sequences is a named tuple (a regular tuple if
    76. 

  76. <a class="reference external" href="http://docs.python.org/3.2/library/collections.html#collections.namedtuple" title="(in Python v3.2)"><tt class="xref py py-func docutils literal"><span class="pre">collections.namedtuple()</span></tt></a> is not available) containing information
    77. 

  77. describing one result column:</p>
    78. 

  78. <ol class="arabic simple" start="0">
    79. 

  79. <li><tt class="xref py py-obj docutils literal"><span class="pre">name</span></tt>: the name of the column returned.</li>
    80. 

  80. <li><tt class="xref py py-obj docutils literal"><span class="pre">type_code</span></tt>: the PostgreSQL OID of the column. You can use the
    81. 

  81. <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/catalog-pg-type.html"><tt class="sql docutils literal"><span class="pre">pg_type</span></tt></a> system table to get more informations about the type.
    82. 

  82. This is the value used by Psycopg to decide what Python type use
    83. 

  83. to represent the value.  See also
    84. 

  84. <a class="reference internal" href="advanced.html#type-casting-from-sql-to-python"><em>Type casting of SQL types into Python objects</em></a>.</li>
    85. 

  85. <li><tt class="xref py py-obj docutils literal"><span class="pre">display_size</span></tt>: the actual length of the column in bytes.
    86. 

  86. Obtaining this value is computationally intensive, so it is
    87. 

  87. always <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> unless the <span class="target" id="index-0"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PSYCOPG_DISPLAY_SIZE</span></tt> parameter
    88. 

  88. is set at compile time. See also <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/libpq-exec.html#LIBPQ-PQGETLENGTH">PQgetlength</a>.</li>
    89. 

  89. <li><tt class="xref py py-obj docutils literal"><span class="pre">internal_size</span></tt>: the size in bytes of the column associated to
    90. 

  90. this column on the server. Set to a negative value for
    91. 

  91. variable-size types See also <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/libpq-exec.html#LIBPQ-PQFSIZE">PQfsize</a>.</li>
    92. 

  92. <li><tt class="xref py py-obj docutils literal"><span class="pre">precision</span></tt>: total number of significant digits in columns of
    93. 

  93. type <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/datatype-numeric.html#DATATYPE-NUMERIC-DECIMAL"><tt class="sql docutils literal"><span class="pre">NUMERIC</span></tt></a>. <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> for other types.</li>
    94. 

  94. <li><tt class="xref py py-obj docutils literal"><span class="pre">scale</span></tt>: count of decimal digits in the fractional part in
    95. 

  95. columns of type <tt class="sql docutils literal"><span class="pre">NUMERIC</span></tt>. <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> for other types.</li>
    96. 

  96. <li><tt class="xref py py-obj docutils literal"><span class="pre">null_ok</span></tt>: always <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> as not easy to retrieve from the libpq.</li>
    97. 

  97. </ol>
    98. 

  98. <p>This attribute will be <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> for operations that do not return rows
    99. 

  99. or if the cursor has not had an operation invoked via the
    100. 

  100. <a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> methods yet.</p>
    101. 

  101. <p class="versionchanged">
    102. 

  102. <span class="versionmodified">Changed in version 2.4: </span>if possible, columns descriptions are named tuple instead of
    103. 

  103. regular tuples.</p>
    104. 

  104. </dd></dl>
    105. 

  105. 

  106. <dl class="method">
    107. 

  107. <dt id="cursor.close">
    108. 

  108. <tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#cursor.close" title="Permalink to this definition"></a></dt>
    109. 

  109. <dd><p>Close the cursor now (rather than whenever <tt class="xref py py-obj docutils literal"><span class="pre">del</span></tt> is executed).
    110. 

  110. The cursor will be unusable from this point forward; an
    111. 

  111. <a class="reference internal" href="module.html#psycopg2.InterfaceError" title="psycopg2.InterfaceError"><tt class="xref py py-obj docutils literal"><span class="pre">InterfaceError</span></tt></a> will be raised if any operation is
    112. 

  112. attempted with the cursor.</p>
    113. 

  113. </dd></dl>
    114. 

  114. 

  115. <dl class="attribute">
    116. 

  116. <dt id="cursor.closed">
    117. 

  117. <tt class="descname">closed</tt><a class="headerlink" href="#cursor.closed" title="Permalink to this definition"></a></dt>
    118. 

  118. <dd><p>Read-only boolean attribute: specifies if the cursor is closed
    119. 

  119. (<tt class="xref py py-obj xref docutils literal"><span class="pre">True</span></tt>) or not (<tt class="xref py py-obj xref docutils literal"><span class="pre">False</span></tt>).</p>
    120. 

  120. <div class="admonition-db-api-extension dbapi-extension admonition ">
    121. 

  121. <p class="first admonition-title">DB API extension</p>
    122. 

  122. <p class="last">The <a class="reference internal" href="#cursor.closed" title="cursor.closed"><tt class="xref py py-obj docutils literal"><span class="pre">closed</span></tt></a> attribute is a Psycopg extension to the
    123. 

  123. DB API 2.0.</p>
    124. 

  124. </div>
    125. 

  125. <p class="versionadded">
    126. 

  126. <span class="versionmodified">New in version 2.0.7.</span></p>
    127. 

  127. </dd></dl>
    128. 

  128. 

  129. <dl class="attribute">
    130. 

  130. <dt id="cursor.connection">
    131. 

  131. <tt class="descname">connection</tt><a class="headerlink" href="#cursor.connection" title="Permalink to this definition"></a></dt>
    132. 

  132. <dd><p>Read-only attribute returning a reference to the <a class="reference internal" href="connection.html#connection" title="connection"><tt class="xref py py-obj docutils literal"><span class="pre">connection</span></tt></a>
    133. 

  133. object on which the cursor was created.</p>
    134. 

  134. </dd></dl>
    135. 

  135. 

  136. <dl class="attribute">
    137. 

  137. <dt id="cursor.name">
    138. 

  138. <tt class="descname">name</tt><a class="headerlink" href="#cursor.name" title="Permalink to this definition"></a></dt>
    139. 

  139. <dd><p>Read-only attribute containing the name of the cursor if it was
    140. 

  140. creates as named cursor by <a class="reference internal" href="connection.html#connection.cursor" title="connection.cursor"><tt class="xref py py-obj docutils literal"><span class="pre">connection.cursor()</span></tt></a>, or <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> if
    141. 

  141. it is a client side cursor.  See <a class="reference internal" href="usage.html#server-side-cursors"><em>Server side cursors</em></a>.</p>
    142. 

  142. <div class="admonition-db-api-extension dbapi-extension admonition ">
    143. 

  143. <p class="first admonition-title">DB API extension</p>
    144. 

  144. <p class="last">The <a class="reference internal" href="#cursor.name" title="cursor.name"><tt class="xref py py-obj docutils literal"><span class="pre">name</span></tt></a> attribute is a Psycopg extension to the DB API 2.0.</p>
    145. 

  145. </div>
    146. 

  146. </dd></dl>
    147. 

  147. 

  148. <p class="rubric" id="execute">Commands execution methods</p>
    149. 

  149. <dl class="method">
    150. 

  150. <dt id="cursor.execute">
    151. 

  151. <tt class="descname">execute</tt><big>(</big><em>operation</em><span class="optional">[</span>, <em>parameters</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.execute" title="Permalink to this definition"></a></dt>
    152. 

  152. <dd><p>Prepare and execute a database operation (query or command).</p>
    153. 

  153. <p>Parameters may be provided as sequence or mapping and will be bound to
    154. 

  154. variables in the operation.  Variables are specified either with
    155. 

  155. positional (<tt class="docutils literal"><span class="pre">%s</span></tt>) or named (<tt class="samp docutils literal"><span class="pre">%(</span><em><span class="pre">name</span></em><span class="pre">)s</span></tt>) placeholders. See
    156. 

  156. <a class="reference internal" href="usage.html#query-parameters"><em>Passing parameters to SQL queries</em></a>.</p>
    157. 

  157. <p>The method returns <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt>. If a query was executed, the returned
    158. 

  158. values can be retrieved using <a class="reference internal" href="#fetch"><tt class="xref py py-obj docutils literal"><span class="pre">fetch*()</span></tt></a> methods.</p>
    159. 

  159. </dd></dl>
    160. 

  160. 

  161. <dl class="method">
    162. 

  162. <dt id="cursor.executemany">
    163. 

  163. <tt class="descname">executemany</tt><big>(</big><em>operation</em>, <em>seq_of_parameters</em><big>)</big><a class="headerlink" href="#cursor.executemany" title="Permalink to this definition"></a></dt>
    164. 

  164. <dd><p>Prepare a database operation (query or command) and then execute it
    165. 

  165. against all parameter tuples or mappings found in the sequence
    166. 

  166. <tt class="xref py py-obj docutils literal"><span class="pre">seq_of_parameters</span></tt>.</p>
    167. 

  167. <p>The function is mostly useful for commands that update the database:
    168. 

  168. any result set returned by the query is discarded.</p>
    169. 

  169. <p>Parameters are bounded to the query using the same rules described in
    170. 

  170. the <a class="reference internal" href="#cursor.execute" title="cursor.execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute()</span></tt></a> method.</p>
    171. 

  171. </dd></dl>
    172. 

  172. 

  173. <dl class="method">
    174. 

  174. <dt id="cursor.callproc">
    175. 

  175. <tt class="descname">callproc</tt><big>(</big><em>procname</em><span class="optional">[</span>, <em>parameters</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.callproc" title="Permalink to this definition"></a></dt>
    176. 

  176. <dd><p>Call a stored database procedure with the given name. The sequence of
    177. 

  177. parameters must contain one entry for each argument that the procedure
    178. 

  178. expects. The result of the call is returned as modified copy of the
    179. 

  179. input sequence. Input parameters are left untouched, output and
    180. 

  180. input/output parameters replaced with possibly new values.</p>
    181. 

  181. <p>The procedure may also provide a result set as output. This must then
    182. 

  182. be made available through the standard <a class="reference internal" href="#fetch"><tt class="xref py py-obj docutils literal"><span class="pre">fetch*()</span></tt></a> methods.</p>
    183. 

  183. </dd></dl>
    184. 

  184. 

  185. <dl class="method">
    186. 

  186. <dt id="cursor.mogrify">
    187. 

  187. <tt class="descname">mogrify</tt><big>(</big><em>operation</em><span class="optional">[</span>, <em>parameters</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.mogrify" title="Permalink to this definition"></a></dt>
    188. 

  188. <dd><p>Return a query string after arguments binding. The string returned is
    189. 

  189. exactly the one that would be sent to the database running the
    190. 

  190. <a class="reference internal" href="#cursor.execute" title="cursor.execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute()</span></tt></a> method or similar.</p>
    191. 

  191. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">mogrify</span><span class="p">(</span><span class="s">&quot;INSERT INTO test (num, data) VALUES (</span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">)&quot;</span><span class="p">,</span> <span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="s">&#39;bar&#39;</span><span class="p">))</span>
    192. 

  192. <span class="go">&quot;INSERT INTO test (num, data) VALUES (42, E&#39;bar&#39;)&quot;</span>
    193. 

  193. </pre></div>
    194. 

  194. </div>
    195. 

  195. <div class="admonition-db-api-extension dbapi-extension admonition ">
    196. 

  196. <p class="first admonition-title">DB API extension</p>
    197. 

  197. <p class="last">The <a class="reference internal" href="#cursor.mogrify" title="cursor.mogrify"><tt class="xref py py-obj docutils literal"><span class="pre">mogrify()</span></tt></a> method is a Psycopg extension to the DB API 2.0.</p>
    198. 

  198. </div>
    199. 

  199. </dd></dl>
    200. 

  200. 

  201. <dl class="method">
    202. 

  202. <dt id="cursor.setinputsizes">
    203. 

  203. <tt class="descname">setinputsizes</tt><big>(</big><em>sizes</em><big>)</big><a class="headerlink" href="#cursor.setinputsizes" title="Permalink to this definition"></a></dt>
    204. 

  204. <dd><p>This method is exposed in compliance with the DB API 2.0. It currently
    205. 

  205. does nothing but it is safe to call it.</p>
    206. 

  206. </dd></dl>
    207. 

  207. 

  208. <p class="rubric" id="fetch">Results retrieval methods</p>
    209. 

  209. <p>The following methods are used to read data from the database after an
    210. 

  210. <a class="reference internal" href="#cursor.execute" title="cursor.execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute()</span></tt></a> call.</p>
    211. 

  211. <div class="admonition note" id="cursor-iterable">
    212. 

  212. <p class="first admonition-title">Note</p>
    213. 

  213. <p><a class="reference internal" href="#cursor" title="cursor"><tt class="xref py py-obj docutils literal"><span class="pre">cursor</span></tt></a> objects are iterable, so, instead of calling
    214. 

  214. explicitly <a class="reference internal" href="#cursor.fetchone" title="cursor.fetchone"><tt class="xref py py-obj docutils literal"><span class="pre">fetchone()</span></tt></a> in a loop, the object itself can
    215. 

  215. be used:</p>
    216. 

  216. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;SELECT * FROM test;&quot;</span><span class="p">)</span>
    217. 

  217. <span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">record</span> <span class="ow">in</span> <span class="n">cur</span><span class="p">:</span>
    218. 

  218. <span class="gp">... </span>    <span class="k">print</span> <span class="n">record</span>
    219. 

  219. <span class="gp">...</span>
    220. 

  220. <span class="go">(1, 100, &quot;abc&#39;def&quot;)</span>
    221. 

  221. <span class="go">(2, None, &#39;dada&#39;)</span>
    222. 

  222. <span class="go">(3, 42, &#39;bar&#39;)</span>
    223. 

  223. </pre></div>
    224. 

  224. </div>
    225. 

  225. <p class="last versionchanged">
    226. 

  226. <span class="versionmodified">Changed in version 2.4: </span>iterating over a <a class="reference internal" href="usage.html#server-side-cursors"><em>named cursor</em></a>
    227. 

  227. fetches <a class="reference internal" href="#cursor.itersize" title="cursor.itersize"><tt class="xref py py-obj docutils literal"><span class="pre">itersize</span></tt></a> records at time from the backend.
    228. 

  228. Previously only one record was fetched per roundtrip, resulting
    229. 

  229. in a large overhead.</p>
    230. 

  230. </div>
    231. 

  231. <dl class="method">
    232. 

  232. <dt id="cursor.fetchone">
    233. 

  233. <tt class="descname">fetchone</tt><big>(</big><big>)</big><a class="headerlink" href="#cursor.fetchone" title="Permalink to this definition"></a></dt>
    234. 

  234. <dd><p>Fetch the next row of a query result set, returning a single tuple,
    235. 

  235. or <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> when no more data is available:</p>
    236. 

  236. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;SELECT * FROM test WHERE id = </span><span class="si">%s</span><span class="s">&quot;</span><span class="p">,</span> <span class="p">(</span><span class="mi">3</span><span class="p">,))</span>
    237. 

  237. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">fetchone</span><span class="p">()</span>
    238. 

  238. <span class="go">(3, 42, &#39;bar&#39;)</span>
    239. 

  239. </pre></div>
    240. 

  240. </div>
    241. 

  241. <p>A <a class="reference internal" href="module.html#psycopg2.ProgrammingError" title="psycopg2.ProgrammingError"><tt class="xref py py-obj docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call
    242. 

  242. to <a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued
    243. 

  243. yet.</p>
    244. 

  244. </dd></dl>
    245. 

  245. 

  246. <dl class="method">
    247. 

  247. <dt id="cursor.fetchmany">
    248. 

  248. <tt class="descname">fetchmany</tt><big>(</big><span class="optional">[</span><em>size=cursor.arraysize</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.fetchmany" title="Permalink to this definition"></a></dt>
    249. 

  249. <dd><p>Fetch the next set of rows of a query result, returning a list of
    250. 

  250. tuples. An empty list is returned when no more rows are available.</p>
    251. 

  251. <p>The number of rows to fetch per call is specified by the parameter.
    252. 

  252. If it is not given, the cursor&#8217;s <a class="reference internal" href="#cursor.arraysize" title="cursor.arraysize"><tt class="xref py py-obj docutils literal"><span class="pre">arraysize</span></tt></a> determines
    253. 

  253. the number of rows to be fetched. The method should try to fetch as
    254. 

  254. many rows as indicated by the size parameter. If this is not possible
    255. 

  255. due to the specified number of rows not being available, fewer rows
    256. 

  256. may be returned:</p>
    257. 

  257. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;SELECT * FROM test;&quot;</span><span class="p">)</span>
    258. 

  258. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">fetchmany</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
    259. 

  259. <span class="go">[(1, 100, &quot;abc&#39;def&quot;), (2, None, &#39;dada&#39;)]</span>
    260. 

  260. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">fetchmany</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
    261. 

  261. <span class="go">[(3, 42, &#39;bar&#39;)]</span>
    262. 

  262. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">fetchmany</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
    263. 

  263. <span class="go">[]</span>
    264. 

  264. </pre></div>
    265. 

  265. </div>
    266. 

  266. <p>A <a class="reference internal" href="module.html#psycopg2.ProgrammingError" title="psycopg2.ProgrammingError"><tt class="xref py py-obj docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call to
    267. 

  267. <a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued yet.</p>
    268. 

  268. <p>Note there are performance considerations involved with the size
    269. 

  269. parameter.  For optimal performance, it is usually best to use the
    270. 

  270. <a class="reference internal" href="#cursor.arraysize" title="cursor.arraysize"><tt class="xref py py-obj docutils literal"><span class="pre">arraysize</span></tt></a> attribute.  If the size parameter is used,
    271. 

  271. then it is best for it to retain the same value from one
    272. 

  272. <a class="reference internal" href="#cursor.fetchmany" title="cursor.fetchmany"><tt class="xref py py-obj docutils literal"><span class="pre">fetchmany()</span></tt></a> call to the next.</p>
    273. 

  273. </dd></dl>
    274. 

  274. 

  275. <dl class="method">
    276. 

  276. <dt id="cursor.fetchall">
    277. 

  277. <tt class="descname">fetchall</tt><big>(</big><big>)</big><a class="headerlink" href="#cursor.fetchall" title="Permalink to this definition"></a></dt>
    278. 

  278. <dd><p>Fetch all (remaining) rows of a query result, returning them as a list
    279. 

  279. of tuples.  An empty list is returned if there is no more record to
    280. 

  280. fetch.</p>
    281. 

  281. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;SELECT * FROM test;&quot;</span><span class="p">)</span>
    282. 

  282. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span>
    283. 

  283. <span class="go">[(1, 100, &quot;abc&#39;def&quot;), (2, None, &#39;dada&#39;), (3, 42, &#39;bar&#39;)]</span>
    284. 

  284. </pre></div>
    285. 

  285. </div>
    286. 

  286. <p>A <a class="reference internal" href="module.html#psycopg2.ProgrammingError" title="psycopg2.ProgrammingError"><tt class="xref py py-obj docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised if the previous call to
    287. 

  287. <a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> did not produce any result set or no call was issued yet.</p>
    288. 

  288. </dd></dl>
    289. 

  289. 

  290. <dl class="method">
    291. 

  291. <dt id="cursor.scroll">
    292. 

  292. <tt class="descname">scroll</tt><big>(</big><em>value</em><span class="optional">[</span>, <em>mode='relative'</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.scroll" title="Permalink to this definition"></a></dt>
    293. 

  293. <dd><p>Scroll the cursor in the result set to a new position according
    294. 

  294. to mode.</p>
    295. 

  295. <p>If <tt class="xref py py-obj docutils literal"><span class="pre">mode</span></tt> is <tt class="docutils literal"><span class="pre">relative</span></tt> (default), value is taken as offset to
    296. 

  296. the current position in the result set, if set to <tt class="docutils literal"><span class="pre">absolute</span></tt>,
    297. 

  297. value states an absolute target position.</p>
    298. 

  298. <p>If the scroll operation would leave the result set, a
    299. 

  299. <a class="reference internal" href="module.html#psycopg2.ProgrammingError" title="psycopg2.ProgrammingError"><tt class="xref py py-obj docutils literal"><span class="pre">ProgrammingError</span></tt></a> is raised and the cursor position is
    300. 

  300. not changed.</p>
    301. 

  301. <p>The method can be used both for client-side cursors and
    302. 

  302. <a class="reference internal" href="usage.html#server-side-cursors"><em>server-side cursors</em></a>.</p>
    303. 

  303. <div class="admonition note">
    304. 

  304. <p class="first admonition-title">Note</p>
    305. 

  305. <p>According to the <a class="reference external" href="http://www.python.org/dev/peps/pep-0249/">DB API 2.0</a>, the exception raised for a cursor out
    306. 

  306. of bound should have been <tt class="xref py py-obj docutils literal"><span class="pre">IndexError</span></tt>.  The best option is
    307. 

  307. probably to catch both exceptions in your code:</p>
    308. 

  308. <div class="last highlight-python"><div class="highlight"><pre><span class="k">try</span><span class="p">:</span>
    309. 

  309.     <span class="n">cur</span><span class="o">.</span><span class="n">scroll</span><span class="p">(</span><span class="mi">1000</span> <span class="o">*</span> <span class="mi">1000</span><span class="p">)</span>
    310. 

  310. <span class="k">except</span> <span class="p">(</span><span class="n">ProgrammingError</span><span class="p">,</span> <span class="ne">IndexError</span><span class="p">),</span> <span class="n">exc</span><span class="p">:</span>
    311. 

  311.     <span class="n">deal_with_it</span><span class="p">(</span><span class="n">exc</span><span class="p">)</span>
    312. 

  312. </pre></div>
    313. 

  313. </div>
    314. 

  314. </div>
    315. 

  315. </dd></dl>
    316. 

  316. 

  317. <dl class="attribute">
    318. 

  318. <dt id="cursor.arraysize">
    319. 

  319. <tt class="descname">arraysize</tt><a class="headerlink" href="#cursor.arraysize" title="Permalink to this definition"></a></dt>
    320. 

  320. <dd><p>This read/write attribute specifies the number of rows to fetch at a
    321. 

  321. time with <a class="reference internal" href="#cursor.fetchmany" title="cursor.fetchmany"><tt class="xref py py-obj docutils literal"><span class="pre">fetchmany()</span></tt></a>. It defaults to 1 meaning to fetch
    322. 

  322. a single row at a time.</p>
    323. 

  323. </dd></dl>
    324. 

  324. 

  325. <dl class="attribute">
    326. 

  326. <dt id="cursor.itersize">
    327. 

  327. <tt class="descname">itersize</tt><a class="headerlink" href="#cursor.itersize" title="Permalink to this definition"></a></dt>
    328. 

  328. <dd><p>Read/write attribute specifying the number of rows to fetch from the
    329. 

  329. backend at each network roundtrip during <a class="reference internal" href="#cursor-iterable"><em>iteration</em></a> on a <a class="reference internal" href="usage.html#server-side-cursors"><em>named cursor</em></a>. The
    330. 

  330. default is 2000.</p>
    331. 

  331. <p class="versionadded">
    332. 

  332. <span class="versionmodified">New in version 2.4.</span></p>
    333. 

  333. <div class="admonition-db-api-extension dbapi-extension admonition ">
    334. 

  334. <p class="first admonition-title">DB API extension</p>
    335. 

  335. <p class="last">The <a class="reference internal" href="#cursor.itersize" title="cursor.itersize"><tt class="xref py py-obj docutils literal"><span class="pre">itersize</span></tt></a> attribute is a Psycopg extension to the DB API 2.0.</p>
    336. 

  336. </div>
    337. 

  337. </dd></dl>
    338. 

  338. 

  339. <dl class="attribute">
    340. 

  340. <dt id="cursor.rowcount">
    341. 

  341. <tt class="descname">rowcount</tt><a class="headerlink" href="#cursor.rowcount" title="Permalink to this definition"></a></dt>
    342. 

  342. <dd><p>This read-only attribute specifies the number of rows that the last
    343. 

  343. <a class="reference internal" href="#execute"><tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt></a> produced (for <abbr title="Data Query Language">DQL</abbr> statements
    344. 

  344. like <tt class="sql docutils literal"><span class="pre">SELECT</span></tt>) or affected (for
    345. 

  345. <abbr title="Data Manipulation Language">DML</abbr> statements like <tt class="sql docutils literal"><span class="pre">UPDATE</span></tt>
    346. 

  346. or <tt class="sql docutils literal"><span class="pre">INSERT</span></tt>).</p>
    347. 

  347. <p>The attribute is -1 in case no <tt class="xref py py-obj docutils literal"><span class="pre">execute*()</span></tt> has been performed on
    348. 

  348. the cursor or the row count of the last operation if it can&#8217;t be
    349. 

  349. determined by the interface.</p>
    350. 

  350. <div class="admonition note">
    351. 

  351. <p class="first admonition-title">Note</p>
    352. 

  352. <p class="last">The <a class="reference external" href="http://www.python.org/dev/peps/pep-0249/">DB API 2.0</a> interface reserves to redefine the latter case to
    353. 

  353. have the object return <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> instead of -1 in future versions
    354. 

  354. of the specification.</p>
    355. 

  355. </div>
    356. 

  356. </dd></dl>
    357. 

  357. 

  358. <dl class="attribute">
    359. 

  359. <dt id="cursor.rownumber">
    360. 

  360. <tt class="descname">rownumber</tt><a class="headerlink" href="#cursor.rownumber" title="Permalink to this definition"></a></dt>
    361. 

  361. <dd><p>This read-only attribute provides the current 0-based index of the
    362. 

  362. cursor in the result set or <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> if the index cannot be
    363. 

  363. determined.</p>
    364. 

  364. <p>The index can be seen as index of the cursor in a sequence (the result
    365. 

  365. set). The next fetch operation will fetch the row indexed by
    366. 

  366. <a class="reference internal" href="#cursor.rownumber" title="cursor.rownumber"><tt class="xref py py-obj docutils literal"><span class="pre">rownumber</span></tt></a> in that sequence.</p>
    367. 

  367. </dd></dl>
    368. 

  368. 

  369. <span class="target" id="index-1"></span><dl class="attribute">
    370. 

  370. <dt id="cursor.lastrowid">
    371. 

  371. <tt class="descname">lastrowid</tt><a class="headerlink" href="#cursor.lastrowid" title="Permalink to this definition"></a></dt>
    372. 

  372. <dd><p>This read-only attribute provides the OID of the last row inserted
    373. 

  373. by the cursor. If the table wasn&#8217;t created with OID support or the
    374. 

  374. last operation is not a single record insert, the attribute is set to
    375. 

  375. <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt>.</p>
    376. 

  376. <div class="admonition note">
    377. 

  377. <p class="first admonition-title">Note</p>
    378. 

  378. <p class="last">PostgreSQL currently advices to not create OIDs on the tables and
    379. 

  379. the default for <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/sql-createtable.html"><tt class="sql docutils literal"><span class="pre">CREATE</span> <span class="pre">TABLE</span></tt></a> is to not support them. The
    380. 

  380. <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/sql-insert.html"><tt class="sql docutils literal"><span class="pre">INSERT</span> <span class="pre">...</span> <span class="pre">RETURNING</span></tt></a> syntax available from PostgreSQL 8.3 allows
    381. 

  381. more flexibility.</p>
    382. 

  382. </div>
    383. 

  383. </dd></dl>
    384. 

  384. 

  385. <dl class="attribute">
    386. 

  386. <dt id="cursor.query">
    387. 

  387. <tt class="descname">query</tt><a class="headerlink" href="#cursor.query" title="Permalink to this definition"></a></dt>
    388. 

  388. <dd><p>Read-only attribute containing the body of the last query sent to the
    389. 

  389. backend (including bound arguments). <tt class="xref py py-obj xref docutils literal"><span class="pre">None</span></tt> if no query has been
    390. 

  390. executed yet:</p>
    391. 

  391. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;INSERT INTO test (num, data) VALUES (</span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">)&quot;</span><span class="p">,</span> <span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="s">&#39;bar&#39;</span><span class="p">))</span>
    392. 

  392. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">query</span>
    393. 

  393. <span class="go">&quot;INSERT INTO test (num, data) VALUES (42, E&#39;bar&#39;)&quot;</span>
    394. 

  394. </pre></div>
    395. 

  395. </div>
    396. 

  396. <div class="admonition-db-api-extension dbapi-extension admonition ">
    397. 

  397. <p class="first admonition-title">DB API extension</p>
    398. 

  398. <p class="last">The <a class="reference internal" href="#cursor.query" title="cursor.query"><tt class="xref py py-obj docutils literal"><span class="pre">query</span></tt></a> attribute is a Psycopg extension to the DB API 2.0.</p>
    399. 

  399. </div>
    400. 

  400. </dd></dl>
    401. 

  401. 

  402. <dl class="attribute">
    403. 

  403. <dt id="cursor.statusmessage">
    404. 

  404. <tt class="descname">statusmessage</tt><a class="headerlink" href="#cursor.statusmessage" title="Permalink to this definition"></a></dt>
    405. 

  405. <dd><p>Read-only attribute containing the message returned by the last
    406. 

  406. command:</p>
    407. 

  407. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;INSERT INTO test (num, data) VALUES (</span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">)&quot;</span><span class="p">,</span> <span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="s">&#39;bar&#39;</span><span class="p">))</span>
    408. 

  408. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">statusmessage</span>
    409. 

  409. <span class="go">&#39;INSERT 0 1&#39;</span>
    410. 

  410. </pre></div>
    411. 

  411. </div>
    412. 

  412. <div class="admonition-db-api-extension dbapi-extension admonition ">
    413. 

  413. <p class="first admonition-title">DB API extension</p>
    414. 

  414. <p class="last">The <a class="reference internal" href="#cursor.statusmessage" title="cursor.statusmessage"><tt class="xref py py-obj docutils literal"><span class="pre">statusmessage</span></tt></a> attribute is a Psycopg extension to the
    415. 

  415. DB API 2.0.</p>
    416. 

  416. </div>
    417. 

  417. </dd></dl>
    418. 

  418. 

  419. <dl class="method">
    420. 

  420. <dt id="cursor.cast">
    421. 

  421. <tt class="descname">cast</tt><big>(</big><em>oid</em>, <em>s</em><big>)</big><a class="headerlink" href="#cursor.cast" title="Permalink to this definition"></a></dt>
    422. 

  422. <dd><p>Convert a value from the PostgreSQL string representation to a Python
    423. 

  423. object.</p>
    424. 

  424. <p>Use the most specific of the typecasters registered by
    425. 

  425. <a class="reference internal" href="extensions.html#psycopg2.extensions.register_type" title="psycopg2.extensions.register_type"><tt class="xref py py-obj docutils literal"><span class="pre">register_type()</span></tt></a>.</p>
    426. 

  426. <p class="versionadded">
    427. 

  427. <span class="versionmodified">New in version 2.4.</span></p>
    428. 

  428. <div class="admonition-db-api-extension dbapi-extension admonition ">
    429. 

  429. <p class="first admonition-title">DB API extension</p>
    430. 

  430. <p class="last">The <a class="reference internal" href="#cursor.cast" title="cursor.cast"><tt class="xref py py-obj docutils literal"><span class="pre">cast()</span></tt></a> method is a Psycopg extension to the DB API 2.0.</p>
    431. 

  431. </div>
    432. 

  432. </dd></dl>
    433. 

  433. 

  434. <dl class="attribute">
    435. 

  435. <dt id="cursor.tzinfo_factory">
    436. 

  436. <tt class="descname">tzinfo_factory</tt><a class="headerlink" href="#cursor.tzinfo_factory" title="Permalink to this definition"></a></dt>
    437. 

  437. <dd><p>The time zone factory used to handle data types such as
    438. 

  438. <tt class="sql docutils literal"><span class="pre">TIMESTAMP</span> <span class="pre">WITH</span> <span class="pre">TIME</span> <span class="pre">ZONE</span></tt>.  It should be a <a class="reference external" href="http://docs.python.org/3.2/library/datetime.html#datetime.tzinfo" title="(in Python v3.2)"><tt class="xref py py-obj docutils literal"><span class="pre">tzinfo</span></tt></a>
    439. 

  439. object.  A few implementations are available in the <a class="reference internal" href="tz.html#module-psycopg2.tz" title="psycopg2.tz"><tt class="xref py py-obj docutils literal"><span class="pre">psycopg2.tz</span></tt></a>
    440. 

  440. module.</p>
    441. 

  441. </dd></dl>
    442. 

  442. 

  443. <dl class="method">
    444. 

  444. <dt id="cursor.nextset">
    445. 

  445. <tt class="descname">nextset</tt><big>(</big><big>)</big><a class="headerlink" href="#cursor.nextset" title="Permalink to this definition"></a></dt>
    446. 

  446. <dd><p>This method is not supported (PostgreSQL does not have multiple data
    447. 

  447. sets) and will raise a <a class="reference internal" href="module.html#psycopg2.NotSupportedError" title="psycopg2.NotSupportedError"><tt class="xref py py-obj docutils literal"><span class="pre">NotSupportedError</span></tt></a> exception.</p>
    448. 

  448. </dd></dl>
    449. 

  449. 

  450. <dl class="method">
    451. 

  451. <dt id="cursor.setoutputsize">
    452. 

  452. <tt class="descname">setoutputsize</tt><big>(</big><em>size</em><span class="optional">[</span>, <em>column</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#cursor.setoutputsize" title="Permalink to this definition"></a></dt>
    453. 

  453. <dd><p>This method is exposed in compliance with the DB API 2.0. It currently
    454. 

  454. does nothing but it is safe to call it.</p>
    455. 

  455. </dd></dl>
    456. 

  456. 

  457. <p class="rubric">COPY-related methods</p>
    458. 

  458. <div class="admonition-db-api-extension dbapi-extension admonition ">
    459. 

  459. <p class="first admonition-title">DB API extension</p>
    460. 

  460. <p class="last">The <tt class="sql docutils literal"><span class="pre">COPY</span></tt> command is a PostgreSQL extension to the SQL standard.
    461. 

  461. As such, its support is a Psycopg extension to the DB API 2.0.</p>
    462. 

  462. </div>
    463. 

  463. <dl class="method">
    464. 

  464. <dt id="cursor.copy_from">
    465. 

  465. <tt class="descname">copy_from</tt><big>(</big><em>file</em>, <em>table</em>, <em>sep='\t'</em>, <em>null='\N'</em>, <em>size=8192</em>, <em>columns=None</em><big>)</big><a class="headerlink" href="#cursor.copy_from" title="Permalink to this definition"></a></dt>
    466. 

  466. <dd><p>Read data <em>from</em> the file-like object <em>file</em> appending them to
    467. 

  467. the table named <em>table</em>.  See <a class="reference internal" href="usage.html#copy"><em>Using COPY TO and COPY FROM</em></a> for an overview.</p>
    468. 

  468. <table class="docutils field-list" frame="void" rules="none">
    469. 

  469. <col class="field-name" />
    470. 

  470. <col class="field-body" />
    471. 

  471. <tbody valign="top">
    472. 

  472. <tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
    473. 

  473. <li><strong>file</strong> &#8211; file-like object to read data from.  It must have both
    474. 

  474. <tt class="xref py py-obj docutils literal"><span class="pre">read()</span></tt> and <tt class="xref py py-obj docutils literal"><span class="pre">readline()</span></tt> methods.</li>
    475. 

  475. <li><strong>table</strong> &#8211; name of the table to copy data into.</li>
    476. 

  476. <li><strong>sep</strong> &#8211; columns separator expected in the file. Defaults to a tab.</li>
    477. 

  477. <li><strong>null</strong> &#8211; textual representation of <tt class="sql docutils literal"><span class="pre">NULL</span></tt> in the file.</li>
    478. 

  478. <li><strong>size</strong> &#8211; size of the buffer used to read from the file.</li>
    479. 

  479. <li><strong>columns</strong> &#8211; iterable with name of the columns to import.
    480. 

  480. The length and types should match the content of the file to read.
    481. 

  481. If not specified, it is assumed that the entire table matches the
    482. 

  482. file structure.</li>
    483. 

  483. </ul>
    484. 

  484. </td>
    485. 

  485. </tr>
    486. 

  486. </tbody>
    487. 

  487. </table>
    488. 

  488. <p>Example:</p>
    489. 

  489. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">(</span><span class="s">&quot;42</span><span class="se">\t</span><span class="s">foo</span><span class="se">\n</span><span class="s">74</span><span class="se">\t</span><span class="s">bar</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">)</span>
    490. 

  490. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">copy_from</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="s">&#39;test&#39;</span><span class="p">,</span> <span class="n">columns</span><span class="o">=</span><span class="p">(</span><span class="s">&#39;num&#39;</span><span class="p">,</span> <span class="s">&#39;data&#39;</span><span class="p">))</span>
    491. 

  491. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">&quot;select * from test where id &gt; 5;&quot;</span><span class="p">)</span>
    492. 

  492. <span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span>
    493. 

  493. <span class="go">[(6, 42, &#39;foo&#39;), (7, 74, &#39;bar&#39;)]</span>
    494. 

  494. </pre></div>
    495. 

  495. </div>
    496. 

  496. <p class="versionchanged">
    497. 

  497. <span class="versionmodified">Changed in version 2.0.6: </span>added the <em>columns</em> parameter.</p>
    498. 

  498. <p class="versionchanged">
    499. 

  499. <span class="versionmodified">Changed in version 2.4: </span>data read from files implementing the <a class="reference external" href="http://docs.python.org/3.2/library/io.html#io.TextIOBase" title="(in Python v3.2)"><tt class="xref py py-obj docutils literal"><span class="pre">io.TextIOBase</span></tt></a> interface
    500. 

  500. are encoded in the connection <a class="reference internal" href="connection.html#connection.encoding" title="connection.encoding"><tt class="xref py py-obj docutils literal"><span class="pre">encoding</span></tt></a> when sent to
    501. 

  501. the backend.</p>
    502. 

  502. </dd></dl>
    503. 

  503. 

  504. <dl class="method">
    505. 

  505. <dt id="cursor.copy_to">
    506. 

  506. <tt class="descname">copy_to</tt><big>(</big><em>file</em>, <em>table</em>, <em>sep='\t'</em>, <em>null='\N'</em>, <em>columns=None</em><big>)</big><a class="headerlink" href="#cursor.copy_to" title="Permalink to this definition"></a></dt>
    507. 

  507. <dd><p>Write the content of the table named <em>table</em> <em>to</em> the file-like
    508. 

  508. object <em>file</em>.  See <a class="reference internal" href="usage.html#copy"><em>Using COPY TO and COPY FROM</em></a> for an overview.</p>
    509. 

  509. <table class="docutils field-list" frame="void" rules="none">
    510. 

  510. <col class="field-name" />
    511. 

  511. <col class="field-body" />
    512. 

  512. <tbody valign="top">
    513. 

  513. <tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
    514. 

  514. <li><strong>file</strong> &#8211; file-like object to write data into.  It must have a
    515. 

  515. <tt class="xref py py-obj docutils literal"><span class="pre">write()</span></tt> method.</li>
    516. 

  516. <li><strong>table</strong> &#8211; name of the table to copy data from.</li>
    517. 

  517. <li><strong>sep</strong> &#8211; columns separator expected in the file. Defaults to a tab.</li>
    518. 

  518. <li><strong>null</strong> &#8211; textual representation of <tt class="sql docutils literal"><span class="pre">NULL</span></tt> in the file.</li>
    519. 

  519. <li><strong>columns</strong> &#8211; iterable with name of the columns to export.
    520. 

  520. If not specified, export all the columns.</li>
    521. 

  521. </ul>
    522. 

  522. </td>
    523. 

  523. </tr>
    524. 

  524. </tbody>
    525. 

  525. </table>
    526. 

  526. <p>Example:</p>
    527. 

  527. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">copy_to</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="s">&#39;test&#39;</span><span class="p">,</span> <span class="n">sep</span><span class="o">=</span><span class="s">&quot;|&quot;</span><span class="p">)</span>
    528. 

  528. <span class="go">1|100|abc&#39;def</span>
    529. 

  529. <span class="go">2|\N|dada</span>
    530. 

  530. <span class="gp">...</span>
    531. 

  531. </pre></div>
    532. 

  532. </div>
    533. 

  533. <p class="versionchanged">
    534. 

  534. <span class="versionmodified">Changed in version 2.0.6: </span>added the <em>columns</em> parameter.</p>
    535. 

  535. <p class="versionchanged">
    536. 

  536. <span class="versionmodified">Changed in version 2.4: </span>data sent to files implementing the <a class="reference external" href="http://docs.python.org/3.2/library/io.html#io.TextIOBase" title="(in Python v3.2)"><tt class="xref py py-obj docutils literal"><span class="pre">io.TextIOBase</span></tt></a> interface
    537. 

  537. are decoded in the connection <a class="reference internal" href="connection.html#connection.encoding" title="connection.encoding"><tt class="xref py py-obj docutils literal"><span class="pre">encoding</span></tt></a> when read
    538. 

  538. from the backend.</p>
    539. 

  539. </dd></dl>
    540. 

  540. 

  541. <dl class="method">
    542. 

  542. <dt id="cursor.copy_expert">
    543. 

  543. <tt class="descname">copy_expert</tt><big>(</big><em>sql</em>, <em>file</em>, <em>size=8192</em><big>)</big><a class="headerlink" href="#cursor.copy_expert" title="Permalink to this definition"></a></dt>
    544. 

  544. <dd><p>Submit a user-composed <tt class="sql docutils literal"><span class="pre">COPY</span></tt> statement. The method is useful to
    545. 

  545. handle all the parameters that PostgreSQL makes available (see
    546. 

  546. <a class="reference external" href="http://www.postgresql.org/docs/9.0/static/sql-copy.html"><tt class="sql docutils literal"><span class="pre">COPY</span></tt></a> command documentation).</p>
    547. 

  547. <table class="docutils field-list" frame="void" rules="none">
    548. 

  548. <col class="field-name" />
    549. 

  549. <col class="field-body" />
    550. 

  550. <tbody valign="top">
    551. 

  551. <tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
    552. 

  552. <li><strong>sql</strong> &#8211; the <tt class="sql docutils literal"><span class="pre">COPY</span></tt> statement to execute.</li>
    553. 

  553. <li><strong>file</strong> &#8211; a file-like object; must be a readable file for
    554. 

  554. <tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">FROM</span></tt> or an writeable file for <tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">TO</span></tt>.</li>
    555. 

  555. <li><strong>size</strong> &#8211; size of the read buffer to be used in <tt class="sql docutils literal"><span class="pre">COPY</span> <span class="pre">FROM</span></tt>.</li>
    556. 

  556. </ul>
    557. 

  557. </td>
    558. 

  558. </tr>
    559. 

  559. </tbody>
    560. 

  560. </table>
    561. 

  561. <p>Example:</p>
    562. 

  562. <div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">cur</span><span class="o">.</span><span class="n">copy_expert</span><span class="p">(</span><span class="s">&quot;COPY test TO STDOUT WITH CSV HEADER&quot;</span><span class="p">,</span> <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span><span class="p">)</span>
    563. 

  563. <span class="go">id,num,data</span>
    564. 

  564. <span class="go">1,100,abc&#39;def</span>
    565. 

  565. <span class="go">2,,dada</span>
    566. 

  566. <span class="gp">...</span>
    567. 

  567. </pre></div>
    568. 

  568. </div>
    569. 

  569. <p class="versionadded">
    570. 

  570. <span class="versionmodified">New in version 2.0.6.</span></p>
    571. 

  571. <p class="versionchanged">
    572. 

  572. <span class="versionmodified">Changed in version 2.4: </span>files implementing the <a class="reference external" href="http://docs.python.org/3.2/library/io.html#io.TextIOBase" title="(in Python v3.2)"><tt class="xref py py-obj docutils literal"><span class="pre">io.TextIOBase</span></tt></a> interface are dealt with
    573. 

  573. using Unicode data instead of bytes.</p>
    574. 

  574. </dd></dl>
    575. 

  575. 

  576. </dd></dl>
    577. 

  577. 

  578. </div>
    579. 

  579. 

  580. 

  581.           </div>
    582. 

  582.         </div>
    583. 

  583.       </div>
    584. 

  584.       <div class="sphinxsidebar">
    585. 

  585.         <div class="sphinxsidebarwrapper">
    586. 

  586.   <h4>Previous topic</h4>
    587. 

  587.   <p class="topless"><a href="connection.html"
    588. 

  588.                         title="previous chapter">The <tt class="docutils literal docutils literal"><span class="pre">connection</span></tt> class</a></p>
    589. 

  589.   <h4>Next topic</h4>
    590. 

  590.   <p class="topless"><a href="advanced.html"
    591. 

  591.                         title="next chapter">More advanced topics</a></p>
    592. 

  592.   <h3>This Page</h3>
    593. 

  593.   <ul class="this-page-menu">
    594. 

  594.     <li><a href="_sources/cursor.txt"
    595. 

  595.            rel="nofollow">Show Source</a></li>
    596. 

  596.   </ul>
    597. 

  597. <div id="searchbox" style="display: none">
    598. 

  598.   <h3>Quick search</h3>
    599. 

  599.     <form class="search" action="search.html" method="get">
    600. 

  600.       <input type="text" name="q" size="18" />
    601. 

  601.       <input type="submit" value="Go" />
    602. 

  602.       <input type="hidden" name="check_keywords" value="yes" />
    603. 

  603.       <input type="hidden" name="area" value="default" />
    604. 

  604.     </form>
    605. 

  605.     <p class="searchtip" style="font-size: 90%">
    606. 

  606.     Enter search terms or a module, class or function name.
    607. 

  607.     </p>
    608. 

  608. </div>
    609. 

  609. <script type="text/javascript">$('#searchbox').show(0);</script>
    610. 

  610.         </div>
    611. 

  611.       </div>
    612. 

  612.       <div class="clearer"></div>
    613. 

  613.     </div>
    614. 

  614.     <div class="related">
    615. 

  615.       <h3>Navigation</h3>
    616. 

  616.       <ul>
    617. 

  617.         <li class="right" style="margin-right: 10px">
    618. 

  618.           <a href="genindex.html" title="General Index"
    619. 

  619.              >index</a></li>
    620. 

  620.         <li class="right" >
    621. 

  621.           <a href="py-modindex.html" title="Python Module Index"
    622. 

  622.              >modules</a> |</li>
    623. 

  623.         <li class="right" >
    624. 

  624.           <a href="advanced.html" title="More advanced topics"
    625. 

  625.              >next</a> |</li>
    626. 

  626.         <li class="right" >
    627. 

  627.           <a href="connection.html" title="The connection class"
    628. 

  628.              >previous</a> |</li>
    629. 

  629.         <li><a href="index.html">Psycopg v2.4.2 documentation</a> &raquo;</li> 
    630. 

  630.       </ul>
    631. 

  631.     </div>
    632. 

  632.     <div class="footer">
    633. 

  633.         &copy; Copyright 2001-2011, Federico Di Gregorio. Documentation by Daniele Varrazzo.
    634. 

  634.       Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
    635. 

  635.     </div>
    636. 

  636.   </body>
    637. 

  637. </html>
    638.