| PostgreSQL 9.6.24 Documentation | |||
|---|---|---|---|
| Prev | Up | Chapter 51. Frontend/Backend Protocol | Next |
To initiate streaming replication, the frontend sends the replication parameter in the startup message. A Boolean value of true 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. Replication commands are logged in the server log when log_replication_commands is enabled. Passing database as the value instructs walsender to connect to the database specified in the dbname parameter, which will allow the connection to be used for logical replication from that database.
For the purpose of testing replication commands, you can make a replication connection via psql or any other libpq-using tool with a connection string including the replication option, e.g.:
psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
However, it is often more useful to use pg_receivexlog (for physical replication) or pg_recvlogical (for logical replication).
The commands accepted in walsender mode are:
Requests the server to identify itself. Server replies with a result set of a single row, containing four fields:
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.
Current timeline ID. Also useful to check that the standby is consistent with the master.
Current xlog flush location. Useful to get a known location in the transaction log where streaming can start.
Database connected to or null.
Requests the server to send over the timeline history file for timeline tli. Server replies with a result set of a single row, containing two fields. While the fields are labeled as text and bytea, they effectively return raw bytes, with no escaping or encoding conversion:
File name of the timeline history file, e.g., 00000002.history.
Contents of the timeline history file.
Create a physical or logical replication slot. See Section 26.2.6 for more about replication slots.
The name of the slot to create. Must be a valid replication slot name (see Section 26.2.6.1).
The name of the output plugin used for logical decoding (see Section 47.6).
Specify that this physical replication slot reserves WAL immediately. Otherwise, WAL is only reserved upon connection from a streaming replication client.
Instructs server to start streaming WAL, starting at WAL position XXX/XXX. If TIMELINE option is specified, streaming starts on timeline tli; otherwise, the server's current timeline is selected. The server can reply with an error, for example 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.
If a slot's name is provided via slot_name, it will be updated as replication progresses so that the server knows which WAL segments, and if hot_standby_feedback is on which transactions, are still needed by the standby.
If the client requests a timeline that's not the latest but is part of the history of the server, the server will stream all the WAL on that timeline starting from the requested start point up to the point where the server switched to another timeline. If the client requests streaming at exactly the end of an old timeline, the server responds immediately with CommandComplete without entering COPY mode.
After streaming all the WAL on a timeline that is not the latest one, the server will end streaming by exiting the COPY mode. When the client acknowledges this by also exiting COPY mode, the server sends a result set with one row and two columns, indicating the next timeline in this server's history. The first column is the next timeline's ID (type int8), and the second column is the WAL position where the switch happened (type text). Usually, the switch position is the end of the WAL that was streamed, but there are corner cases where the server can send some WAL from the old timeline that it has not itself replayed before promoting. Finally, the server sends CommandComplete message, and is ready to accept a new command.
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 of each CopyData message from server to the client contains a message of one of the following formats:
Identifies the message as WAL data.
The starting point of the WAL data in this message.
The current end of WAL on the server.
The server's system clock at the time of transmission, as microseconds since midnight on 2000-01-01.
A section of the WAL data stream.
A single WAL record is never split across two XLogData 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 XLogData messages.
Identifies the message as a sender keepalive.
The current end of WAL on the server.
The server's system clock at the time of transmission, as microseconds since midnight on 2000-01-01.
1 means that the client should reply to this message as soon as possible, to avoid a timeout disconnect. 0 otherwise.
The receiving process can send replies back to the sender at any time, using one of the following message formats (also in the payload of a CopyData message):
Identifies the message as a receiver status update.
The location of the last WAL byte + 1 received and written to disk in the standby.
The location of the last WAL byte + 1 flushed to disk in the standby.
The location of the last WAL byte + 1 applied in the standby.
The client's system clock at the time of transmission, as microseconds since midnight on 2000-01-01.
If 1, the client requests the server to reply to this message immediately. This can be used to ping the server, to test if the connection is still healthy.
Identifies the message as a Hot Standby feedback message.
The client's system clock at the time of transmission, as microseconds since midnight on 2000-01-01.
The standby's current xmin. This may be 0, if the standby is sending notification that Hot Standby feedback will no longer be sent on this connection. Later non-zero messages may reinitiate the feedback mechanism.
The standby's current epoch.
Instructs server to start streaming WAL for logical replication, starting at WAL position XXX/XXX. The server can reply with an error, for example 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.
The messages inside the CopyBothResponse messages are of the same format documented for START_REPLICATION ... PHYSICAL.
The output plugin associated with the selected slot is used to process the output for streaming.
The name of the slot to stream changes from. This parameter is required, and must correspond to an existing logical replication slot created with CREATE_REPLICATION_SLOT in LOGICAL mode.
The WAL position to begin streaming at.
The name of an option passed to the slot's logical decoding plugin.
Optional value, in the form of a string constant, associated with the specified option.