X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=doc%2Fsrc%2Fsgml%2Fprotocol.sgml;h=73f26b432da0943ecbc9477fce139f9f832acca3;hb=048d148fe63102fafb2336ab5439c950dea7f692;hp=1ec079e41c865f0168aa172643a2510eb4088d42;hpb=59ed94ad0c9f74a3f057f359316c845cedc4461e;p=postgresql diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 1ec079e41c..73f26b432d 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1,4 +1,4 @@ - + Frontend/Backend Protocol @@ -28,12 +28,6 @@ if it is able. - - Higher level features built on this protocol (for example, how - libpq passes certain environment - variables when the connection is established) are covered elsewhere. - - In order to serve multiple clients efficiently, the server launches a new backend process for each client. @@ -354,7 +348,7 @@ This message contains the response data from the previous step of GSSAPI or SSPI negotiation (AuthenticationGSS, AuthenticationSSPI - or a previous AuthenticationGSSContinue). If the GSSAPI + or a previous AuthenticationGSSContinue). If the GSSAPI or SSPI data in this message indicates more data is needed to complete the authentication, the frontend must send that data as another PasswordMessage. If @@ -737,9 +731,9 @@ The unnamed prepared statement is likewise planned during Parse processing if the Parse message defines no parameters. But if there are parameters, - query planning occurs during Bind processing instead. This allows the - planner to make use of the actual values of the parameters provided in - the Bind message when planning the query. + query planning occurs every time Bind parameters are supplied. This allows the + planner to make use of the actual values of the parameters provided by + each Bind message, rather than use generic estimates. @@ -992,7 +986,7 @@ In the event of a backend-detected error during copy-in mode (including - receipt of a CopyFail message), the backend will issue an ErrorResponse + receipt of a CopyFail message), the backend will issue an ErrorResponse message. If the COPY command was issued via an extended-query message, the backend will now discard frontend messages until a Sync message is received, then it will issue ReadyForQuery and return to normal @@ -1039,12 +1033,25 @@ - The CopyInResponse and CopyOutResponse messages include fields that - inform the frontend of the number of columns per row and the format - codes being used for each column. (As of the present implementation, - all columns in a given COPY operation will use the same - format, but the message design does not assume this.) + There is another Copy-related mode called Copy-both, which allows + high-speed bulk data transfer to and from the server. + Copy-both mode is initiated when a backend in walsender mode + executes a START_REPLICATION statement. The + backend sends a CopyBothResponse message to the frontend. Both + the backend and the frontend may then send CopyData messages + until the connection is terminated. See . + + + The CopyInResponse, CopyOutResponse and CopyBothResponse messages + include fields that inform the frontend of the number of columns + per row and the format codes being used for each column. (As of + the present implementation, all columns in a given COPY + operation will use the same format, but the message design does not + assume this.) + + @@ -1101,7 +1108,7 @@ standard_conforming_strings was not reported by releases before 8.1; IntervalStyle was not reported by releases before 8.4; - application_name was not reported by releases before 8.5.) + application_name was not reported by releases before 9.0.) Note that server_version, server_encoding and @@ -1117,7 +1124,7 @@ backend will send a NotificationResponse message (not to be confused with NoticeResponse!) whenever a NOTIFY command is executed for the same - notification name. + channel name. @@ -1290,6 +1297,285 @@ + +Streaming Replication Protocol + + +To initiate streaming replication, the frontend sends the +replication parameter in the startup message. This tells the +backend to go into walsender mode, wherein a small set of replication commands +can be issued instead of SQL statements. Only the simple query protocol can be +used in walsender mode. + +The commands accepted in walsender mode are: + + + + IDENTIFY_SYSTEM + + + Requests the server to identify itself. Server replies with a result + set of a single row, containing two fields: + + + + + + + systemid + + + + The unique system identifier identifying the cluster. This + can be used to check that the base backup used to initialize the + standby came from the same cluster. + + + + + + + timeline + + + + Current TimelineID. Also useful to check that the standby is + consistent with the master. + + + + + + + + + + START_REPLICATION XXX/XXX + + + Instructs server to start streaming WAL, starting at + WAL position XXX/XXX. + The server can reply with an error, e.g. if the requested section of WAL + has already been recycled. On success, server responds with a + CopyBothResponse message, and then starts to stream WAL to the frontend. + WAL will continue to be streamed until the connection is broken; + no further commands will be accepted. + + + + WAL data is sent as a series of CopyData messages. (This allows + other information to be intermixed; in particular the server can send + an ErrorResponse message if it encounters a failure after beginning + to stream.) The payload in each CopyData message follows this format: + + + + + + + XLogData (B) + + + + + + + Byte1('w') + + + + Identifies the message as WAL data. + + + + + + Byte8 + + + + The starting point of the WAL data in this message, given in + XLogRecPtr format. + + + + + + Byte8 + + + + The current end of WAL on the server, given in + XLogRecPtr format. + + + + + + Byte8 + + + + The server's system clock at the time of transmission, + given in TimestampTz format. + + + + + + Byten + + + + A section of the WAL data stream. + + + + + + + + + + + A single WAL record is never split across two CopyData messages. + When a WAL record crosses a WAL page boundary, and is therefore + already split using continuation records, it can be split at the page + boundary. In other words, the first main WAL record and its + continuation records can be sent in different CopyData messages. + + + Note that all fields within the WAL data and the above-described header + will be in the sending server's native format. Endianness, and the + format for the timestamp, are unpredictable unless the receiver has + verified that the sender's system identifier matches its own + pg_control contents. + + + If the WAL sender process is terminated normally (during postmaster + shutdown), it will send a CommandComplete message before exiting. + This might not happen during an abnormal shutdown, of course. + + + + + + BASE_BACKUP [LABEL 'label'] [PROGRESS] [FAST] + + + Instructs the server to start streaming a base backup. + The system will automatically be put in backup mode before the backup + is started, and taken out of it when the backup is complete. The + following options are accepted: + + + LABEL 'label' + + + Sets the label of the backup. If none is specified, a backup label + of base backup will be used. The quoting rules + for the label are the same as a standard SQL string with + turned on. + + + + + + PROGRESS + + + Request information required to generate a progress report. This will + send back an approximate size in the header of each tablespace, which + can be used to calculate how far along the stream is done. This is + calculated by enumerating all the file sizes once before the transfer + is even started, and may as such have a negative impact on the + performance - in particular it may take longer before the first data + is streamed. Since the database files can change during the backup, + the size is only approximate and may both grow and shrink between + the time of approximation and the sending of the actual files. + + + + + + FAST + + + Request a fast checkpoint. + + + + + + + When the backup is started, the server will first send a header in + ordinary result set format, followed by one or more CopyResponse + results, one for PGDATA and one for each additional tablespace other + than pg_default and pg_global. The data in + the CopyResponse results will be a tar format (using ustar00 + extensions) dump of the tablespace contents. + + + The header is an ordinary resultset with one row for each tablespace. + The fields in this row are: + + + spcoid + + + The oid of the tablespace, or NULL if it's the base + directory. + + + + + spclocation + + + The full path of the tablespace directory, or NULL + if it's the base directory. + + + + + size + + + The approximate size of the tablespace, if progress report has + been requested; otherwise it's NULL. + + + + + + + The tar archive for the data directory and each tablespace will contain + all files in the directories, regardless of whether they are + PostgreSQL files or other files added to the same + directory. The only excluded files are: + + + + postmaster.pid + + + + + pg_xlog (including subdirectories) + + + + Owner, group and file mode are set if the underlying filesystem on + the server supports it. + + + + + + + + + Message Data Types @@ -1340,7 +1626,7 @@ This section describes the base data types used in messages. value that will appear, otherwise the value is variable. Eg. String, String("user"). - + There is no predefined limit on the length of a string @@ -1951,7 +2237,7 @@ Bind (F) (denoted R below). This can be zero to indicate that there are no result columns or that the result columns should all use the default format - (text); + (text); 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. @@ -2221,6 +2507,12 @@ CommandComplete (B) rows is the number of rows updated. + + For a SELECT or CREATE TABLE AS + command, the tag is SELECT rows + where rows is the number of rows retrieved. + + For a MOVE command, the tag is MOVE rows where @@ -2419,7 +2711,7 @@ CopyInResponse (B) characters, etc). 1 indicates the overall copy format is binary (similar to DataRow format). - See + See for more information. @@ -2493,8 +2785,80 @@ CopyOutResponse (B) 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. + 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. + + + + + + + + + + + + +CopyBothResponse (B) + + + + + + + + Byte1('W') + + + + Identifies the message as a Start Copy Both response. + This message is used only for Streaming Replication. + + + + + + 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. @@ -3181,7 +3545,7 @@ NotificationResponse (B) - The name of the condition that the notify has been raised on. + The name of the channel that the notify has been raised on. @@ -3191,9 +3555,7 @@ NotificationResponse (B) - Additional information passed from the notifying process. - (Currently, this feature is unimplemented so the field - is always an empty string.) + The payload string passed from the notifying process. @@ -4140,7 +4502,6 @@ not line breaks. - Summary of Changes since Protocol 2.0 @@ -4234,7 +4595,7 @@ the backend. The NotificationResponse ('A') message has an additional string -field, which is presently empty but might someday carry additional data passed +field, which can carry a payload string passed from the NOTIFY event sender. @@ -4245,5 +4606,4 @@ string parameter; this has been removed. -