From d036a699dc968e75e6a6cb11783931411cedab47 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Mon, 23 Feb 1998 13:10:53 +0000 Subject: [PATCH] Remind people of view permissions, and install libpq README. --- migration/6.2.1_to_6.3 | 5 + src/backend/libpq/README | 446 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 451 insertions(+) create mode 100644 src/backend/libpq/README diff --git a/migration/6.2.1_to_6.3 b/migration/6.2.1_to_6.3 index c29215c6e3..6e31f7d571 100644 --- a/migration/6.2.1_to_6.3 +++ b/migration/6.2.1_to_6.3 @@ -1,5 +1,10 @@ This migration requires a complete dump of the 6.2 or 6.2.1 database and a restore of the database in 6.3. +In addition, 6.3 has separate permissions for views, rather than relying +on the permissions set on the underlying tables. For this reason, you will +have to set permissions on your views if you want anything but the default +permissions. + Those migrating from earlier 1.* releases should first upgrade to 1.09 because the COPY output format was improved from the 1.02 release. diff --git a/src/backend/libpq/README b/src/backend/libpq/README new file mode 100644 index 0000000000..aa47082375 --- /dev/null +++ b/src/backend/libpq/README @@ -0,0 +1,446 @@ +Date: Wed, 18 Feb 1998 19:44:52 +0000 +From: Phil Thompson +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-- -- 2.40.0