--- /dev/null
+Date: Wed, 18 Feb 1998 19:44:52 +0000
+To: "Thomas G. Lockhart"
+Subject: [DOCS] Re: [HACKERS] Frontend/Backend Protocol
+
+1. Introduction
+
+This document describes V1.0 of the protocol used between PostgreSQL frontends
+and backends. It is a message based protocol running over TCP. V6.3 of
+PostgreSQL introduced version numbers into the protocol. This was done in such
+a way as to still allow connections from earlier versions of frontends, but
+this document does not cover the protocol used by those earlier versions.
+
+This document does not cover how different frontend interfaces may use the
+protocol to implement certain features, eg. the way in which libpq passes
+certain environment variables after the connection is established.
+
+
+2. Overview
+
+The three major components are the frontend (running on the client) and the
+postmaster and backend (running on the server). The postmaster and backend
+have different roles but may be implemented by the same executable.
+
+A frontend sends a startup packet to the postmaster. This includes the names
+of the user and the database the user wants to connect to. The postmaster then
+uses this, and the information in the pg_hba.conf(5) file to determine what
+further authentication information it requires the frontend to send (if any)
+and responds to the frontend accordingly.
+
+The frontend then sends any required authentication information. Once the
+postmaster validates this it responds to the frontend that it is authenticated
+and hands over to a backend.
+
+Subsequent communications are query and result packets exchanged between the
+frontend and the backend. The postmaster takes no further part in the
+communication.
+
+When the frontend wishes to disconnect it sends an appropriate packet and
+closes the connection without waiting for a response for the backend.
+
+Packets are sent as a data stream. The first byte determines what should be
+expected in the rest of the packet. The exception is packets send from a
+frontend to the postmaster, which comprise a packet length then the packet
+itself. The difference is historical.
+
+
+3. Protocol
+
+This section describes the message flow. There are four different types of
+flows depending on the state of the connection.
+
+3.1 Authentication
+
+The frontend sends a StartupPacket. The postmaster uses this and the contents
+of the pg_hba.conf(5) file to determine what authentication method the frontend
+must use. The postmaster then responds with one of the following messages.
+
+ ErrorResponse
+ The postmaster then immediately closes the connection.
+
+ AuthenticationOk
+ The postmaster then hands over to the backend. The postmaster
+ takes no further part in the communication.
+
+ AuthenticationKerberosV4
+ The frontend must then take part in a Kerberos V4
+ authentication dialog (not described here) with the postmaster.
+ If this is succesful, the postmaster responds with an
+ AuthenticationOk, otherwise it responds with an ErrorResponse.
+
+ AuthenticationKerberosV5
+ The frontend must then take part in a Kerberos V5
+ authentication dialog (not described here) with the postmaster.
+ If this is succesful, the postmaster responds with an
+ AuthenticationOk, otherwise it responds with an ErrorResponse.
+
+ AuthenticationUnencryptedPassword
+ The frontend must then send an UnencryptedPasswordPacket.
+ If this is the correct password, the postmaster responds with
+ an AuthenticationOk, otherwise it responds with an
+ ErrorResponse.
+
+ AuthenticationEncryptedPassword
+ The frontend must then send an EncryptedPasswordPacket.
+ If this is the correct password, the postmaster responds with
+ an AuthenticationOk, otherwise it responds with an
+ ErrorResponse.
+
+If the frontend does not support the authentication method requested by the
+postmaster, then it should immediately close the connection.
+
+3.2 Query
+
+The frontend sends a Query message to the backend. The response sent by the
+backend depends on the contents of the query. The possible responses are as
+follows.
+
+ CompletedResponse
+ The query completed normally.
+
+ CopyInResponse
+ The backend is ready to copy data from the frontend to a
+ relation. The frontend should then send a CopyDataRows
+ message. The backend will then respond with a
+ CompletedResponse message with a tag of "COPY".
+
+ CopyOutResponse
+ The backend is ready to copy data from a relation to the
+ frontend. It then sends a CopyDataRows message, and then a
+ CompletedResponse message with a tag of "COPY".
+
+ CursorResponse
+ The query was either an insert(l), delete(l), update(l),
+ fetch(l) or a select(l) 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.
+
+ For an insert(l) command, the backend then sends a
+ CompletedResponse message with a tag of "INSERT "
+ where is the number of rows inserted, and is the
+ object ID of the inserted row if is 1, otherwise
+ is 0.
+
+ For a delete(l) command, the backend then sends a
+ CompletedResponse message with a tag of "DELETE " where
+ is the number of rows deleted.
+
+ For an update(l) command, the backend then sends a
+ CompletedResponse message with a tag of "UPDATE " where
+ is the number of rows deleted.
+
+ For a fetch(l) or select(l) command, the backend sends a
+ RowDescription message. This is then followed by an AsciiRow
+ or BinaryRow message (depending on if 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".
+
+ EmptyQueryResponse
+ The query was empty.
+
+ ErrorResponse
+ An error has occured.
+
+ NoticeResponse
+ A warning message has been issued in relation to the query.
+ Notices are in addition to other responses, ie. the backend
+ will send another response message immediately afterwards.
+
+ NotificationResponse
+ A notify(l) command has been executed for a relation for
+ which a previous listen(l) command was executed. Notifications
+ are in addition to other responses, ie. the backend will send
+ another response message immediately afterwards.
+
+A frontend must be prepared to accept ErrorResponse and NoticeResponse
+messages whenever it is expecting any other type of message.
+
+3.3 Function Call
+
+The frontend sends a FunctionCall message to the backend. The response sent by
+the backend depends on the result of the function call. The possible responses
+are as follows.
+
+ ErrorResponse
+ An error has occured.
+
+ FunctionResultResponse
+ The function call was executed and returned a result.
+
+ FunctionVoidResponse
+ The function call was executed and returned no result.
+
+ NoticeResponse
+ A warning message has been issued in relation to the function
+ call. Notices are in addition to other responses, ie. the
+ backend will send another response message immediately
+ afterwards.
+
+A frontend must be prepared to accept ErrorResponse and NoticeResponse
+messages whenever it is expecting any other type of message.
+
+3.4 Termination
+
+The frontend sends a Terminate message and immediately closes the connection.
+On receipt of the message, the backend immediately closes the connection and
+terminates.
+
+
+4. Message Data Types
+
+This section describes the base data types used in messages.
+
+ Int(i)
+ An bit integer in network byte order. If i is specified it
+ is the literal value. Eg. Int16, Int32(42).
+
+ LimString(s)
+ A character array of exactly bytes interpreted as a '\0'
+ terminated string. The '\0' is omitted if there is
+ insufficient room. If s is specified it is the literal value.
+ Eg. LimString32, LimString64("user").
+
+ String(s)
+ A conventional C '\0' terminated string with no length
+ limitation. A frontend should always read the full string
+ even though it may have to discard characters if it's buffers
+ aren't big enough. If s is specified it is the literal value.
+ Eg. String, String("user").
+
+ Byte(c)
+ Exactly bytes. If c is specified it is the literal
+ value. Eg. Byte, Byte1('\n').
+
+
+5. Messages Formats
+
+This section describes the detailed format of each message. Each can be sent
+by either a frontend (F), a postmaster/backend (B), or both (F & B).
+
+AsciiRow (B)
+ Byte1('D')
+ Identifies the message, in the context in which it is sent (see
+ CopyInResponse), as an ASCII row.
+ Byte
+ A bit map with one bit for each field in the row. The 1st
+ field corresponds to bit 7 of the 1st byte, the 2nd field
+ corresponds to bit 6 of the 1st byte, the 8th field corresponds
+ to bit 0 of the 1st byte, the 9th field corresponds to bit 8 of
+ the 2nd byte, and so on. The bit is set if the value of the
+ corresponding field is not NULL.
+
+ Then, for each field, there is the following.
+ Int32
+ Specifies the size of the value of the field, including
+ this size.
+ Byte
+ Specifies the value of the field itself in ASCII
+ characters. is the above size minus 4.
+
+AuthenticationOk (B)
+ Byte1('R')
+ Identifies the message as an authentication request.
+ Int32(0)
+ Specifies that the authentication was succesful.
+
+AuthenticationKerberosV4 (B)
+ Byte1('R')
+ Identifies the message as an authentication request.
+ Int32(1)
+ Specifies that Kerberos V4 authentication is required.
+
+AuthenticationKerberosV5 (B)
+ Byte1('R')
+ Identifies the message as an authentication request.
+ Int32(2)
+ Specifies that Kerberos V5 authentication is required.
+
+AuthenticationUnencryptedPassword (B)
+ Byte1('R')
+ Identifies the message as an authentication request.
+ Int32(3)
+ Specifies that an unencrypted password is required.
+
+AuthenticationEncryptedPassword (B)
+ Byte1('R')
+ Identifies the message as an authentication request.
+ Int32(4)
+ Specifies that an encrypted password is required.
+ Byte2
+ The salt to use when encrypting the password.
+
+BinaryRow (B)
+ Byte1('B')
+ Identifies the message, in the context in which it is sent (see
+ CopyOutResponse), as a binary row.
+ Byte
+ A bit map with one bit for each field in the row. The 1st
+ field corresponds to bit 7 of the 1st byte, the 2nd field
+ corresponds to bit 6 of the 1st byte, the 8th field corresponds
+ to bit 0 of the 1st byte, the 9th field corresponds to bit 8 of
+ the 2nd byte, and so on. The bit is set if the value of the
+ corresponding field is not NULL.
+
+ Then, for each field, there is the following.
+ Int32
+ Specifies the size of the value of the field, excluding
+ this size.
+ Byte
+ Specifies the value of the field itself in binary
+ format. is the above size.
+
+CompletedResponse (B)
+ Byte1('C')
+ Identifies the message as a completed response.
+ String
+ The command tag. This is usually (but not always) a single
+ word that identifies which SQL command was completed.
+
+CopyDataRows (B & F)
+ This is a stream of rows where each row is terminated by a Char1('\n').
+ This is then followed by the sequence Char1('\\'), Char1('.'),
+ Char1('\n').
+
+CopyInResponse (B)
+ Byte1('D')
+ Identifies the message, in the context in which it is sent (see
+ AsciiRow), as a copy in started response.
+
+CopyOutResponse (B)
+ Byte1('B')
+ Identifies the message, in the context in which it is sent (see
+ BinaryRow), as a copy out started response.
+
+CursorResponse (B)
+ Byte1('P')
+ Identifies the message as a cursor response.
+ String
+ The name of the cursor. This will be "blank" if the cursor is
+ implicit.
+
+EmptyQueryResponse (B)
+ Byte1('I')
+ Identifies the message as an empty query response.
+ String("")
+ Unused.
+
+EncryptedPasswordPacket (F)
+ Int32
+ The size of the packet in bytes.
+ String
+ The encrypted (using crypt()) password.
+
+ErrorResponse (B)
+ Byte1('E')
+ Identifies the message as an error.
+ String
+ The error message itself.
+
+FunctionCall (F)
+ Byte1('F')
+ Identifies the message as a function call.
+ String("")
+ Unused.
+ Int32
+ Specifies the object ID of the function to call.
+ Int32
+ Specifies the number of arguments being supplied to the
+ function.
+
+ Then, for each argument, there is the following.
+ Int32
+ Specifies the size of the value of the argument,
+ excluding this size.
+ Byte
+ Specifies the value of the field itself in binary
+ format. is the above size.
+
+FunctionResultResponse (B)
+ Byte1('V')
+ Identifies the message as a function call result.
+ Byte1('G')
+ Specifies that an actual result was returned.
+ Int32
+ Specifies the size of the value of the result, excluding this
+ size.
+ Byte
+ Specifies the value of the result itself in binary format.
+ is the above size.
+ Byte1('0')
+ Unused. (Strictly speaking, FunctionResultResponse and
+ FunctionVoidResponse are the same thing but with some optional
+ parts to the message.)
+
+FunctionVoidResponse (B)
+ Byte1('V')
+ Identifies the message as a function call result.
+ Byte1('0')
+ Specifies that no actual result was returned.
+
+NoticeResponse (B)
+ Byte1('N')
+ Identifies the message as a notice.
+ String
+ The notice message itself.
+
+NotificationResponse (B)
+ Byte1('A')
+ Identifies the message as a notification response.
+ Int32
+ The process ID of the backend process.
+ String
+ The name of the relation that the notify has been raised on.
+
+Query (F)
+ Byte1('Q')
+ Identifies the message as query.
+ String
+ The query itself.
+
+RowDescription (B)
+ Byte1('T')
+ Identifies the message as a row description.
+ Int16
+ Specifies the number of fields in a row (and may be zero).
+
+ Then, for each field, there is the following.
+ String
+ Specifies the field name.
+ Int32
+ Specifies the object ID of the field type.
+ Int16
+ Specifies the type size.
+
+StartupPacket (F)
+ Int32(296)
+ The size of the packet in bytes.
+ Int32
+ The protocol version number. The most significant 16 bits are
+ the major version number. The least 16 significant bits are
+ the minor version number.
+ LimString64
+ The database name, defaults to the user name if omitted.
+ LimString32
+ The user name.
+ LimString64
+ Any additional command line arguments to be passed to the
+ backend by the postmaster.
+ LimString64
+ Unused.
+ LimString64
+ The optional tty the backend should use for debugging messages.
+
+Terminate (F)
+ Byte1('X')
+ Identifies the message as a termination.
+
+UnencryptedPasswordPacket (F)
+ Int32
+ The size of the packet in bytes.
+ String
+ The unencrypted password.
+
+--------------1B9BA35856C95E22453E911A--
projects / postgresql.git / commitdiff