diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 822b562843d..f8848a3fe42 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,4 +1,4 @@ - + Frontend/Backend Protocol @@ -38,7 +38,7 @@ A frontend opens a connection to the server and sends a start-up - packet. This includes the names of the user and the database the + packet. This includes the names of the user and of the database the user wants to connect to. The server then uses this, and the information in the pg_hba.conf file to determine what further authentication information it requires the @@ -53,19 +53,15 @@ - In order to serve multiple clients efficiently, the server would - normally create a new child process to handle each incoming - connection. However, this is not required. In the current - implementation, a new child process is created immediately after an - incoming connection is detected. In earlier versions of - PostgreSQL - (7.1 and earlier), the child process was created after sending the - authentication confirmation message. + In order to serve multiple clients efficiently, the server launches + a new backend process for each client. This is transparent + to the protocol, however. In the current implementation, a new child + process is created immediately after an incoming connection is detected. When the frontend wishes to disconnect it sends an appropriate packet and - closes the connection without waiting for a response for the backend. + closes the connection without waiting for a response from the backend. @@ -319,47 +315,26 @@ CursorResponse - The query was either an INSERT, - UPDATE, DELETE, - FETCH, or a SELECT - command. If the transaction has been aborted then the backend - sends a CompletedResponse message with a tag of *ABORT - STATE*. Otherwise the following responses are sent. + Beginning of the response to a SELECT, + FETCH, INSERT, + UPDATE, or DELETE + query. In the FETCH case the name of the + cursor being fetched from is included in the message. Otherwise + the message always mentions the blank cursor. + + + + RowDescription + - For an INSERT command, the backend then - sends a CompletedResponse message with a tag of - INSERT oid - rows, where - rows is the number of rows - inserted, and oid is the object ID - of the inserted row if rows is 1, - otherwise oid is 0. - - - - For a DELETE command, the backend then - sends a CompletedResponse message with a tag of DELETE - rows where - rows is the number of rows deleted. - - - - For an UPDATE command, the backend then - sends a CompletedResponse message with a tag of UPDATE - rows where - rows is the number of rows affected - by the update. - - - - For a FETCH or SELECT - command, the backend sends a RowDescription message. This is - then followed by an AsciiRow or BinaryRow message (depending - on whether a binary cursor was specified) for each row being - returned to the frontend. Finally, the backend sends a - CompletedResponse message with a tag of SELECT. + Indicates that rows are about to be returned in response to + a SELECT or FETCH query. + The message contents describe the layout of the rows. This + will be followed by an AsciiRow or BinaryRow message (depending on + whether a binary cursor was specified) for each row being returned + to the frontend. @@ -368,8 +343,7 @@ EmptyQueryResponse - An empty query string was recognized. (The need to specially - distinguish this case is historical.) + An empty query string was recognized. @@ -411,6 +385,41 @@ + + The response to a SELECT or FETCH query + normally consists of CursorResponse, RowDescription, zero or more + AsciiRow or BinaryRow messages, and finally CompletedResponse. + INSERT, UPDATE, and + DELETE queries produce CursorResponse followed by + CompletedResponse. + COPY to or from the frontend invokes special protocol + as mentioned above. + All other query types normally produce only + a CompletedResponse message. + + + + Since a query string could contain several queries (separated by + semicolons), there might be several such response sequences before the + backend finishes processing the query string. ReadyForQuery is issued + when the entire string has been processed and the backend is ready to + accept a new query string. + + + + If a completely empty (no contents other than whitespace) query string + is received, the response is EmptyQueryResponse followed by ReadyForQuery. + (The need to specially distinguish this case is historical.) + + + + In the event of an error, ErrorResponse is issued followed by + ReadyForQuery. All further processing of the query string is aborted by + ErrorResponse (even if more queries remained in it). Note that this + may occur partway through the sequence of messages generated by an + individual query. + + A frontend must be prepared to accept ErrorResponse and NoticeResponse messages whenever it is expecting any other type of @@ -428,10 +437,16 @@ - Also, if the frontend issues any LISTEN + Also, if the frontend issues any LISTEN commands then it must be prepared to accept NotificationResponse messages at any time; see below. + + + Recommended practice is to code frontends in a state-machine style + that will accept any message type at any time that it could make sense, + rather than wiring in assumptions about the exact sequence of messages. + @@ -504,7 +519,7 @@ A frontend must be prepared to accept ErrorResponse and NoticeResponse messages whenever it is expecting any other type of - message. Also, if it issues any LISTEN + message. Also, if it issues any LISTEN commands then it must be prepared to accept NotificationResponse messages at any time; see below. @@ -514,10 +529,10 @@ Notification Responses - If a frontend issues a LISTEN command, then the + If a frontend issues a LISTEN command, then the backend will send a NotificationResponse message (not to be confused with NoticeResponse!) whenever a - NOTIFY command is executed for the same + NOTIFY command is executed for the same notification name. @@ -534,8 +549,8 @@ NotificationResponse - A NOTIFY command has been executed for a - name for which a previous LISTEN command + A NOTIFY command has been executed for a + name for which a previous LISTEN command was executed. Notifications may be sent at any time. @@ -579,7 +594,7 @@ same key data (PID and secret key) passed to the frontend during connection start-up. If the request matches the PID and secret key for a currently executing backend, the processing of the - current query is aborted. (In the existing implemenation, this is + current query is aborted. (In the existing implementation, this is done by sending a special signal to the backend process that is processing the query.) @@ -633,6 +648,61 @@ by recontacting the server if it doesn't want to terminate itself. + + + For either normal or abnormal termination, any open transaction is + rolled back, not committed. One should note however that if a + frontend disconnects while a query is being processed, the backend + will probably finish the query before noticing the disconnection. + If the query is outside any transaction block (BEGIN + ... COMMIT sequence) then its results may be committed + before the disconnection is recognized. + + + + + SSL Session Encryption + + + Recent releases of PostgreSQL allow frontend/backend + communication to be encrypted using SSL. This provides communication + security in environments where attackers might be able to capture the + session traffic. + + + + To initiate an SSL-encrypted connection, the frontend initially sends + an SSLRequest message rather than a StartupPacket. The server then + responds with a single byte containing Y or N, + indicating that it is willing or unwilling to perform SSL, respectively. + The frontend may close the connection at this point if it is dissatisfied + with the response. To continue after Y, perform an SSL + startup handshake (not described here, part of the SSL specification) + with the server. If this is successful, continue with + sending the usual StartupPacket. In this case the StartupPacket and + all subsequent data will be SSL-encrypted. To continue after + N, send the usual StartupPacket and proceed without + encryption. + + + + The frontend should also be prepared to handle an ErrorMessage response + to SSLRequest from the server. This would only occur if the server + predates the addition of SSL support to PostgreSQL. + In this case the connection must be closed, but the frontend may choose + to open a fresh connection and proceed without requesting SSL. + + + + An initial SSLRequest may also be used in a connection that is being + opened to send a CancelRequest message. + + + + While the protocol itself does not provide a way for the server to + force SSL encryption, the administrator may configure the server to + reject unencrypted sessions as a byproduct of authentication checking. + @@ -1240,8 +1310,30 @@ CompletedResponse (B) - The command tag. This is usually (but not always) a single - word that identifies which SQL command was completed. + The command tag. This is usually a single + word that identifies which SQL command was completed. + + + + For an INSERT command, the tag is + INSERT oid + rows, where + rows is the number of rows + inserted, and oid is the object ID + of the inserted row if rows is 1, + otherwise oid is 0. + + + + For a DELETE command, the tag is + DELETE rows where + rows is the number of rows deleted. + + + + For an UPDATE command, the tag is + UPDATE rows where + rows is the number of rows updated. @@ -1853,6 +1945,44 @@ RowDescription (B) + + + +SSLRequest (F) + + + + + + + + Int32(8) + + + + The size of the packet in bytes. + + + + + + Int32(80877103) + + + + The SSL request code. The value is chosen to contain + 1234 in the most significant 16 bits, and 5679 in the + least 16 significant bits. (To avoid confusion, this code + must not be the same as any protocol version number.) + + + + + + + + + StartupPacket (F) @@ -1931,6 +2061,7 @@ StartupPacket (F) The optional tty the backend should use for debugging messages. + (Currently, this field is unsupported and ignored.)