Home Explore Blog CI



postgresql

13th chunk of `doc/src/sgml/protocol.sgml`
452ff64235e3e9abd79a103f263cde40789cb01702c970f60000000100000fa0
 <para>
     A parameter data type can be left unspecified by setting it to zero,
     or by making the array of parameter type OIDs shorter than the
     number of parameter symbols (<literal>$</literal><replaceable>n</replaceable>)
     used in the query string.  Another special case is that a parameter's
     type can be specified as <type>void</type> (that is, the OID of the
     <type>void</type> pseudo-type).  This is meant to allow parameter symbols
     to be used for function parameters that are actually OUT parameters.
     Ordinarily there is no context in which a <type>void</type> parameter
     could be used, but if such a parameter symbol appears in a function's
     parameter list, it is effectively ignored.  For example, a function
     call such as <literal>foo($1,$2,$3,$4)</literal> could match a function with
     two IN and two OUT arguments, if <literal>$3</literal> and <literal>$4</literal>
     are specified as having type <type>void</type>.
    </para>
   </note>

   <note>
    <para>
     The query string contained in a Parse message cannot include more
     than one SQL statement; else a syntax error is reported.  This
     restriction does not exist in the simple-query protocol, but it
     does exist in the extended protocol, because allowing prepared
     statements or portals to contain multiple commands would complicate
     the protocol unduly.
    </para>
   </note>

   <para>
    If successfully created, a named prepared-statement object lasts till
    the end of the current session, unless explicitly destroyed.  An unnamed
    prepared statement lasts only until the next Parse statement specifying
    the unnamed statement as destination is issued.  (Note that a simple
    Query message also destroys the unnamed statement.)  Named prepared
    statements must be explicitly closed before they can be redefined by
    another Parse message, but this is not required for the unnamed statement.
    Named prepared statements can also be created and accessed at the SQL
    command level, using <command>PREPARE</command> and <command>EXECUTE</command>.
   </para>

   <para>
    Once a prepared statement exists, it can be readied for execution using a
    Bind message.  The Bind message gives the name of the source prepared
    statement (empty string denotes the unnamed prepared statement), the name
    of the destination portal (empty string denotes the unnamed portal), and
    the values to use for any parameter placeholders present in the prepared
    statement.  The
    supplied parameter set must match those needed by the prepared statement.
    (If you declared any <type>void</type> parameters in the Parse message,
    pass NULL values for them in the Bind message.)
    Bind also specifies the format to use for any data returned
    by the query; the format can be specified overall, or per-column.
    The response is either BindComplete or ErrorResponse.
   </para>

   <note>
    <para>
     The choice between text and binary output is determined by the format
     codes given in Bind, regardless of the SQL command involved.  The
     <literal>BINARY</literal> attribute in cursor declarations is irrelevant when
     using extended query protocol.
    </para>
   </note>

   <para>
    Query planning typically occurs when the Bind message is processed.
    If the prepared statement has no parameters, or is executed repeatedly,
    the server might save the created plan and re-use it during subsequent
    Bind messages for the same prepared statement.  However, it will do so
    only if it finds that a generic plan can be created that is not much
    less efficient than a plan that depends on the specific parameter values
    supplied.  This happens transparently so far as the protocol is concerned.
   </para>

   <para>
    If successfully created, a named portal object lasts till the end of the
    current transaction, unless explicitly destroyed.  An unnamed portal is
    destroyed at the end of

Title: Extended Query Protocol Details
Summary
The extended query protocol allows for prepared statements and portals to be created and managed, with features such as parameterized queries, separate data value supply, and query planning, which can improve efficiency and reduce errors, and includes rules for creating and managing named and unnamed prepared statements and portals, as well as binding parameters and specifying output formats.