begriffs open source - ai-pg/blob - full-docs/txt/sql-prepare.txt

   1
   2 PREPARE
   3
   4    PREPARE — prepare a statement for execution
   5
   6 Synopsis
   7
   8 PREPARE name [ ( data_type [, ...] ) ] AS statement
   9
  10 Description
  11
  12    PREPARE creates a prepared statement. A prepared statement is a
  13    server-side object that can be used to optimize performance. When the
  14    PREPARE statement is executed, the specified statement is parsed,
  15    analyzed, and rewritten. When an EXECUTE command is subsequently
  16    issued, the prepared statement is planned and executed. This division
  17    of labor avoids repetitive parse analysis work, while allowing the
  18    execution plan to depend on the specific parameter values supplied.
  19
  20    Prepared statements can take parameters: values that are substituted
  21    into the statement when it is executed. When creating the prepared
  22    statement, refer to parameters by position, using $1, $2, etc. A
  23    corresponding list of parameter data types can optionally be specified.
  24    When a parameter's data type is not specified or is declared as
  25    unknown, the type is inferred from the context in which the parameter
  26    is first referenced (if possible). When executing the statement,
  27    specify the actual values for these parameters in the EXECUTE
  28    statement. Refer to EXECUTE for more information about that.
  29
  30    Prepared statements only last for the duration of the current database
  31    session. When the session ends, the prepared statement is forgotten, so
  32    it must be recreated before being used again. This also means that a
  33    single prepared statement cannot be used by multiple simultaneous
  34    database clients; however, each client can create their own prepared
  35    statement to use. Prepared statements can be manually cleaned up using
  36    the DEALLOCATE command.
  37
  38    Prepared statements potentially have the largest performance advantage
  39    when a single session is being used to execute a large number of
  40    similar statements. The performance difference will be particularly
  41    significant if the statements are complex to plan or rewrite, e.g., if
  42    the query involves a join of many tables or requires the application of
  43    several rules. If the statement is relatively simple to plan and
  44    rewrite but relatively expensive to execute, the performance advantage
  45    of prepared statements will be less noticeable.
  46
  47 Parameters
  48
  49    name
  50           An arbitrary name given to this particular prepared statement.
  51           It must be unique within a single session and is subsequently
  52           used to execute or deallocate a previously prepared statement.
  53
  54    data_type
  55           The data type of a parameter to the prepared statement. If the
  56           data type of a particular parameter is unspecified or is
  57           specified as unknown, it will be inferred from the context in
  58           which the parameter is first referenced. To refer to the
  59           parameters in the prepared statement itself, use $1, $2, etc.
  60
  61    statement
  62           Any SELECT, INSERT, UPDATE, DELETE, MERGE, or VALUES statement.
  63
  64 Notes
  65
  66    A prepared statement can be executed with either a generic plan or a
  67    custom plan. A generic plan is the same across all executions, while a
  68    custom plan is generated for a specific execution using the parameter
  69    values given in that call. Use of a generic plan avoids planning
  70    overhead, but in some situations a custom plan will be much more
  71    efficient to execute because the planner can make use of knowledge of
  72    the parameter values. (Of course, if the prepared statement has no
  73    parameters, then this is moot and a generic plan is always used.)
  74
  75    By default (that is, when plan_cache_mode is set to auto), the server
  76    will automatically choose whether to use a generic or custom plan for a
  77    prepared statement that has parameters. The current rule for this is
  78    that the first five executions are done with custom plans and the
  79    average estimated cost of those plans is calculated. Then a generic
  80    plan is created and its estimated cost is compared to the average
  81    custom-plan cost. Subsequent executions use the generic plan if its
  82    cost is not so much higher than the average custom-plan cost as to make
  83    repeated replanning seem preferable.
  84
  85    This heuristic can be overridden, forcing the server to use either
  86    generic or custom plans, by setting plan_cache_mode to
  87    force_generic_plan or force_custom_plan respectively. This setting is
  88    primarily useful if the generic plan's cost estimate is badly off for
  89    some reason, allowing it to be chosen even though its actual cost is
  90    much more than that of a custom plan.
  91
  92    To examine the query plan PostgreSQL is using for a prepared statement,
  93    use EXPLAIN, for example
  94 EXPLAIN EXECUTE name(parameter_values);
  95
  96    If a generic plan is in use, it will contain parameter symbols $n,
  97    while a custom plan will have the supplied parameter values substituted
  98    into it.
  99
 100    For more information on query planning and the statistics collected by
 101    PostgreSQL for that purpose, see the ANALYZE documentation.
 102
 103    Although the main point of a prepared statement is to avoid repeated
 104    parse analysis and planning of the statement, PostgreSQL will force
 105    re-analysis and re-planning of the statement before using it whenever
 106    database objects used in the statement have undergone definitional
 107    (DDL) changes or their planner statistics have been updated since the
 108    previous use of the prepared statement. Also, if the value of
 109    search_path changes from one use to the next, the statement will be
 110    re-parsed using the new search_path. (This latter behavior is new as of
 111    PostgreSQL 9.3.) These rules make use of a prepared statement
 112    semantically almost equivalent to re-submitting the same query text
 113    over and over, but with a performance benefit if no object definitions
 114    are changed, especially if the best plan remains the same across uses.
 115    An example of a case where the semantic equivalence is not perfect is
 116    that if the statement refers to a table by an unqualified name, and
 117    then a new table of the same name is created in a schema appearing
 118    earlier in the search_path, no automatic re-parse will occur since no
 119    object used in the statement changed. However, if some other change
 120    forces a re-parse, the new table will be referenced in subsequent uses.
 121
 122    You can see all prepared statements available in the session by
 123    querying the pg_prepared_statements system view.
 124
 125 Examples
 126
 127    Create a prepared statement for an INSERT statement, and then execute
 128    it:
 129 PREPARE fooplan (int, text, bool, numeric) AS
 130     INSERT INTO foo VALUES($1, $2, $3, $4);
 131 EXECUTE fooplan(1, 'Hunter Valley', 't', 200.00);
 132
 133    Create a prepared statement for a SELECT statement, and then execute
 134    it:
 135 PREPARE usrrptplan (int) AS
 136     SELECT * FROM users u, logs l WHERE u.usrid=$1 AND u.usrid=l.usrid
 137     AND l.date = $2;
 138 EXECUTE usrrptplan(1, current_date);
 139
 140    In this example, the data type of the second parameter is not
 141    specified, so it is inferred from the context in which $2 is used.
 142
 143 Compatibility
 144
 145    The SQL standard includes a PREPARE statement, but it is only for use
 146    in embedded SQL. This version of the PREPARE statement also uses a
 147    somewhat different syntax.
 148
 149 See Also
 150
 151    DEALLOCATE, EXECUTE