Current File : //opt/alt/postgresql11/usr/share/man/man7/PREPARE.7
'\" t
.\" Title: PREPARE
.\" Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\" Date: 2017-11-06
.\" Manual: PostgreSQL 9.2.24 Documentation
.\" Source: PostgreSQL 9.2.24
.\" Language: English
.\"
.TH "PREPARE" "7" "2017-11-06" "PostgreSQL 9.2.24" "PostgreSQL 9.2.24 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
PREPARE \- prepare a statement for execution
.\" PREPARE
.\" prepared statements: creating
.SH "SYNOPSIS"
.sp
.nf
PREPARE \fIname\fR [ ( \fIdata_type\fR [, \&.\&.\&.] ) ] AS \fIstatement\fR
.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, analyzed, and rewritten\&. When an
\fBEXECUTE\fR
command is subsequently issued, the prepared statement is planned and executed\&. This division of labor avoids repetitive parse analysis work, while allowing the execution plan to depend on the specific parameter values supplied\&.
.PP
Prepared statements can take parameters: values that are substituted into the statement when it is executed\&. When creating the prepared statement, refer to parameters by position, using
$1,
$2, etc\&. A corresponding list of parameter data types can optionally be specified\&. When a parameter\*(Aqs data type is not specified or is declared as
unknown, 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
\fBEXECUTE\fR
statement\&. Refer to
\fBEXECUTE\fR(7)
for more information about that\&.
.PP
Prepared statements only last for the duration of the current database session\&. When the session ends, the prepared statement is 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\&. Prepared statements can be manually cleaned up using the
\fBDEALLOCATE\fR(7)
command\&.
.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"
.PP
\fIname\fR
.RS 4
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\&.
.RE
.PP
\fIdata_type\fR
.RS 4
The data type of a parameter to the prepared statement\&. If the data type of a particular parameter is unspecified or is specified as
unknown, it will be inferred from the context in which the parameter is used\&. To refer to the parameters in the prepared statement itself, use
$1,
$2, etc\&.
.RE
.PP
\fIstatement\fR
.RS 4
Any
\fBSELECT\fR,
\fBINSERT\fR,
\fBUPDATE\fR,
\fBDELETE\fR, or
\fBVALUES\fR
statement\&.
.RE
.SH "NOTES"
.PP
If a prepared statement is executed enough times, the server may eventually decide to save and re\-use a generic plan rather than re\-planning each time\&. This will occur immediately if the prepared statement has no parameters; otherwise it occurs only if the generic plan appears to be not much more expensive than a plan that depends on specific parameter values\&. Typically, a generic plan will be selected only if the query\*(Aqs performance is estimated to be fairly insensitive to the specific parameter values supplied\&.
.PP
To examine the query plan
PostgreSQL
is using for a prepared statement, use
\fBEXPLAIN\fR(7)\&. If a generic plan is in use, it will contain parameter symbols
$\fIn\fR, while a custom plan will have the current actual parameter values substituted into it\&.
.PP
For more information on query planning and the statistics collected by
PostgreSQL
for that purpose, see the
\fBANALYZE\fR(7)
documentation\&.
.PP
You can see all prepared statements available in the session by querying the
pg_prepared_statements
system view\&.
.SH "EXAMPLES"
.PP
Create a prepared statement for an
\fBINSERT\fR
statement, and then execute it:
.sp
.if n \{\
.RS 4
.\}
.nf
PREPARE fooplan (int, text, bool, numeric) AS
INSERT INTO foo VALUES($1, $2, $3, $4);
EXECUTE fooplan(1, \*(AqHunter Valley\*(Aq, \*(Aqt\*(Aq, 200\&.00);
.fi
.if n \{\
.RE
.\}
.PP
Create a prepared statement for a
\fBSELECT\fR
statement, and then execute it:
.sp
.if n \{\
.RS 4
.\}
.nf
PREPARE usrrptplan (int) AS
SELECT * FROM users u, logs l WHERE u\&.usrid=$1 AND u\&.usrid=l\&.usrid
AND l\&.date = $2;
EXECUTE usrrptplan(1, current_date);
.fi
.if n \{\
.RE
.\}
.sp
Note that the data type of the second parameter is not specified, so it is inferred from the context in which
$2
is used\&.
.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\&.
.SH "SEE ALSO"
\fBDEALLOCATE\fR(7), \fBEXECUTE\fR(7)
Mini Shell