Home • Explore • Blog • CI
☰



postgresql
11th chunk of `doc/src/sgml/spi.sgml`
4a19206244b56a592a3f6302045685bff3fadfb580d8a0980000000100000fa1
 <varname>SPI_tuptable</varname> are set as in
   <function>SPI_execute</function> if successful.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-prepare">
 <indexterm><primary>SPI_prepare</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_prepare</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_prepare</refname>
  <refpurpose>prepare a statement, without executing it yet</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
SPIPlanPtr SPI_prepare(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_prepare</function> creates and returns a prepared
   statement for the specified command, but doesn't execute the command.
   The prepared statement can later be executed repeatedly using
   <function>SPI_execute_plan</function>.
  </para>

  <para>
   When the same or a similar command is to be executed repeatedly, it
   is generally advantageous to perform parse analysis only once, and
   might furthermore be advantageous to re-use an execution plan for the
   command.
   <function>SPI_prepare</function> converts a command string into a
   prepared statement that encapsulates the results of parse analysis.
   The prepared statement also provides a place for caching an execution plan
   if it is found that generating a custom plan for each execution is not
   helpful.
  </para>

  <para>
   A prepared command can be generalized by writing parameters
   (<literal>$1</literal>, <literal>$2</literal>, etc.) in place of what would be
   constants in a normal command.  The actual values of the parameters
   are then specified when <function>SPI_execute_plan</function> is called.
   This allows the prepared command to be used over a wider range of
   situations than would be possible without parameters.
  </para>

  <para>
   The statement returned by <function>SPI_prepare</function> can be used
   only in the current invocation of the C function, since
   <function>SPI_finish</function> frees memory allocated for such a
   statement.  But the statement can be saved for longer using the functions
   <function>SPI_keepplan</function> or <function>SPI_saveplan</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      command string
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>nargs</parameter></literal></term>
    <listitem>
     <para>
      number of input parameters (<literal>$1</literal>, <literal>$2</literal>, etc.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
    <listitem>
     <para>
      pointer to an array containing the <acronym>OID</acronym>s of
      the data types of the parameters
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   <function>SPI_prepare</function> returns a non-null pointer to an
   <type>SPIPlan</type>, which is an opaque struct representing a prepared
   statement.  On error, <symbol>NULL</symbol> will be returned,
   and <varname>SPI_result</varname> will be set to one of the same
   error codes used by <function>SPI_execute</function>, except that
   it is set to <symbol>SPI_ERROR_ARGUMENT</symbol> if
   <parameter>command</parameter> is <symbol>NULL</symbol>, or if
   <parameter>nargs</parameter> is less than 0, or if <parameter>nargs</parameter> is
   greater than 0 and <parameter>argtypes</parameter> is <symbol>NULL</symbol>.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   If no parameters are defined, a generic
Title: SPI_prepare Function: Description, Arguments, and Return Value
Summary
This section delves into the `SPI_prepare` function, which creates a prepared statement from a command string for later execution. It explains the advantages of using prepared statements for repeated execution, parameterization of commands, and the lifespan of prepared statements. The section then outlines the arguments of the `SPI_prepare` function: the command string, number of input parameters, and an array of parameter data types. Finally, it details the return value, which is a pointer to an `SPIPlan` struct representing the prepared statement or NULL in case of an error, with `SPI_result` set accordingly.