From: Tom Lane Date: Mon, 14 Jan 2008 18:46:40 +0000 (+0000) Subject: Fix an ancient oversight in libpq's handling of V3-protocol COPY OUT mode: X-Git-Url: http://waps.l3s.uni-hannover.de/gitweb/?a=commitdiff_plain;h=47141c5b5834ccd06714f84dae64bd48a0f48615;p=users%2Fbernd%2Fpostgres.git Fix an ancient oversight in libpq's handling of V3-protocol COPY OUT mode: we need to be able to swallow NOTICE messages, and potentially also ParameterStatus messages (although the latter would be a bit weird), without exiting COPY OUT state. Fix it, and adjust the protocol documentation to emphasize the need for this. Per off-list report from Alexander Galler. --- diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 74a9aca446..4f76a6c23b 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -210,7 +210,7 @@ - Start-Up + Start-Up To begin a session, a frontend opens a connection to the server and sends @@ -265,7 +265,7 @@ - AuthenticationKerberosV4 + AuthenticationKerberosV4 The frontend must now take part in a Kerberos V4 @@ -278,60 +278,60 @@ - AuthenticationKerberosV5 - - + AuthenticationKerberosV5 + + The frontend must now take part in a Kerberos V5 authentication dialog (not described here, part of the Kerberos specification) with the server. If this is successful, the server responds with an AuthenticationOk, otherwise it responds with an ErrorResponse. - - - - - - AuthenticationCleartextPassword - - + + + + + + AuthenticationCleartextPassword + + The frontend must now send a PasswordMessage containing the password in clear-text form. If this is the correct password, the server responds with an AuthenticationOk, otherwise it responds with an ErrorResponse. - - - - - - AuthenticationCryptPassword - - + + + + + + AuthenticationCryptPassword + + The frontend must now send a PasswordMessage containing the password encrypted via crypt(3), using the 2-character salt specified in the AuthenticationCryptPassword message. If this is the correct password, the server responds with an AuthenticationOk, otherwise it responds with an ErrorResponse. - - - - - - AuthenticationMD5Password - - + + + + + + AuthenticationMD5Password + + The frontend must now send a PasswordMessage containing the password encrypted via MD5, using the 4-character salt specified in the AuthenticationMD5Password message. If this is the correct password, the server responds with an AuthenticationOk, otherwise it responds with an ErrorResponse. - - - - - - AuthenticationSCMCredential - - + + + + + + AuthenticationSCMCredential + + This response is only possible for local Unix-domain connections on platforms that support SCM credential messages. The frontend must issue an SCM credential message and then send a single data @@ -340,12 +340,12 @@ the credential message.) If the credential is acceptable, the server responds with an AuthenticationOk, otherwise it responds with an ErrorResponse. - - - + + + - - + + If the frontend does not support the authentication method @@ -372,23 +372,23 @@ The possible messages from the backend in this phase are: - - - BackendKeyData - - + + + BackendKeyData + + This message provides secret-key data that the frontend must save if it wants to be able to issue cancel requests later. The frontend should not respond to this message, but should continue listening for a ReadyForQuery message. - - - - - - ParameterStatus - - + + + + + + ParameterStatus + + This message informs the frontend about the current (initial) setting of backend parameters, such as or . @@ -397,41 +397,41 @@ more details. The frontend should not respond to this message, but should continue listening for a ReadyForQuery message. - - - - - - ReadyForQuery - - + + + + + + ReadyForQuery + + Start-up is completed. The frontend may now issue commands. - - - - - - ErrorResponse - - + + + + + + ErrorResponse + + Start-up failed. The connection is closed after sending this message. - - - - - - NoticeResponse - - + + + + + + NoticeResponse + + A warning message has been issued. The frontend should display the message but continue listening for ReadyForQuery or ErrorResponse. - - - - - + + + + + The ReadyForQuery message is the same one that the backend will @@ -442,10 +442,10 @@ - - Simple Query + + Simple Query - + A simple query cycle is initiated by the frontend sending a Query message to the backend. The message includes an SQL command (or commands) expressed as a text string. @@ -459,109 +459,109 @@ command fails and already-issued later commands succeed.) - + The possible response messages from the backend are: - - - CommandComplete - - + + + CommandComplete + + An SQL command completed normally. - - - - - - CopyInResponse - - + + + + + + CopyInResponse + + The backend is ready to copy data from the frontend to a table; see . - - - - - - CopyOutResponse - - + + + + + + CopyOutResponse + + The backend is ready to copy data from a table to the frontend; see . - - - - - - RowDescription - - + + + + + + RowDescription + + Indicates that rows are about to be returned in response to a SELECT, FETCH, etc query. The contents of this message describe the column layout of the rows. This will be followed by a DataRow message for each row being returned to the frontend. - - - - - - DataRow - - + + + + + + DataRow + + One of the set of rows returned by a SELECT, FETCH, etc query. - - - - - - EmptyQueryResponse - - + + + + + + EmptyQueryResponse + + An empty query string was recognized. - - - - - - ErrorResponse - - + + + + + + ErrorResponse + + An error has occurred. - - - - - - ReadyForQuery - - + + + + + + ReadyForQuery + + Processing of the query string is complete. A separate message is sent to indicate this because the query string may contain multiple SQL commands. (CommandComplete marks the end of processing one SQL command, not the whole string.) ReadyForQuery will always be sent, whether processing terminates successfully or with an error. - - - - - - NoticeResponse - - + + + + + + NoticeResponse + + A warning message has been issued in relation to the query. Notices are in addition to other responses, i.e., the backend will continue processing the command. - - - + + + - - + + - + The response to a SELECT query (or other queries that return row sets, such as EXPLAIN or SHOW) normally consists of RowDescription, zero or more @@ -570,28 +570,28 @@ as described in . All other query types normally produce only a CommandComplete 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. - + - + 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. - + In simple Query mode, the format of retrieved values is always text, @@ -615,8 +615,8 @@ - - Extended Query + + Extended Query The extended query protocol breaks down the above-described simple @@ -854,8 +854,8 @@ - - Function Call + + Function Call The Function Call sub-protocol allows the client to request a direct @@ -885,51 +885,51 @@ The possible response messages from the backend are: - - - ErrorResponse - - + + + ErrorResponse + + An error has occurred. - - - - - - FunctionCallResponse - - + + + + + + FunctionCallResponse + + The function call was completed and returned the result given in the message. (Note that the Function Call protocol can only handle a single scalar result, not a row type or set of results.) - - - - - - ReadyForQuery - - + + + + + + ReadyForQuery + + Processing of the function call is complete. ReadyForQuery will always be sent, whether processing terminates successfully or with an error. - - - - - - NoticeResponse - - + + + + + + NoticeResponse + + A warning message has been issued in relation to the function call. Notices are in addition to other responses, i.e., the backend will continue processing the command. - - - - - + + + + + @@ -994,9 +994,16 @@ In the event of a backend-detected error during copy-out mode, the backend will issue an ErrorResponse message and revert to normal - processing. The frontend should treat receipt of ErrorResponse (or - indeed any message type other than CopyData or CopyDone) as terminating - the copy-out mode. + processing. The frontend should treat receipt of ErrorResponse as + terminating the copy-out mode. + + + + It is possible for NoticeResponse messages to be interspersed between + CopyData messages; frontends must handle this case, and should be + prepared for other asynchronous message types as well (see ). Otherwise, any message type other than + CopyData or CopyDone may be treated as terminating copy-out mode. @@ -1086,10 +1093,10 @@ - - Cancelling Requests in Progress + + Cancelling Requests in Progress - + During the processing of a query, the frontend may request cancellation of the query. The cancel request is not sent directly on the open connection to the backend for reasons of @@ -1100,7 +1107,7 @@ the normal case. - + To issue a cancel request, the frontend opens a new connection to the server and sends a CancelRequest message, rather than the StartupMessage message that would ordinarily be sent across a new @@ -1109,7 +1116,7 @@ the cancel request message. - + A CancelRequest message will be ignored unless it contains the same key data (PID and secret key) passed to the frontend during connection start-up. If the request matches the PID and secret @@ -1119,7 +1126,7 @@ processing the query.) - + The cancellation signal may or may not have any effect — for example, if it arrives after the backend has finished processing the query, then it will have no effect. If the cancellation is @@ -1127,7 +1134,7 @@ early with an error message. - + The upshot of all this is that for reasons of both security and efficiency, the frontend has no direct way to tell whether a cancel request has succeeded. It must continue to wait for the @@ -1137,7 +1144,7 @@ succeeding. - + Since the cancel request is sent across a new connection to the server and not across the regular frontend/backend communication link, it is possible for the cancel request to be issued by any @@ -1150,8 +1157,8 @@ - - Termination + + Termination The normal, graceful termination procedure is that the frontend @@ -1190,10 +1197,10 @@ - - <acronym>SSL</acronym> Session Encryption + + <acronym>SSL</acronym> Session Encryption - + If PostgreSQL was built with SSL support, frontend/backend communications can be encrypted using SSL. This provides @@ -1244,92 +1251,92 @@ - -Message Data Types + +Message Data Types - + This section describes the base data types used in messages. - + - - - Intn(i) - - - - An n-bit integer in network byte + + + Intn(i) + + + + An n-bit integer in network byte order (most significant byte first). - If i is specified it + If i is specified it is the exact value that will appear, otherwise the value is variable. Eg. Int16, Int32(42). - - - - - - - Intn[k] - - - - An array of k - n-bit integers, each in network - byte order. The array length k + + + + + + + Intn[k] + + + + An array of k + n-bit integers, each in network + byte order. The array length k is always determined by an earlier field in the message. Eg. Int16[M]. - - - - - - - String(s) - - - + + + + + + + String(s) + + + A null-terminated string (C-style string). There is no specific length limitation on strings. - If s is specified it is the exact + If s is specified it is the exact value that will appear, otherwise the value is variable. Eg. String, String("user"). - + - - -There is no predefined limit on the length of a string + + +There is no predefined limit on the length of a string that can be returned by the backend. Good coding strategy for a frontend is to use an expandable buffer so that anything that fits in memory can be accepted. If that's not feasible, read the full string and discard trailing characters that don't fit into your fixed-size buffer. - - - - - - - - Byten(c) - - - - Exactly n bytes. If the field - width n is not a constant, it is + + + + + + + + Byten(c) + + + + Exactly n bytes. If the field + width n is not a constant, it is always determinable from an earlier field in the message. - If c is specified it is the exact + If c is specified it is the exact value. Eg. Byte2, Byte1('\n'). - - - + + + - - + + - -Message Formats + +Message Formats - + This section describes the detailed format of each message. Each is marked to indicate that it may be sent by a frontend (F), a backend (B), or both (F & B). @@ -1340,454 +1347,454 @@ message is an exception, because it forms part of a data stream; the contents of any individual CopyData message may not be interpretable on their own.) - + - - + + AuthenticationOk (B) - - - + + + - - - + + + Byte1('R') - - - + + + Identifies the message as an authentication request. - - - - - + + + + + Int32(8) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(0) - - - + + + Specifies that the authentication was successful. - - - - + + + + - - - + + + - - + + AuthenticationKerberosV4 (B) - - - + + + - - - + + + Byte1('R') - - - + + + Identifies the message as an authentication request. - - - - - + + + + + Int32(8) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(1) - - - + + + Specifies that Kerberos V4 authentication is required. - - - - - - - + + + + + + + - - + + AuthenticationKerberosV5 (B) - - - + + + - - - + + + Byte1('R') - - - + + + Identifies the message as an authentication request. - - - - - + + + + + Int32(8) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(2) - - - + + + Specifies that Kerberos V5 authentication is required. - - - - - - - + + + + + + + - - + + AuthenticationCleartextPassword (B) - - - + + + - - - + + + Byte1('R') - - - + + + Identifies the message as an authentication request. - - - - - + + + + + Int32(8) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(3) - - - + + + Specifies that a clear-text password is required. - - - - - - - + + + + + + + - - + + AuthenticationCryptPassword (B) - - - + + + - - - + + + Byte1('R') - - - + + + Identifies the message as an authentication request. - - - - - + + + + + Int32(10) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(4) - - - + + + Specifies that a crypt()-encrypted password is required. - - - - - + + + + + Byte2 - - - + + + The salt to use when encrypting the password. - - - - + + + + - - - + + + - - + + AuthenticationMD5Password (B) - - - + + + - - - + + + Byte1('R') - - - + + + Identifies the message as an authentication request. - - - - - + + + + + Int32(12) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(5) - - - + + + Specifies that an MD5-encrypted password is required. - - - - - + + + + + Byte4 - - - + + + The salt to use when encrypting the password. - - - - + + + + - - - + + + - - + + AuthenticationSCMCredential (B) - - - + + + - - - + + + Byte1('R') - - - + + + Identifies the message as an authentication request. - - - - - + + + + + Int32(8) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(6) - - - + + + Specifies that an SCM credentials message is required. - - - - + + + + - - - + + + - - + + BackendKeyData (B) - - - + + + - - - + + + Byte1('K') - - - + + + Identifies the message as cancellation key data. The frontend must save these values if it wishes to be able to issue CancelRequest messages later. - - - - - + + + + + Int32(12) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32 - - - + + + The process ID of this backend. - - - - - + + + + + Int32 - - - + + + The secret key of this backend. - - - - + + + + - - - + + + - - + + Bind (F) - - - + + + - - - + + + Byte1('B') - - - + + + Identifies the message as a Bind command. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + String - - - + + + The name of the destination portal (an empty string selects the unnamed portal). - - - - - + + + + + String - - - + + + The name of the source prepared statement (an empty string selects the unnamed prepared statement). - - - - - + + + + + Int16 - - - + + + The number of parameter format codes that follow (denoted C below). This can be zero to indicate that there are no parameters @@ -1795,68 +1802,68 @@ Bind (F) or one, in which case the specified format code is applied to all parameters; or it can equal the actual number of parameters. - - - - - + + + + + Int16[C] - - - + + + The parameter format codes. Each must presently be zero (text) or one (binary). - - - - - + + + + + Int16 - - - + + + The number of parameter values that follow (possibly zero). This must match the number of parameters needed by the query. - - - - + + + + Next, the following pair of fields appear for each parameter: - - - + + + Int32 - - - + + + The length of the parameter value, in bytes (this count does not include itself). Can be zero. As a special case, -1 indicates a NULL parameter value. No value bytes follow in the NULL case. - - - - - - Byten - - - + + + + + + Byten + + + The value of the parameter, in the format indicated by the associated format code. - n is the above length. - - - - + n is the above length. + + + + After the last parameter, the following fields appear: - - - + + + Int16 - - - + + + The number of result-column format codes that follow (denoted R below). This can be zero to indicate that there are no result columns @@ -1865,271 +1872,271 @@ Bind (F) or one, in which case the specified format code is applied to all result columns (if any); or it can equal the actual number of result columns of the query. - - - - - + + + + + Int16[R] - - - + + + The result-column format codes. Each must presently be zero (text) or one (binary). - - - - - - - + + + + + + + - - + + BindComplete (B) - - - + + + - - - + + + Byte1('2') - - - + + + Identifies the message as a Bind-complete indicator. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + CancelRequest (F) - - - + + + - - - + + + Int32(16) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(80877102) - - - + + + The cancel request code. The value is chosen to contain 1234 in the most significant 16 bits, and 5678 in the least 16 significant bits. (To avoid confusion, this code must not be the same as any protocol version number.) - - - - - + + + + + Int32 - - - + + + The process ID of the target backend. - - - - - + + + + + Int32 - - - + + + The secret key for the target backend. - - - - + + + + - - - + + + - - + + Close (F) - - - + + + - - - + + + Byte1('C') - - - + + + Identifies the message as a Close command. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Byte1 - - - + + + 'S' to close a prepared statement; or 'P' to close a portal. - - - - - + + + + + String - - - + + + The name of the prepared statement or portal to close (an empty string selects the unnamed prepared statement or portal). - - - - - - - + + + + + + + - - + + CloseComplete (B) - - - + + + - - - + + + Byte1('3') - - - + + + Identifies the message as a Close-complete indicator. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + CommandComplete (B) - - - + + + - - - + + + Byte1('C') - - - + + + Identifies the message as a command-completed response. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + String - - - + + + 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. oid is the object ID - of the inserted row if rows is 1 + of the inserted row if rows is 1 and the target table has OIDs; - otherwise oid is 0. - + otherwise oid is 0. + - + For a DELETE command, the tag is - DELETE rows where - rows is the number of rows deleted. - + 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. - + UPDATE rows where + rows is the number of rows updated. + For a MOVE command, the tag is @@ -2143,178 +2150,178 @@ CommandComplete (B) FETCH rows where rows is the number of rows that have been retrieved from the cursor. - - - - + + + + - - - + + + - - + + CopyData (F & B) - - - - - - + + + + + + Byte1('d') - - - + + + Identifies the message as COPY data. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - - Byten - - - + + + + + + Byten + + + Data that forms part of a COPY data stream. Messages sent from the backend will always correspond to single data rows, but messages sent by frontends may divide the data stream arbitrarily. - - - - - - - + + + + + + + - - + + CopyDone (F & B) - - - + + + - - - + + + Byte1('c') - - - + + + Identifies the message as a COPY-complete indicator. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + CopyFail (F) - - - + + + - - - + + + Byte1('f') - - - + + + Identifies the message as a COPY-failure indicator. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + String - - - + + + An error message to report as the cause of failure. - - - - + + + + - - - + + + - - + + CopyInResponse (B) - - - + + + - - - + + + Byte1('G') - - - + + + Identifies the message as a Start Copy In response. The frontend must now send copy-in data (if not prepared to do so, send a CopyFail message). - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int8 - - - + + + 0 indicates the overall COPY format is textual (rows separated by newlines, columns separated by separator characters, etc). @@ -2322,317 +2329,317 @@ CopyInResponse (B) to DataRow format). See for more information. - - - - - + + + + + Int16 - - - + + + The number of columns in the data to be copied (denoted N below). - - - - - + + + + + Int16[N] - - - + + + The format codes to be used for each column. Each must presently be zero (text) or one (binary). All must be zero if the overall copy format is textual. - - - - + + + + - - - + + + - - + + CopyOutResponse (B) - - - + + + - - - + + + Byte1('H') - - - + + + Identifies the message as a Start Copy Out response. This message will be followed by copy-out data. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int8 - - - + + + 0 indicates the overall COPY format is textual (rows separated by newlines, columns separated by separator characters, etc). 1 indicates the overall copy format is binary (similar to DataRow format). See for more information. - - - - - + + + + + Int16 - - - + + + The number of columns in the data to be copied (denoted N below). - - - - - + + + + + Int16[N] - - - + + + The format codes to be used for each column. Each must presently be zero (text) or one (binary). All must be zero if the overall copy format is textual. - - - - + + + + - - - + + + - - + + DataRow (B) - - - - - - + + + + + + Byte1('D') - - - + + + Identifies the message as a data row. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int16 - - - + + + The number of column values that follow (possibly zero). - - - - + + + + Next, the following pair of fields appear for each column: - - - + + + Int32 - - - + + + The length of the column value, in bytes (this count does not include itself). Can be zero. As a special case, -1 indicates a NULL column value. No value bytes follow in the NULL case. - - - - - - Byten - - - + + + + + + Byten + + + The value of the column, in the format indicated by the associated format code. - n is the above length. - - - - + n is the above length. + + + + - - - + + + - - + + Describe (F) - - - + + + - - - + + + Byte1('D') - - - + + + Identifies the message as a Describe command. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Byte1 - - - + + + 'S' to describe a prepared statement; or 'P' to describe a portal. - - - - - + + + + + String - - - + + + The name of the prepared statement or portal to describe (an empty string selects the unnamed prepared statement or portal). - - - - - - - + + + + + + + - - + + EmptyQueryResponse (B) - - - + + + - - - + + + Byte1('I') - - - + + + Identifies the message as a response to an empty query string. (This substitutes for CommandComplete.) - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + ErrorResponse (B) - - - + + + - - - + + + Byte1('E') - - - + + + Identifies the message as an error. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - + + + + The message body consists of one or more identified fields, followed by a zero byte as a terminator. Fields may appear in any order. For each field there is the following: - - - + + + Byte1 - - - + + + A code identifying the field type; if zero, this is the message terminator and no string follows. The presently defined field types are listed in @@ -2640,162 +2647,162 @@ ErrorResponse (B) Since more field types may be added in future, frontends should silently ignore fields of unrecognized type. - - - - - + + + + + String - - - + + + The field value. - - - - + + + + - - - + + + - - + + Execute (F) - - - + + + - - - + + + Byte1('E') - - - + + + Identifies the message as an Execute command. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + String - - - + + + The name of the portal to execute (an empty string selects the unnamed portal). - - - - - + + + + + Int32 - - - + + + Maximum number of rows to return, if portal contains a query that returns rows (ignored otherwise). Zero denotes no limit. - - - - - - - + + + + + + + - - + + Flush (F) - - - + + + - - - + + + Byte1('H') - - - + + + Identifies the message as a Flush command. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + FunctionCall (F) - - - + + + - - - + + + Byte1('F') - - - + + + Identifies the message as a function call. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32 - - - + + + Specifies the object ID of the function to call. - - - - - + + + + + Int16 - - - + + + The number of argument format codes that follow (denoted C below). This can be zero to indicate that there are no arguments @@ -2803,214 +2810,214 @@ FunctionCall (F) or one, in which case the specified format code is applied to all arguments; or it can equal the actual number of arguments. - - - - - + + + + + Int16[C] - - - + + + The argument format codes. Each must presently be zero (text) or one (binary). - - - - - + + + + + Int16 - - - + + + Specifies the number of arguments being supplied to the function. - - - - + + + + Next, the following pair of fields appear for each argument: - - - + + + Int32 - - - + + + The length of the argument value, in bytes (this count does not include itself). Can be zero. As a special case, -1 indicates a NULL argument value. No value bytes follow in the NULL case. - - - - - - Byten - - - + + + + + + Byten + + + The value of the argument, in the format indicated by the associated format code. - n is the above length. - - - - + n is the above length. + + + + After the last argument, the following field appears: - - - + + + Int16 - - - + + + The format code for the function result. Must presently be zero (text) or one (binary). - - - - + + + + - - - + + + - - + + FunctionCallResponse (B) - - - + + + - - - + + + Byte1('V') - - - + + + Identifies the message as a function call result. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32 - - - + + + The length of the function result value, in bytes (this count does not include itself). Can be zero. As a special case, -1 indicates a NULL function result. No value bytes follow in the NULL case. - - - - - - Byten - - - + + + + + + Byten + + + The value of the function result, in the format indicated by the associated format code. - n is the above length. - - - - + n is the above length. + + + + - - - + + + - - + + NoData (B) - - - + + + - - - + + + Byte1('n') - - - + + + Identifies the message as a no-data indicator. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + NoticeResponse (B) - - - + + + - - - + + + Byte1('N') - - - + + + Identifies the message as a notice. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - + + + + The message body consists of one or more identified fields, followed by a zero byte as a terminator. Fields may appear in any order. For each field there is the following: - - - + + + Byte1 - - - + + + A code identifying the field type; if zero, this is the message terminator and no string follows. The presently defined field types are listed in @@ -3018,848 +3025,848 @@ NoticeResponse (B) Since more field types may be added in future, frontends should silently ignore fields of unrecognized type. - - - - - + + + + + String - - - + + + The field value. - - - - + + + + - - - + + + - - + + NotificationResponse (B) - - - + + + - - - + + + Byte1('A') - - - + + + Identifies the message as a notification response. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32 - - - + + + The process ID of the notifying backend process. - - - - - + + + + + String - - - + + + The name of the condition that the notify has been raised on. - - - - - + + + + + String - - - + + + Additional information passed from the notifying process. (Currently, this feature is unimplemented so the field is always an empty string.) - - - - + + + + - - - + + + - - + + ParameterDescription (B) - - - + + + - - - + + + Byte1('t') - - - + + + Identifies the message as a parameter description. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int16 - - - + + + The number of parameters used by the statement (may be zero). - - - - + + + + Then, for each parameter, there is the following: - - - + + + Int32 - - - + + + Specifies the object ID of the parameter data type. - - - - - - - + + + + + + + - - + + ParameterStatus (B) - - - + + + - - - + + + Byte1('S') - - - + + + Identifies the message as a run-time parameter status report. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + String - - - + + + The name of the run-time parameter being reported. - - - - - + + + + + String - - - + + + The current value of the parameter. - - - - - - - + + + + + + + - - + + Parse (F) - - - + + + - - - + + + Byte1('P') - - - + + + Identifies the message as a Parse command. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + String - - - + + + The name of the destination prepared statement (an empty string selects the unnamed prepared statement). - - - - - + + + + + String - - - + + + The query string to be parsed. - - - - - + + + + + Int16 - - - + + + The number of parameter data types specified (may be zero). Note that this is not an indication of the number of parameters that might appear in the query string, only the number that the frontend wants to prespecify types for. - - - - + + + + Then, for each parameter, there is the following: - - - + + + Int32 - - - + + + Specifies the object ID of the parameter data type. Placing a zero here is equivalent to leaving the type unspecified. - - - - - - - + + + + + + + - - + + ParseComplete (B) - - - + + + - - - + + + Byte1('1') - - - + + + Identifies the message as a Parse-complete indicator. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + PasswordMessage (F) - - - + + + - - - + + + Byte1('p') - - - + + + Identifies the message as a password response. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + String - - - + + + The password (encrypted, if requested). - - - - - - - + + + + + + + - - + + PortalSuspended (B) - - - + + + - - - + + + Byte1('s') - - - + + + Identifies the message as a portal-suspended indicator. Note this only appears if an Execute message's row-count limit was reached. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + Query (F) - - - + + + - - - + + + Byte1('Q') - - - + + + Identifies the message as a simple query. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + String - - - + + + The query string itself. - - - - + + + + - - - + + + - - + + ReadyForQuery (B) - - - + + + - - - + + + Byte1('Z') - - - + + + Identifies the message type. ReadyForQuery is sent whenever the backend is ready for a new query cycle. - - - - - + + + + + Int32(5) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Byte1 - - - + + + Current backend transaction status indicator. Possible values are 'I' if idle (not in a transaction block); 'T' if in a transaction block; or 'E' if in a failed transaction block (queries will be rejected until block is ended). - - - - + + + + - - - + + + - - + + RowDescription (B) - - - + + + - - - + + + Byte1('T') - - - + + + Identifies the message as a row description. - - - - - + + + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int16 - - - + + + Specifies the number of fields in a row (may be zero). - - - - + + + + Then, for each field, there is the following: - - - + + + String - - - + + + The field name. - - - - - + + + + + Int32 - - - + + + If the field can be identified as a column of a specific table, the object ID of the table; otherwise zero. - - - - - + + + + + Int16 - - - + + + If the field can be identified as a column of a specific table, the attribute number of the column; otherwise zero. - - - - - + + + + + Int32 - - - + + + The object ID of the field's data type. - - - - - + + + + + Int16 - - - + + + The data type size (see pg_type.typlen). Note that negative values denote variable-width types. - - - - - + + + + + Int32 - - - + + + The type modifier (see pg_attribute.atttypmod). The meaning of the modifier is type-specific. - - - - - + + + + + Int16 - - - + + + The format code being used for the field. Currently will be zero (text) or one (binary). In a RowDescription returned from the statement variant of Describe, the format code is not yet known and will always be zero. - - - - + + + + - - - + + + - - + + SSLRequest (F) - - - + + + - - - + + + Int32(8) - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + 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.) - - - - + + + + - - - + + + - - + + StartupMessage (F) - - - + + + - - - + + + Int32 - - - + + + Length of message contents in bytes, including self. - - - - - + + + + + Int32(196608) - - - + + + The protocol version number. The most significant 16 bits are the major version number (3 for the protocol described here). The least significant 16 bits are the minor version number (0 for the protocol described here). - - - - + + + + The protocol version number is followed by one or more pairs of parameter name and value strings. A zero byte is required as a terminator after the last name/value pair. Parameters can appear in any order. user is required, others are optional. Each parameter is specified as: - - - + + + String - - - + + + The parameter name. Currently recognized names are: - - - + + + user - - - + + + The database user name to connect as. Required; there is no default. - - - - - + + + + + database - - - + + + The database to connect to. Defaults to the user name. - - - - - + + + + + options - - - + + + Command-line arguments for the backend. (This is deprecated in favor of setting individual run-time parameters.) - - - - + + + + In addition to the above, any run-time parameter that can be set at backend start time may be listed. Such settings will be applied during backend start (after parsing the command-line options if any). The values will act as session defaults. - - - - - + + + + + String - - - + + + The parameter value. - - - - + + + + - - - + + + - - + + Sync (F) - - - + + + - - - + + + Byte1('S') - - - + + + Identifies the message as a Sync command. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - - + + Terminate (F) - - - + + + - - - + + + Byte1('X') - - - + + + Identifies the message as a termination. - - - - - + + + + + Int32(4) - - - + + + Length of message contents in bytes, including self. - - - - + + + + - - - + + + - + - -Error and Notice Message Fields + +Error and Notice Message Fields This section describes the fields that may appear in ErrorResponse and @@ -3868,165 +3875,165 @@ token. Note that any given field type should appear at most once per message. - + - - + + S - - - + + + Severity: the field contents are ERROR, FATAL, or PANIC (in an error message), or WARNING, NOTICE, DEBUG, INFO, or LOG (in a notice message), or a localized translation of one of these. Always present. - - - + + + - - + + C - - - + + + Code: the SQLSTATE code for the error (see ). Not localizable. Always present. - - - + + + - - + + M - - - + + + Message: the primary human-readable error message. This should be accurate but terse (typically one line). Always present. - - - + + + - - + + D - - - + + + Detail: an optional secondary error message carrying more detail about the problem. May run to multiple lines. - - - + + + - - + + H - - - + + + Hint: an optional suggestion what to do about the problem. This is intended to differ from Detail in that it offers advice (potentially inappropriate) rather than hard facts. May run to multiple lines. - - - + + + - - + + P - - - + + + Position: the field value is a decimal ASCII integer, indicating an error cursor position as an index into the original query string. The first character has index 1, and positions are measured in characters not bytes. - - - + + + - - + + p - - - + + + Internal position: this is defined the same as the P field, but it is used when the cursor position refers to an internally generated command rather than the one submitted by the client. The q field will always appear when this field appears. - - - + + + - - + + q - - - + + + Internal query: the text of a failed internally-generated command. This could be, for example, a SQL query issued by a PL/pgSQL function. - - - + + + - - + + W - - - + + + Where: an indication of the context in which the error occurred. Presently this includes a call stack traceback of active procedural language functions and internally-generated queries. The trace is one entry per line, most recent first. - - - + + + - - + + F - - - + + + File: the file name of the source-code location where the error was reported. - - - + + + - - + + L - - - + + + Line: the line number of the source-code location where the error was reported. - - - + + + - - + + R - - - + + + Routine: the name of the source-code routine reporting the error. - - - + + + - + The client is responsible for formatting displayed information to meet its @@ -4038,8 +4045,8 @@ not line breaks. - -Summary of Changes since Protocol 2.0 + +Summary of Changes since Protocol 2.0 This section provides a quick checklist of changes, for the benefit of @@ -4143,4 +4150,4 @@ string parameter; this has been removed. - + diff --git a/src/interfaces/libpq/fe-protocol3.c b/src/interfaces/libpq/fe-protocol3.c index cbfb0b8a5d..15ca002926 100644 --- a/src/interfaces/libpq/fe-protocol3.c +++ b/src/interfaces/libpq/fe-protocol3.c @@ -902,16 +902,13 @@ getReadyForQuery(PGconn *conn) } /* - * PQgetCopyData - read a row of data from the backend during COPY OUT + * getCopyDataMessage - fetch next CopyData message, process async messages * - * If successful, sets *buffer to point to a malloc'd row of data, and - * returns row length (always > 0) as result. - * Returns 0 if no row available yet (only possible if async is true), - * -1 if end of copy (consult PQgetResult), or -2 if error (consult - * PQerrorMessage). + * Returns length word of CopyData message (> 0), or 0 if no complete + * message available, -1 if end of copy, -2 if error. */ -int -pqGetCopyData3(PGconn *conn, char **buffer, int async) +static int +getCopyDataMessage(PGconn *conn) { char id; int msgLength; @@ -926,22 +923,94 @@ pqGetCopyData3(PGconn *conn, char **buffer, int async) */ conn->inCursor = conn->inStart; if (pqGetc(&id, conn)) - goto nodata; + return 0; if (pqGetInt(&msgLength, 4, conn)) - goto nodata; + return 0; + if (msgLength < 4) + { + handleSyncLoss(conn, id, msgLength); + return -2; + } avail = conn->inEnd - conn->inCursor; if (avail < msgLength - 4) - goto nodata; + return 0; /* - * If it's anything except Copy Data, exit COPY_OUT mode and let - * caller read status with PQgetResult(). The normal case is that - * it's Copy Done, but we let parseInput read that. + * If it's a legitimate async message type, process it. (NOTIFY + * messages are not currently possible here, but we handle them for + * completeness. NOTICE is definitely possible, and ParameterStatus + * could probably be made to happen.) Otherwise, if it's anything + * except Copy Data, report end-of-copy. */ - if (id != 'd') + switch (id) { - conn->asyncStatus = PGASYNC_BUSY; - return -1; + case 'A': /* NOTIFY */ + if (getNotify(conn)) + return 0; + break; + case 'N': /* NOTICE */ + if (pqGetErrorNotice3(conn, false)) + return 0; + break; + case 'S': /* ParameterStatus */ + if (getParameterStatus(conn)) + return 0; + break; + case 'd': /* Copy Data, pass it back to caller */ + return msgLength; + default: /* treat as end of copy */ + return -1; + } + + /* Drop the processed message and loop around for another */ + conn->inStart = conn->inCursor; + } +} + +/* + * PQgetCopyData - read a row of data from the backend during COPY OUT + * + * If successful, sets *buffer to point to a malloc'd row of data, and + * returns row length (always > 0) as result. + * Returns 0 if no row available yet (only possible if async is true), + * -1 if end of copy (consult PQgetResult), or -2 if error (consult + * PQerrorMessage). + */ +int +pqGetCopyData3(PGconn *conn, char **buffer, int async) +{ + int msgLength; + + for (;;) + { + /* + * Collect the next input message. To make life simpler for async + * callers, we keep returning 0 until the next message is fully + * available, even if it is not Copy Data. + */ + msgLength = getCopyDataMessage(conn); + if (msgLength < 0) + { + /* + * On end-of-copy, exit COPY_OUT mode and let caller read status + * with PQgetResult(). The normal case is that it's Copy Done, + * but we let parseInput read that. If error, we expect the + * state was already changed. + */ + if (msgLength == -1) + conn->asyncStatus = PGASYNC_BUSY; + return msgLength; /* end-of-copy or error */ + } + if (msgLength == 0) + { + /* Don't block if async read requested */ + if (async) + return 0; + /* Need to load more data */ + if (pqWait(TRUE, FALSE, conn) || + pqReadData(conn) < 0) + return -2; + continue; } /* @@ -969,16 +1038,6 @@ pqGetCopyData3(PGconn *conn, char **buffer, int async) /* Empty, so drop it and loop around for another */ conn->inStart = conn->inCursor; - continue; - -nodata: - /* Don't block if async read requested */ - if (async) - return 0; - /* Need to load more data */ - if (pqWait(TRUE, FALSE, conn) || - pqReadData(conn) < 0) - return -2; } } @@ -1041,7 +1100,6 @@ pqGetline3(PGconn *conn, char *s, int maxlen) int pqGetlineAsync3(PGconn *conn, char *buffer, int bufsize) { - char id; int msgLength; int avail; @@ -1054,21 +1112,11 @@ pqGetlineAsync3(PGconn *conn, char *buffer, int bufsize) * available even if it is not Copy Data. This should keep PQendcopy * from blocking. */ - conn->inCursor = conn->inStart; - if (pqGetc(&id, conn)) - return 0; - if (pqGetInt(&msgLength, 4, conn)) - return 0; - avail = conn->inEnd - conn->inCursor; - if (avail < msgLength - 4) - return 0; - - /* - * Cannot proceed unless it's a Copy Data message. Anything else - * means end of copy mode. - */ - if (id != 'd') - return -1; + msgLength = getCopyDataMessage(conn); + if (msgLength < 0) + return -1; /* end-of-copy or error */ + if (msgLength == 0) + return 0; /* no data yet */ /* * Move data from libpq's buffer to the caller's. In the case where a