|
- <?xml version="1.0" encoding="UTF-8" standalone="no"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>52.1. Overview</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="prev" href="protocol.html" title="Chapter 52. Frontend/Backend Protocol" /><link rel="next" href="protocol-flow.html" title="52.2. Message Flow" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">52.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol.html" title="Chapter 52. Frontend/Backend Protocol">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 52. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 52. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 12.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-flow.html" title="52.2. Message Flow">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="PROTOCOL-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">52.1. Overview</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-MESSAGE-CONCEPTS">52.1.1. Messaging Overview</a></span></dt><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-QUERY-CONCEPTS">52.1.2. Extended Query Overview</a></span></dt><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-FORMAT-CODES">52.1.3. Formats and Format Codes</a></span></dt></dl></div><p>
- The protocol has separate phases for startup and normal operation.
- In the startup phase, the frontend opens a connection to the server
- and authenticates itself to the satisfaction of the server. (This might
- involve a single message, or multiple messages depending on the
- authentication method being used.) If all goes well, the server then sends
- status information to the frontend, and finally enters normal operation.
- Except for the initial startup-request message, this part of the
- protocol is driven by the server.
- </p><p>
- During normal operation, the frontend sends queries and
- other commands to the backend, and the backend sends back query results
- and other responses. There are a few cases (such as <code class="command">NOTIFY</code>)
- wherein the
- backend will send unsolicited messages, but for the most part this portion
- of a session is driven by frontend requests.
- </p><p>
- Termination of the session is normally by frontend choice, but can be
- forced by the backend in certain cases. In any case, when the backend
- closes the connection, it will roll back any open (incomplete) transaction
- before exiting.
- </p><p>
- Within normal operation, SQL commands can be executed through either of
- two sub-protocols. In the <span class="quote">“<span class="quote">simple query</span>”</span> protocol, the frontend
- just sends a textual query string, which is parsed and immediately
- executed by the backend. In the <span class="quote">“<span class="quote">extended query</span>”</span> protocol,
- processing of queries is separated into multiple steps: parsing,
- binding of parameter values, and execution. This offers flexibility
- and performance benefits, at the cost of extra complexity.
- </p><p>
- Normal operation has additional sub-protocols for special operations
- such as <code class="command">COPY</code>.
- </p><div class="sect2" id="PROTOCOL-MESSAGE-CONCEPTS"><div class="titlepage"><div><div><h3 class="title">52.1.1. Messaging Overview</h3></div></div></div><p>
- All communication is through a stream of messages. The first byte of a
- message identifies the message type, and the next four bytes specify the
- length of the rest of the message (this length count includes itself, but
- not the message-type byte). The remaining contents of the message are
- determined by the message type. For historical reasons, the very first
- message sent by the client (the startup message) has no initial
- message-type byte.
- </p><p>
- To avoid losing synchronization with the message stream, both servers and
- clients typically read an entire message into a buffer (using the byte
- count) before attempting to process its contents. This allows easy
- recovery if an error is detected while processing the contents. In
- extreme situations (such as not having enough memory to buffer the
- message), the receiver can use the byte count to determine how much
- input to skip before it resumes reading messages.
- </p><p>
- Conversely, both servers and clients must take care never to send an
- incomplete message. This is commonly done by marshaling the entire message
- in a buffer before beginning to send it. If a communications failure
- occurs partway through sending or receiving a message, the only sensible
- response is to abandon the connection, since there is little hope of
- recovering message-boundary synchronization.
- </p></div><div class="sect2" id="PROTOCOL-QUERY-CONCEPTS"><div class="titlepage"><div><div><h3 class="title">52.1.2. Extended Query Overview</h3></div></div></div><p>
- In the extended-query protocol, execution of SQL commands is divided
- into multiple steps. The state retained between steps is represented
- by two types of objects: <em class="firstterm">prepared statements</em> and
- <em class="firstterm">portals</em>. A prepared statement represents the result of
- parsing and semantic analysis of a textual query string.
- A prepared statement is not in itself ready to execute, because it might
- lack specific values for <em class="firstterm">parameters</em>. A portal represents
- a ready-to-execute or already-partially-executed statement, with any
- missing parameter values filled in. (For <code class="command">SELECT</code> statements,
- a portal is equivalent to an open cursor, but we choose to use a different
- term since cursors don't handle non-<code class="command">SELECT</code> statements.)
- </p><p>
- The overall execution cycle consists of a <em class="firstterm">parse</em> step,
- which creates a prepared statement from a textual query string; a
- <em class="firstterm">bind</em> step, which creates a portal given a prepared
- statement and values for any needed parameters; and an
- <em class="firstterm">execute</em> step that runs a portal's query. In the case of
- a query that returns rows (<code class="command">SELECT</code>, <code class="command">SHOW</code>, etc),
- the execute step can be told to fetch only
- a limited number of rows, so that multiple execute steps might be needed
- to complete the operation.
- </p><p>
- The backend can keep track of multiple prepared statements and portals
- (but note that these exist only within a session, and are never shared
- across sessions). Existing prepared statements and portals are
- referenced by names assigned when they were created. In addition,
- an <span class="quote">“<span class="quote">unnamed</span>”</span> prepared statement and portal exist. Although these
- behave largely the same as named objects, operations on them are optimized
- for the case of executing a query only once and then discarding it,
- whereas operations on named objects are optimized on the expectation
- of multiple uses.
- </p></div><div class="sect2" id="PROTOCOL-FORMAT-CODES"><div class="titlepage"><div><div><h3 class="title">52.1.3. Formats and Format Codes</h3></div></div></div><p>
- Data of a particular data type might be transmitted in any of several
- different <em class="firstterm">formats</em>. As of <span class="productname">PostgreSQL</span> 7.4
- the only supported formats are <span class="quote">“<span class="quote">text</span>”</span> and <span class="quote">“<span class="quote">binary</span>”</span>,
- but the protocol makes provision for future extensions. The desired
- format for any value is specified by a <em class="firstterm">format code</em>.
- Clients can specify a format code for each transmitted parameter value
- and for each column of a query result. Text has format code zero,
- binary has format code one, and all other format codes are reserved
- for future definition.
- </p><p>
- The text representation of values is whatever strings are produced
- and accepted by the input/output conversion functions for the
- particular data type. In the transmitted representation, there is
- no trailing null character; the frontend must add one to received
- values if it wants to process them as C strings.
- (The text format does not allow embedded nulls, by the way.)
- </p><p>
- Binary representations for integers use network byte order (most
- significant byte first). For other data types consult the documentation
- or source code to learn about the binary representation. Keep in mind
- that binary representations for complex data types might change across
- server versions; the text format is usually the more portable choice.
- </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="protocol.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-flow.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 52. Frontend/Backend Protocol </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 52.2. Message Flow</td></tr></table></div></body></html>
|
