2002-08-27 06:55:12 +02:00
|
|
|
<!--
|
2007-05-15 21:13:55 +02:00
|
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare.sgml,v 1.23 2007/05/15 19:13:55 neilc 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
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="sql-prepare">
|
|
|
|
<primary>PREPARE</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2004-09-30 06:23:27 +02:00
|
|
|
<indexterm zone="sql-prepare">
|
|
|
|
<primary>prepared statements</primary>
|
|
|
|
<secondary>creating</secondary>
|
|
|
|
</indexterm>
|
|
|
|
|
2002-08-27 06:55:12 +02:00
|
|
|
<refsynopsisdiv>
|
2003-04-27 01:56:51 +02:00
|
|
|
<synopsis>
|
2007-05-15 21:13:55 +02:00
|
|
|
PREPARE <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable class="PARAMETER">datatype</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">statement</replaceable>
|
2003-04-27 01:56:51 +02:00
|
|
|
</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
|
2006-01-15 23:18:47 +01:00
|
|
|
substituted into the statement when it is executed. When creating
|
|
|
|
the prepared statement, refer to parameters by position, using
|
|
|
|
<literal>$1</>, <literal>$2</>, etc. A corresponding list of
|
|
|
|
parameter data types can optionally be specified. When a
|
|
|
|
parameter's data type is not specified or is declared as
|
|
|
|
<literal>unknown</literal>, the type is inferred from the context
|
|
|
|
in which the parameter is used (if possible). When executing the
|
|
|
|
statement, specify the actual values for these parameters in the
|
|
|
|
<command>EXECUTE</command> statement. Refer to <xref
|
2003-04-27 01:56:51 +02:00
|
|
|
linkend="sql-execute" endterm="sql-execute-title"> for more
|
|
|
|
information about that.
|
2002-08-27 06:55:12 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-12-14 01:55:46 +01:00
|
|
|
Prepared statements only last for the duration of the current
|
2003-12-01 23:08:02 +01:00
|
|
|
database session. When the session ends, the prepared statement is
|
2004-04-20 01:36:48 +02:00
|
|
|
forgotten, 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 to use. The prepared statement can be
|
2005-10-15 03:47:12 +02:00
|
|
|
manually cleaned up using the <xref linkend="sql-deallocate"
|
|
|
|
endterm="sql-deallocate-title"> command.
|
2002-08-27 06:55:12 +02:00
|
|
|
</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>
|
2006-01-15 23:18:47 +01:00
|
|
|
<term><replaceable class="PARAMETER">name</replaceable></term>
|
2003-04-27 01:56:51 +02:00
|
|
|
<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>
|
2006-01-15 23:18:47 +01:00
|
|
|
The data type of a parameter to the prepared statement. If the
|
|
|
|
data type of a particular parameter is unspecified or is
|
|
|
|
specified as <literal>unknown</literal>, it will be inferred
|
|
|
|
from the context in which the parameter is used. To refer to the
|
|
|
|
parameters in the prepared statement itself, use
|
2003-04-27 01:56:51 +02:00
|
|
|
<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</>,
|
2006-09-18 21:54:01 +02:00
|
|
|
<command>DELETE</>, or <command>VALUES</> statement.
|
2003-04-27 01:56:51 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
2002-08-27 06:55:12 +02:00
|
|
|
</refsect1>
|
|
|
|
|
2003-04-27 01:56:51 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
2003-12-14 01:55:46 +01:00
|
|
|
In some situations, the query plan produced for a prepared
|
|
|
|
statement will be inferior to the query plan that would have been
|
|
|
|
chosen if the statement had been submitted and executed
|
|
|
|
normally. This is because when the statement is planned and the
|
|
|
|
planner attempts to determine the optimal query plan, the actual
|
|
|
|
values of any parameters specified in the statement are
|
2003-04-27 01:56:51 +02:00
|
|
|
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
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
might be suboptimal. To examine the query plan
|
2003-04-27 01:56:51 +02:00
|
|
|
<productname>PostgreSQL</productname> has chosen for a prepared
|
2004-09-20 02:04:19 +02:00
|
|
|
statement, use <xref linkend="sql-explain"
|
|
|
|
endterm="sql-explain-title">.
|
2003-04-27 01:56:51 +02:00
|
|
|
</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>
|
2006-01-08 08:00:27 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
You can see all available prepared statements of a session by querying the
|
2006-02-26 04:20:46 +01:00
|
|
|
<link linkend="view-pg-prepared-statements"><structname>pg_prepared_statements</structname></link>
|
|
|
|
system view.
|
2006-01-08 08:00:27 +01:00
|
|
|
</para>
|
2003-04-27 01:56:51 +02:00
|
|
|
</refsect1>
|
|
|
|
|
2004-01-26 18:26:31 +01:00
|
|
|
<refsect1 id="sql-prepare-examples">
|
|
|
|
<title id="sql-prepare-examples-title">Examples</title>
|
|
|
|
<para>
|
2006-01-15 23:18:47 +01:00
|
|
|
Create a prepared statement for an <command>INSERT</command>
|
|
|
|
statement, and then execute it:
|
2004-01-26 18:26:31 +01:00
|
|
|
<programlisting>
|
2004-10-29 21:40:33 +02:00
|
|
|
PREPARE fooplan (int, text, bool, numeric) AS
|
|
|
|
INSERT INTO foo VALUES($1, $2, $3, $4);
|
|
|
|
EXECUTE fooplan(1, 'Hunter Valley', 't', 200.00);
|
2004-01-26 18:26:31 +01:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2006-01-15 23:18:47 +01:00
|
|
|
Create a prepared statement for a <command>SELECT</command>
|
|
|
|
statement, and then execute it:
|
2004-01-26 18:26:31 +01:00
|
|
|
<programlisting>
|
2006-01-15 23:18:47 +01:00
|
|
|
PREPARE usrrptplan (int) AS
|
2004-01-26 18:26:31 +01:00
|
|
|
SELECT * FROM users u, logs l WHERE u.usrid=$1 AND u.usrid=l.usrid
|
|
|
|
AND l.date = $2;
|
|
|
|
EXECUTE usrrptplan(1, current_date);
|
|
|
|
</programlisting>
|
2006-01-15 23:18:47 +01:00
|
|
|
|
|
|
|
Note that the data type of the second parameter is not specified,
|
|
|
|
so it is inferred from the context in which <literal>$2</> is used.
|
2004-01-26 18:26:31 +01:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
2003-04-27 01:56:51 +02:00
|
|
|
<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>
|
2004-09-20 02:04:19 +02:00
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
|
|
|
<member><xref linkend="sql-deallocate" endterm="sql-deallocate-title"></member>
|
|
|
|
<member><xref linkend="sql-execute" endterm="sql-execute-title"></member>
|
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
2002-08-27 06:55:12 +02:00
|
|
|
</refentry>
|