.\\" auto-generated by docbook2man-spec $Revision: 1.1.1.1 $
.TH "PREPARE" "" "2007-09-16" "SQL - Language Statements" "SQL Commands"
.SH NAME
PREPARE \- prepare a statement for execution

.SH SYNOPSIS
.sp
.nf
PREPARE \fIplan_name\fR [ (\fIdatatype\fR [, ...] ) ] AS \fIstatement\fR
.sp
.fi
.SH "DESCRIPTION"
.PP
\fBPREPARE\fR creates a prepared statement. A prepared
statement is a server-side object that can be used to optimize
performance. When the \fBPREPARE\fR statement is
executed, the specified statement is parsed, rewritten, and
planned. When an \fBEXECUTE\fR command is subsequently
issued, the prepared statement need only be executed. Thus, the
parsing, rewriting, and planning stages are only performed once,
instead of every time the statement is executed.
.PP
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 \fBPREPARE\fR statement, and, in the statement to
be prepared itself, refer to the parameters by position using
$1, $2, etc. When executing
the statement, specify the actual values for these parameters in
the \fBEXECUTE\fR statement. Refer to EXECUTE [\fBexecute\fR(l)] for more
information about that.
.PP
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
to use.
.PP
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
example, if the query involves a join of many tables or requires
the application of several rules. If the statement is relatively simple
to plan and rewrite but relatively expensive to execute, the
performance advantage of prepared statements will be less noticeable.
.SH "PARAMETERS"
.TP
\fB\fIplan_name\fB\fR
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.
.TP
\fB\fIdatatype\fB\fR
The data type of a parameter to the prepared statement. To
refer to the parameters in the prepared statement itself, use
$1, $2, etc.
.TP
\fB\fIstatement\fB\fR
Any \fBSELECT\fR, \fBINSERT\fR, \fBUPDATE\fR,
or \fBDELETE\fR statement.
.SH "NOTES"
.PP
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
statement is planned and the planner attempts to determine the
optimal query plan, the actual values of any parameters specified
in the statement are
unavailable. PostgreSQL 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
PostgreSQL has chosen for a prepared
statement, use \fBEXPLAIN EXECUTE\fR.
.PP
For more information on query planning and the statistics collected
by PostgreSQL for that purpose, see
the ANALYZE [\fBanalyze\fR(l)]
documentation.
.SH "COMPATIBILITY"
.PP
The SQL standard includes a \fBPREPARE\fR statement,
but it is only for use in embedded SQL. This version of the
\fBPREPARE\fR statement also uses a somewhat different
syntax.
