2002-08-27 06:55:12 +02:00
|
|
|
<!--
|
2003-08-17 06:46:59 +02:00
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/prepare.sgml,v 1.5 2003/08/17 04:46:59 momjian Exp $
|
2002-08-27 06:55:12 +02:00
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
|
|
|
<refentry id="SQL-PREPARE">
|
|
|
|
<refmeta>
|
|
|
|
<refentrytitle id="sql-prepare-title">PREPARE</refentrytitle>
|
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
2002-08-27 06:55:12 +02:00
|
|
|
<refnamediv>
|
2003-04-27 01:56:51 +02:00
|
|
|
<refname>PREPARE</refname>
|
|
|
|
<refpurpose>prepare a statement for execution</refpurpose>
|
2002-08-27 06:55:12 +02:00
|
|
|
</refnamediv>
|
2003-04-27 01:56:51 +02:00
|
|
|
|
2002-08-27 06:55:12 +02:00
|
|
|
<refsynopsisdiv>
|
2003-04-27 01:56:51 +02:00
|
|
|
<synopsis>
|
|
|
|
PREPARE <replaceable class="PARAMETER">plan_name</replaceable> [ (<replaceable class="PARAMETER">datatype</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">statement</replaceable>
|
|
|
|
</synopsis>
|
2002-08-27 06:55:12 +02:00
|
|
|
</refsynopsisdiv>
|
|
|
|
|
2003-04-27 01:56:51 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
2002-08-27 06:55:12 +02:00
|
|
|
<para>
|
2003-04-27 01:56:51 +02:00
|
|
|
<command>PREPARE</command> creates a prepared statement. A prepared
|
|
|
|
statement is a server-side object that can be used to optimize
|
2002-08-27 06:55:12 +02:00
|
|
|
performance. When the <command>PREPARE</command> statement is
|
2003-04-27 01:56:51 +02:00
|
|
|
executed, the specified statement is parsed, rewritten, and
|
|
|
|
planned. When an <command>EXECUTE</command> command is subsequently
|
|
|
|
issued, the prepared statement need only be executed. Thus, the
|
2002-08-27 06:55:12 +02:00
|
|
|
parsing, rewriting, and planning stages are only performed once,
|
2003-04-27 01:56:51 +02:00
|
|
|
instead of every time the statement is executed.
|
2002-08-27 06:55:12 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-27 01:56:51 +02:00
|
|
|
Prepared statements can take parameters: values that are
|
|
|
|
substituted into the statement when it is executed. To include
|
|
|
|
parameters in a prepared statement, supply a list of data types in
|
|
|
|
the <command>PREPARE</command> statement, and, in the statement to
|
|
|
|
be prepared itself, refer to the parameters by position using
|
2002-08-27 06:55:12 +02:00
|
|
|
<literal>$1</literal>, <literal>$2</literal>, etc. When executing
|
2003-04-27 01:56:51 +02:00
|
|
|
the statement, specify the actual values for these parameters in
|
|
|
|
the <command>EXECUTE</command> statement. Refer to <xref
|
|
|
|
linkend="sql-execute" endterm="sql-execute-title"> for more
|
|
|
|
information about that.
|
2002-08-27 06:55:12 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-27 01:56:51 +02:00
|
|
|
Prepared statements are only stored in and for the duration of
|
|
|
|
the current database session. When
|
|
|
|
the session ends, the prepared statement is forgotten, and so it must be
|
|
|
|
recreated before being used again. This also means that a single
|
|
|
|
prepared statement cannot be used by multiple simultaneous database
|
|
|
|
clients; however, each client can create their own prepared statement
|
2002-08-27 06:55:12 +02:00
|
|
|
to use.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-27 01:56:51 +02:00
|
|
|
Prepared statements have the largest performance advantage when a
|
|
|
|
single session is being used to execute a large number of similar
|
|
|
|
statements. The performance difference will be particularly
|
|
|
|
significant if the statements are complex to plan or rewrite, for
|
2002-08-27 06:55:12 +02:00
|
|
|
example, if the query involves a join of many tables or requires
|
2003-04-27 01:56:51 +02:00
|
|
|
the application of several rules. If the statement is relatively simple
|
2002-08-27 06:55:12 +02:00
|
|
|
to plan and rewrite but relatively expensive to execute, the
|
2003-04-27 01:56:51 +02:00
|
|
|
performance advantage of prepared statements will be less noticeable.
|
2002-08-27 06:55:12 +02:00
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
</refsect1>
|
2002-08-27 06:55:12 +02:00
|
|
|
|
2003-04-27 01:56:51 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="PARAMETER">plan_name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
An arbitrary name given to this particular prepared
|
|
|
|
statement. It must be unique within a single session and is
|
|
|
|
subsequently used to execute or deallocate a previously prepared
|
|
|
|
statement.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="PARAMETER">datatype</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The data type of a parameter to the prepared statement. To
|
|
|
|
refer to the parameters in the prepared statement itself, use
|
|
|
|
<literal>$1</literal>, <literal>$2</literal>, etc.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="PARAMETER">statement</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>,
|
|
|
|
or <command>DELETE</> statement.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
2002-08-27 06:55:12 +02:00
|
|
|
</refsect1>
|
|
|
|
|
2003-04-27 01:56:51 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Diagnostics</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><computeroutput>PREPARE</computeroutput></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Message returned if the statement has been prepared successfully.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In some situations, the query plan produced by for a prepared
|
|
|
|
statement may be inferior to the plan produced if the statement
|
|
|
|
were submitted and executed normally. This is because when the
|
2003-08-17 06:46:59 +02:00
|
|
|
statement is planned and the planner attempts to determine the
|
2003-04-27 01:56:51 +02:00
|
|
|
optimal query plan, the actual values of any parameters specified
|
|
|
|
in the statement are
|
|
|
|
unavailable. <productname>PostgreSQL</productname> collects
|
|
|
|
statistics on the distribution of data in the table, and can use
|
|
|
|
constant values in a statement to make guesses about the likely
|
|
|
|
result of executing the statement. Since this data is unavailable
|
|
|
|
when planning prepared statements with parameters, the chosen plan
|
|
|
|
may be suboptimal. To examine the query plan
|
|
|
|
<productname>PostgreSQL</productname> has chosen for a prepared
|
|
|
|
statement, use <command>EXPLAIN EXECUTE</command>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For more information on query planning and the statistics collected
|
|
|
|
by <productname>PostgreSQL</productname> for that purpose, see
|
|
|
|
the <xref linkend="sql-analyze" endterm="sql-analyze-title">
|
|
|
|
documentation.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The SQL standard includes a <command>PREPARE</command> statement,
|
|
|
|
but it is only for use in embedded SQL. This version of the
|
|
|
|
<command>PREPARE</command> statement also uses a somewhat different
|
|
|
|
syntax.
|
|
|
|
</para>
|
2002-08-27 06:55:12 +02:00
|
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
|
|
Local variables:
|
|
|
|
mode: sgml
|
|
|
|
sgml-omittag:nil
|
|
|
|
sgml-shorttag:t
|
|
|
|
sgml-minimize-attributes:nil
|
|
|
|
sgml-always-quote-attributes:t
|
|
|
|
sgml-indent-step:1
|
|
|
|
sgml-indent-data:t
|
|
|
|
sgml-parent-document:nil
|
|
|
|
sgml-default-dtd-file:"../reference.ced"
|
|
|
|
sgml-exposed-tags:nil
|
|
|
|
sgml-local-catalogs:"/usr/lib/sgml/catalog"
|
|
|
|
sgml-local-ecat-files:nil
|
|
|
|
End:
|
|
|
|
-->
|