diff options
Diffstat (limited to 'doc/src/sgml/html/protocol-overview.html')
| -rw-r--r-- | doc/src/sgml/html/protocol-overview.html | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/doc/src/sgml/html/protocol-overview.html b/doc/src/sgml/html/protocol-overview.html new file mode 100644 index 0000000..4c35fc3 --- /dev/null +++ b/doc/src/sgml/html/protocol-overview.html @@ -0,0 +1,112 @@ +<?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>55.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 Vsnapshot" /><link rel="prev" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol" /><link rel="next" href="protocol-flow.html" title="55.2. Message Flow" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">55.1. Overview</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><th width="60%" align="center">Chapter 55. Frontend/Backend Protocol</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="protocol-flow.html" title="55.2. Message Flow">Next</a></td></tr></table><hr /></div><div class="sect1" id="PROTOCOL-OVERVIEW"><div class="titlepage"><div><div><h2 class="title" style="clear: both">55.1. Overview</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-MESSAGE-CONCEPTS">55.1.1. Messaging Overview</a></span></dt><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-QUERY-CONCEPTS">55.1.2. Extended Query Overview</a></span></dt><dt><span class="sect2"><a href="protocol-overview.html#PROTOCOL-FORMAT-CODES">55.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">55.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">55.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">55.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" title="Chapter 55. Frontend/Backend Protocol">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="protocol.html" title="Chapter 55. Frontend/Backend Protocol">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-flow.html" title="55.2. Message Flow">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 55. Frontend/Backend Protocol </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 55.2. Message Flow</td></tr></table></div></body></html>
\ No newline at end of file |