begriffs open source - ai-pg/blob - full-docs/src/sgml/html/spi-spi-execute.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!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>SPI_execute</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="spi-spi-finish.html" title="SPI_finish" /><link rel="next" href="spi-spi-exec.html" title="SPI_exec" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SPI_execute</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="spi-spi-finish.html" title="SPI_finish">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="spi-interface.html" title="45.1. Interface Functions">Up</a></td><th width="60%" align="center">45.1. Interface Functions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="spi-spi-exec.html" title="SPI_exec">Next</a></td></tr></table><hr /></div><div class="refentry" id="SPI-SPI-EXECUTE"><div class="titlepage"></div><a id="id-1.8.12.8.4.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SPI_execute</span></h2><p>SPI_execute — execute a command</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 int SPI_execute(const char * <em class="parameter"><code>command</code></em>, bool <em class="parameter"><code>read_only</code></em>, long <em class="parameter"><code>count</code></em>)
   4 </pre></div><div class="refsect1" id="id-1.8.12.8.4.5"><h2>Description</h2><p>
   5    <code class="function">SPI_execute</code> executes the specified SQL command
   6    for <em class="parameter"><code>count</code></em> rows.  If <em class="parameter"><code>read_only</code></em>
   7    is <code class="literal">true</code>, the command must be read-only, and execution overhead
   8    is somewhat reduced.
   9   </p><p>
  10    This function can only be called from a connected C function.
  11   </p><p>
  12    If <em class="parameter"><code>count</code></em> is zero then the command is executed
  13    for all rows that it applies to.  If <em class="parameter"><code>count</code></em>
  14    is greater than zero, then no more than <em class="parameter"><code>count</code></em> rows
  15    will be retrieved; execution stops when the count is reached, much like
  16    adding a <code class="literal">LIMIT</code> clause to the query. For example,
  17 </p><pre class="programlisting">
  18 SPI_execute("SELECT * FROM foo", true, 5);
  19 </pre><p>
  20    will retrieve at most 5 rows from the table.  Note that such a limit
  21    is only effective when the command actually returns rows.  For example,
  22 </p><pre class="programlisting">
  23 SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
  24 </pre><p>
  25    inserts all rows from <code class="structname">bar</code>, ignoring the
  26    <em class="parameter"><code>count</code></em> parameter.  However, with
  27 </p><pre class="programlisting">
  28 SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
  29 </pre><p>
  30    at most 5 rows would be inserted, since execution would stop after the
  31    fifth <code class="literal">RETURNING</code> result row is retrieved.
  32   </p><p>
  33    You can pass multiple commands in one string;
  34    <code class="function">SPI_execute</code> returns the
  35    result for the command executed last.  The <em class="parameter"><code>count</code></em>
  36    limit applies to each command separately (even though only the last
  37    result will actually be returned).  The limit is not applied to any
  38    hidden commands generated by rules.
  39   </p><p>
  40    When <em class="parameter"><code>read_only</code></em> is <code class="literal">false</code>,
  41    <code class="function">SPI_execute</code> increments the command
  42    counter and computes a new <em class="firstterm">snapshot</em> before executing each
  43    command in the string.  The snapshot does not actually change if the
  44    current transaction isolation level is <code class="literal">SERIALIZABLE</code> or <code class="literal">REPEATABLE READ</code>, but in
  45    <code class="literal">READ COMMITTED</code> mode the snapshot update allows each command to
  46    see the results of newly committed transactions from other sessions.
  47    This is essential for consistent behavior when the commands are modifying
  48    the database.
  49   </p><p>
  50    When <em class="parameter"><code>read_only</code></em> is <code class="literal">true</code>,
  51    <code class="function">SPI_execute</code> does not update either the snapshot
  52    or the command counter, and it allows only plain <code class="command">SELECT</code>
  53    commands to appear in the command string.  The commands are executed
  54    using the snapshot previously established for the surrounding query.
  55    This execution mode is somewhat faster than the read/write mode due
  56    to eliminating per-command overhead.  It also allows genuinely
  57    <em class="firstterm">stable</em> functions to be built: since successive executions
  58    will all use the same snapshot, there will be no change in the results.
  59   </p><p>
  60    It is generally unwise to mix read-only and read-write commands within
  61    a single function using SPI; that could result in very confusing behavior,
  62    since the read-only queries would not see the results of any database
  63    updates done by the read-write queries.
  64   </p><p>
  65    The actual number of rows for which the (last) command was executed
  66    is returned in the global variable <code class="varname">SPI_processed</code>.
  67    If the return value of the function is <code class="symbol">SPI_OK_SELECT</code>,
  68    <code class="symbol">SPI_OK_INSERT_RETURNING</code>,
  69    <code class="symbol">SPI_OK_DELETE_RETURNING</code>,
  70    <code class="symbol">SPI_OK_UPDATE_RETURNING</code>, or
  71    <code class="symbol">SPI_OK_MERGE_RETURNING</code>,
  72    then you can use the
  73    global pointer <code class="literal">SPITupleTable *SPI_tuptable</code> to
  74    access the result rows.  Some utility commands (such as
  75    <code class="command">EXPLAIN</code>) also return row sets, and <code class="literal">SPI_tuptable</code>
  76    will contain the result in these cases too. Some utility commands
  77    (<code class="command">COPY</code>, <code class="command">CREATE TABLE AS</code>) don't return a row set, so
  78    <code class="literal">SPI_tuptable</code> is NULL, but they still return the number of
  79    rows processed in <code class="varname">SPI_processed</code>.
  80   </p><p>
  81    The structure <code class="structname">SPITupleTable</code> is defined
  82    thus:
  83 </p><pre class="programlisting">
  84 typedef struct SPITupleTable
  85 {
  86     /* Public members */
  87     TupleDesc   tupdesc;        /* tuple descriptor */
  88     HeapTuple  *vals;           /* array of tuples */
  89     uint64      numvals;        /* number of valid tuples */
  90
  91     /* Private members, not intended for external callers */
  92     uint64      alloced;        /* allocated length of vals array */
  93     MemoryContext tuptabcxt;    /* memory context of result table */
  94     slist_node  next;           /* link for internal bookkeeping */
  95     SubTransactionId subid;     /* subxact in which tuptable was created */
  96 } SPITupleTable;
  97 </pre><p>
  98    The fields <code class="structfield">tupdesc</code>,
  99    <code class="structfield">vals</code>, and
 100    <code class="structfield">numvals</code>
 101    can be used by SPI callers; the remaining fields are internal.
 102    <code class="structfield">vals</code> is an array of pointers to rows.
 103    The number of rows is given by <code class="structfield">numvals</code>
 104    (for somewhat historical reasons, this count is also returned
 105    in <code class="varname">SPI_processed</code>).
 106    <code class="structfield">tupdesc</code> is a row descriptor which you can pass to
 107    SPI functions dealing with rows.
 108   </p><p>
 109    <code class="function">SPI_finish</code> frees all
 110    <code class="structname">SPITupleTable</code>s allocated during the current
 111    C function.  You can free a particular result table earlier, if you
 112    are done with it, by calling <code class="function">SPI_freetuptable</code>.
 113   </p></div><div class="refsect1" id="id-1.8.12.8.4.6"><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">const char * <em class="parameter"><code>command</code></em></code></span></dt><dd><p>
 114       string containing command to execute
 115      </p></dd><dt><span class="term"><code class="literal">bool <em class="parameter"><code>read_only</code></em></code></span></dt><dd><p><code class="literal">true</code> for read-only execution</p></dd><dt><span class="term"><code class="literal">long <em class="parameter"><code>count</code></em></code></span></dt><dd><p>
 116       maximum number of rows to return,
 117       or <code class="literal">0</code> for no limit
 118      </p></dd></dl></div></div><div class="refsect1" id="id-1.8.12.8.4.7"><h2>Return Value</h2><p>
 119    If the execution of the command was successful then one of the
 120    following (nonnegative) values will be returned:
 121
 122    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_OK_SELECT</code></span></dt><dd><p>
 123        if a <code class="command">SELECT</code> (but not <code class="command">SELECT
 124        INTO</code>) was executed
 125       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_SELINTO</code></span></dt><dd><p>
 126        if a <code class="command">SELECT INTO</code> was executed
 127       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_INSERT</code></span></dt><dd><p>
 128        if an <code class="command">INSERT</code> was executed
 129       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_DELETE</code></span></dt><dd><p>
 130        if a <code class="command">DELETE</code> was executed
 131       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_UPDATE</code></span></dt><dd><p>
 132        if an <code class="command">UPDATE</code> was executed
 133       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_MERGE</code></span></dt><dd><p>
 134        if a <code class="command">MERGE</code> was executed
 135       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_INSERT_RETURNING</code></span></dt><dd><p>
 136        if an <code class="command">INSERT RETURNING</code> was executed
 137       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_DELETE_RETURNING</code></span></dt><dd><p>
 138        if a <code class="command">DELETE RETURNING</code> was executed
 139       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_UPDATE_RETURNING</code></span></dt><dd><p>
 140        if an <code class="command">UPDATE RETURNING</code> was executed
 141       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_MERGE_RETURNING</code></span></dt><dd><p>
 142        if a <code class="command">MERGE RETURNING</code> was executed
 143       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_UTILITY</code></span></dt><dd><p>
 144        if a utility command (e.g., <code class="command">CREATE TABLE</code>)
 145        was executed
 146       </p></dd><dt><span class="term"><code class="symbol">SPI_OK_REWRITTEN</code></span></dt><dd><p>
 147        if the command was rewritten into another kind of command (e.g.,
 148        <code class="command">UPDATE</code> became an <code class="command">INSERT</code>) by a <a class="link" href="rules.html" title="Chapter 39. The Rule System">rule</a>.
 149       </p></dd></dl></div><p>
 150   </p><p>
 151    On error, one of the following negative values is returned:
 152
 153    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="symbol">SPI_ERROR_ARGUMENT</code></span></dt><dd><p>
 154        if <em class="parameter"><code>command</code></em> is <code class="symbol">NULL</code> or
 155        <em class="parameter"><code>count</code></em> is less than 0
 156       </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_COPY</code></span></dt><dd><p>
 157        if <code class="command">COPY TO stdout</code> or <code class="command">COPY FROM stdin</code>
 158        was attempted
 159       </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_TRANSACTION</code></span></dt><dd><p>
 160        if a transaction manipulation command was attempted
 161        (<code class="command">BEGIN</code>,
 162        <code class="command">COMMIT</code>,
 163        <code class="command">ROLLBACK</code>,
 164        <code class="command">SAVEPOINT</code>,
 165        <code class="command">PREPARE TRANSACTION</code>,
 166        <code class="command">COMMIT PREPARED</code>,
 167        <code class="command">ROLLBACK PREPARED</code>,
 168        or any variant thereof)
 169       </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_OPUNKNOWN</code></span></dt><dd><p>
 170        if the command type is unknown (shouldn't happen)
 171       </p></dd><dt><span class="term"><code class="symbol">SPI_ERROR_UNCONNECTED</code></span></dt><dd><p>
 172        if called from an unconnected C function
 173       </p></dd></dl></div><p>
 174   </p></div><div class="refsect1" id="id-1.8.12.8.4.8"><h2>Notes</h2><p>
 175    All SPI query-execution functions set both
 176    <code class="varname">SPI_processed</code> and
 177    <code class="varname">SPI_tuptable</code> (just the pointer, not the contents
 178    of the structure).  Save these two global variables into local
 179    C function variables if you need to access the result table of
 180    <code class="function">SPI_execute</code> or another query-execution function
 181    across later calls.
 182   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="spi-spi-finish.html" title="SPI_finish">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="spi-interface.html" title="45.1. Interface Functions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="spi-spi-exec.html" title="SPI_exec">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SPI_finish </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SPI_exec</td></tr></table></div></body></html>