Home • Explore • Blog • CI
☰



postgresql
47th chunk of `doc/src/sgml/spi.sgml`
b91c1e80e19e5b9023f8fea317b0dbb0f6c24f0c5459b71a0000000100000fa2
 function is no longer different from plain
   <function>heap_freetuple</function>.  It's kept just for backward
   compatibility of existing code.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      row to free
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-freetupletable">
 <indexterm><primary>SPI_freetuptable</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_freetuptable</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_freetuptable</refname>
  <refpurpose>free a row set created by <function>SPI_execute</function> or a similar
  function</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
void SPI_freetuptable(SPITupleTable * <parameter>tuptable</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_freetuptable</function> frees a row set created by a
   prior SPI command execution function, such as
   <function>SPI_execute</function>.  Therefore, this function is often called
   with the global variable <varname>SPI_tuptable</varname> as
   argument.
  </para>

  <para>
   This function is useful if an SPI-using C function needs to execute
   multiple commands and does not want to keep the results of earlier
   commands around until it ends.  Note that any unfreed row sets will
   be freed anyway at <function>SPI_finish</function>.
   Also, if a subtransaction is started and then aborted within execution
   of an SPI-using C function, SPI automatically frees any row sets created while
   the subtransaction was running.
  </para>

  <para>
   Beginning in <productname>PostgreSQL</productname> 9.3,
   <function>SPI_freetuptable</function> contains guard logic to protect
   against duplicate deletion requests for the same row set.  In previous
   releases, duplicate deletions would lead to crashes.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPITupleTable * <parameter>tuptable</parameter></literal></term>
    <listitem>
     <para>
      pointer to row set to free, or NULL to do nothing
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-freeplan">
 <indexterm><primary>SPI_freeplan</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_freeplan</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_freeplan</refname>
  <refpurpose>free a previously saved prepared statement</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
int SPI_freeplan(SPIPlanPtr <parameter>plan</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_freeplan</function> releases a prepared statement
   previously returned by <function>SPI_prepare</function> or saved by
   <function>SPI_keepplan</function> or <function>SPI_saveplan</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      pointer to statement to free
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   0 on success;
   <symbol>SPI_ERROR_ARGUMENT</symbol> if <parameter>plan</parameter>
   is <symbol>NULL</symbol> or invalid
  </para>
 </refsect1>
</refentry>

 </sect1>

 <sect1 id="spi-transaction">
  <title>Transaction Management</title>

  <para>
   It is not possible to run transaction control commands such
   as <command>COMMIT</command> and <command>ROLLBACK</command> through SPI
   functions
Title: SPI_freetuptable: Freeing Row Sets and SPI_freeplan: Freeing Prepared Statements
Summary
This section details `SPI_freetuptable`, which frees a row set created by SPI command execution functions like `SPI_execute`. It explains how this function is useful for managing memory when executing multiple commands and notes the automatic freeing of row sets at `SPI_finish` or during subtransaction aborts. It also mentions the addition of guard logic in PostgreSQL 9.3 to prevent duplicate deletion crashes. Additionally, it describes `SPI_freeplan`, which releases a prepared statement previously returned by `SPI_prepare` or saved by `SPI_keepplan` or `SPI_saveplan`.