53.4. Протокол потоковой репликации
Пред. НаверхГлава 53. Клиент-серверный протоколНачало След.

53.4. Протокол потоковой репликации #

Чтобы инициировать потоковую репликацию, клиент передаёт в стартовом сообщении параметр replication. Логическое значение true (или on, yes, 1) этого параметра указывает обслуживающему процессу перейти в режим передатчика данных физической репликации. В этом режиме вместо SQL-операторов клиент может выдавать только ограниченный набор команд репликации, показанный ниже.

Если параметр replication имеет значение database, обслуживающий процесс должен перейти в режим передатчика данных логической репликации. При этом выполняется подключение к базе данных, заданной в параметре dbname. В режиме логической репликации могут выполняться как команды репликации, показанные ниже, так и обычные SQL-команды.

В режиме передачи данных физической или логической репликации может использоваться только простой протокол запросов.

Для тестирования команд репликации вы можете установить соединение для репликации, запустив psql или другую программу на базе libpq со строкой подключения, включающей параметр replication, например так: 

psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"

Однако часто полезнее использовать pg_receivewal (для физической репликации) или pg_recvlogical (для логической).

Команды репликации записываются в журнал работы сервера, когда включён параметр log_replication_commands.

В режиме репликации принимаются следующие команды:

IDENTIFY_SYSTEM #

Запрашивает идентификационные данные сервера. Сервер возвращает набор результатов с одной строкой, содержащей четыре поля:

systemid (text)

Уникальный идентификатор системы, идентифицирующий кластер. По нему можно определить, что базовая резервная копия, из которой инициализировался резервный сервер, получена из того же кластера.

timeline (int8)

Идентификатор текущей линии времени. Также полезен для того, чтобы убедиться, что резервный сервер согласован с главным.

xlogpos (text)

Текущее положение сохранённых данных в WAL. Позволяет узнать, с какой позиции в журнале предзаписи может начаться потоковая передача.

dbname (text)

Подключённая база данных или NULL.

SHOW имя #

Запрашивает у сервера текущее значение параметра времени выполнения. Эта команда подобна SQL-команде SHOW.

имя

Имя параметра времени выполнения. Доступные параметры описаны в Главе 18.

TIMELINE_HISTORY лин_врем #

Запрашивает с сервера файл истории для линии времени лин_врем. Сервер возвращает набор результатов в одной строке, содержащей два поля. Эти поля обозначены как имеющие тип text, но фактически они содержат просто байты, не в текстовой кодировке:

filename (text)

Имя файла с историей линии времени, например 00000002.history.

content (text)

Содержимое файла с историей линией времени.

CREATE_REPLICATION_SLOT имя_слота [ TEMPORARY ] { PHYSICAL | LOGICAL модуль_вывода } [ ( параметр [, ...] ) ] #

Создаёт слот физической или логической репликации. Слоты репликации описаны подробно в Подразделе 25.2.6.

имя_слота

Имя создаваемого слота. Заданное имя должно быть допустимым для слота репликации (см. Подраздел 25.2.6.1).

модуль_вывода

Имя модуля вывода, применяемого для логического декодирования (см. Раздел 47.6).

TEMPORARY

Это указание отмечает, что данный слот репликации является временным. Временные слоты не сохраняются на диске и автоматически удаляются при ошибке или завершении сеанса.

Поддерживаются следующие параметры:

TWO_PHASE [ boolean ]

Если параметр включён (по умолчанию он отключён), этот слот логической репликации поддерживает декодирование двухфазной фиксации. С этим параметром декодируются и передаются серверу команды, связанные с двухфазной фиксацией: PREPARE TRANSACTION, COMMIT PREPARED и ROLLBACK PREPARED. Транзакция будет декодироваться и передаваться во время PREPARE TRANSACTION.

RESERVE_WAL [ boolean ]

Если параметр включён (по умолчанию он отключён), этот слот физической репликации резервирует WAL немедленно. Без этого указания WAL резервируется только при подключении клиента потоковой репликации.

SNAPSHOT { 'export' | 'use' | 'nothing' }

Эти указания выбирают, что делать со снимком, создаваемым при инициализации логического слота. С указанием 'export', подразумеваемым по умолчанию, этот снимок будет экспортироваться для использования в других сеансах. Это указание нельзя использовать внутри транзакции. С указанием 'use' снимок будет использоваться для текущей транзакции, в которой выполняется команда. Это указание должно использоваться в транзакции, при этом команда CREATE_REPLICATION_SLOT должна быть первой в этой транзакции. Наконец, с 'nothing' снимок будет использоваться только для логического декодирования в обычном режиме, и ничего больше с ним делать нельзя.

FAILOVER [ boolean ]

Если параметр имеет значение true, слот может синхронизироваться с резервными серверами, что позволяет возобновлять логическую репликацию после аварийного переключения узлов. Значение по умолчанию — false.

В ответ на эту команду сервер передаст набор результатов с одной строкой, содержащей следующие поля:

slot_name (text)

Имя создаваемого слота репликации.

consistent_point (text)

Позиция в WAL, в которой слот достиг согласованного состояния. Это самая ранняя позиция, с которой может начаться трансляция через этот слот репликации.

snapshot_name (text)

Идентификатор снимка, экспортированного командой. Этот снимок действителен до тех пор, пока через это соединение не будет выполнена следующая команда или соединение не будет закрыто. Null, если созданный слот — физический.

output_plugin (text)

Имя модуля вывода, используемого созданным слотом репликации. Null, если созданный слот — физический.

CREATE_REPLICATION_SLOT имя_слота [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL модуль_вывода [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT | TWO_PHASE ] } #

Такой вариант записи команды CREATE_REPLICATION_SLOT по-прежнему поддерживается для совместимости со старыми версиями.

ALTER_REPLICATION_SLOT имя_слота ( параметр [, ...] ) #

Изменяет определение слота репликации. Слоты репликации подробно описаны в Подразделе 25.2.6. Эта команда сейчас поддерживается только для слотов логической репликации.

имя_слота

Имя изменяемого слота. Заданное имя должно быть действительным для слота репликации (см. Подраздел 25.2.6.1).

Поддерживается следующий параметр:

FAILOVER [ boolean ]

Если параметр имеет значение true, слот может синхронизироваться с резервными серверами, что позволяет возобновлять логическую репликацию после аварийного переключения узлов.

READ_REPLICATION_SLOT имя_слота #

Считывает информацию о слоте репликации. Возвращает кортеж со значениями NULL, если указанный слот репликации не существует. Эта команда поддерживается только для слотов физической репликации.

В ответ на эту команду сервер вернёт набор результатов с одной строкой, содержащей следующие поля:

slot_type (text)

Тип слота репликации: physical или NULL.

restart_lsn (text)

restart_lsn слота репликации.

restart_tli (int8)

Идентификатор линии времени, связанной с restart_lsn, в текущей истории линии времени.

START_REPLICATION [ SLOT имя_слота ] [ PHYSICAL ] XXX/XXX [ TIMELINE лин_врем ] #

Указывает серверу начать потоковую передачу WAL, начиная с позиции XXX/XXX в WAL. Если указывается параметр TIMELINE, передача начинается на линии времени лин_врем, иначе выбирается текущая линия времени сервера. Сервер может вернуть в ответ ошибку, например, если запрошенный сегмент WAL уже потерян. Если проблем не возникает, сервер возвращает сообщение CopyBothResponse, а затем начинает передавать поток WAL клиенту.

Если в параметрах передаётся имя_слота, сервер будет отражать состояние репликации в этом слоте и отслеживать, какие сегменты, а если включён режим hot_standby_feedback, то и в каких транзакциях, всё ещё нужны этому резервному серверу.

Если клиент запрашивает не последнюю, но существующую в истории сервера линию времени, сервер будет передавать весь WAL на этой линии времени, начиная с запрошенной стартовой точки до момента, когда сервер переключился на другую линию времени. Если клиент запрашивает передачу с начальной позицией точно в конце старой линии времени, сервер полностью пропускает режим COPY.

После передачи всех записей WAL на линии времени, не являющейся текущей, сервер завершает потоковую передачу, выходя из режима копирования. Когда клиент подтверждает завершение передачи, также выходя из режима копирования, сервер возвращает набор результатов в одной строке с двумя столбцами, сообщая таким образом о следующей линии времени в истории сервера. В первом столбце передаётся идентификатор следующей линии времени (типа int8), а во втором — позиция в WAL, в которой произошло переключение (типа text). Обычно в этой же позиции завершается передача потока WAL, но возможны исключения, когда сервер может передавать записи WAL из старой линии времени, которые он сам ещё не воспроизвёл до переключения. Наконец сервер передаёт два сообщения CommandComplete (одно говорит о завершении CopyData, а второе — о завершении самой команды START_REPLICATION), после чего он готов принять следующую команду.

Данные WAL передаются в серии сообщений CopyData; за подробностями обратитесь к Разделу 53.6 и Разделу 53.7. (Это позволяет перемежать их с другой информацией; в частности, сервер может передать сообщение ErrorResponse, если он столкнулся с проблемами, уже начав передачу потока.) Полезная нагрузка каждого сообщения CopyData от сервера к клиенту содержит данные в одном из следующих форматов:

XLogData (B) — данные журнала транзакций #
Byte1('w')

Указывает, что в этом сообщении передаются данные WAL.

Int64

Начальная точка данных WAL в этом сообщении.

Int64

Текущее положение конца WAL на сервере.

Int64

Показания системных часов сервера в момент передачи, в микросекундах с полуночи 2000-01-01.

Byten

Фрагмент потока данных WAL.

Одна запись WAL никогда не разделяется на два сообщения XLogData. Когда запись WAL пересекает границу страницы WAL, и таким образом от неё уже оказывается отделена продолжающая запись, её можно разделить на сообщения по границе страницы. Другими словами, первая основная запись WAL и продолжающие её записи могут быть переданы в различных сообщениях XLogData.

Primary keepalive message (B) — Сообщение об активности ведущего #
Byte1('k')

Указывает, что это сообщение об активности отправителя.

Int64

Текущее положение конца WAL на сервере.

Int64

Показания системных часов сервера в момент передачи, в микросекундах с полуночи 2000-01-01.

Byte1

Значение 1 означает, что клиент должен ответить на это сообщение как можно скорее, во избежание отключения по тайм-ауту. Со значением 0 это не требуется.

Принимающий процесс может передавать ответы отправителю в любое время, используя один из следующих форматов данных (также в полезной нагрузке сообщения CopyData):

Standby status update (F) — Обновление состояния резервного сервера #
Byte1('r')

Указывает, что это сообщение передаёт обновлённое состояние получателя.

Int64

Положение следующего за последним байтом WAL, полученным и записанным на диск на резервном сервере.

Int64

Положение следующего за последним байтом WAL, сохранённым на диске на резервном сервере.

Int64

Положение следующего за последним байтом WAL, применённым на резервном сервере.

Int64

Показания системных часов клиента в момент передачи, в микросекундах с полуночи 2000-01-01.

Byte1

Если содержит 1, клиент запрашивает от сервера немедленный ответ на это сообщение. Так клиент может запросить отклик сервера и проверить, продолжает ли функционировать соединение.

Hot standby feedback message (F) — Сообщение обратной связи горячего резерва #
Byte1('h')

Указывает, что это сообщение обратной связи горячего резерва.

Int64

Показания системных часов клиента в момент передачи, в микросекундах с полуночи 2000-01-01.

Int32

Текущее глобальное значение xmin данного резервного сервера, не учитывающее catalog_xmin всех слотов репликации. Если и это значение, и следующее catalog_xmin, равны 0, это воспринимается как уведомление о том, что через данное подключение больше не будут передаваться сообщения обратной связи горячего резерва. Последующие ненулевые сообщения могут возобновить работу механизма обратной связи.

Int32

Эпоха глобального идентификатора транзакции xmin на резервном сервере.

Int32

Наименьшее значение catalog_xmin для всех слотов репликации на резервном сервере. Значение 0 показывает, что на резервном сервере нет catalog_xmin, либо обратная связь горячего резерва отключена.

Int32

Эпоха идентификатора транзакции catalog_xmin на резервном сервере.

START_REPLICATION SLOT имя_слота LOGICAL XXX/XXX [ ( имя_параметра [ значение_параметра ] [, ...] ) ] #

Указывает серверу начинать потоковую передачу WAL для логической репликации с позиции XXX/XXX в WAL или с confirmed_flush_lsn слота (см. Раздел 52.19), если это значение больше. Таким образом клиентам не приходится обновлять локальный статус LSN, если не нужно обрабатывать данные. Однако в случаях, когда репликация начинается не с запрошенного LSN, некоторые ошибки на стороне клиента могут остаться незамеченными. Поэтому прежде чем передавать START_REPLICATION, имеет смысл запросить значение confirmed_flush_lsn и убедиться в том, что оно соответствует ожиданиям.

Сервер может вернуть в ответ ошибку, например, если такого слота нет. Если проблем не возникает, сервер возвращает сообщение CopyBothResponse, а затем начинает передавать поток WAL клиенту.

Данные, передаваемые внутри сообщений CopyBothResponse, имеют тот же формат, что описан для команды START_REPLICATION ... PHYSICAL, включая два сообщения CommandComplete.

Обработку выводимых данных для передачи выполняет модуль вывода, связанный с выбранным слотом.

SLOT имя_слота

Имя слота, из которого передаются изменения. Это имя является обязательным, оно должно соответствовать существующему логическому слоту репликации, созданному командой CREATE_REPLICATION_SLOT в режиме LOGICAL.

XXX/XXX

Позиция в WAL, с которой должна начаться передача.

имя_параметра

Имя параметра, передаваемого модулю вывода логического декодирования для выбранного слота. Параметры, принимаемые стандартным модулем (pgoutput), описаны в Разделе 53.5.

значение_параметра

Необязательное значение, в форме строковой константы, связываемое с указанным параметром.

DROP_REPLICATION_SLOT имя_слота [ WAIT ] #

Удаляет слот репликации, что приводит к освобождению всех занятых им ресурсов на стороне сервера. Если слот представляет собой логический слот, созданный не в той базе данных, к которой подключён walsender, команда завершается ошибкой.

имя_слота

Имя слота, подлежащего удалению.

WAIT

С этим указанием команда будет ждать, пока активный слот не станет неактивным (по умолчанию в этом случае выдаётся ошибка).

UPLOAD_MANIFEST #

Загружает манифест копии при подготовке к инкрементальному резервному копированию.

BASE_BACKUP [ ( параметр [, ...] ) ] #

Указывает серверу начать потоковую передачу базовой копии. Система автоматически переходит в режим резервного копирования до начала передачи, и выходит из него после завершения копирования. Эта команда принимает следующие параметры:

LABEL 'метка'

Устанавливает метку для резервной копии. Если метка не задана, по умолчанию устанавливается метка base backup. Для метки действуют те же правила применения кавычек, что и для стандартных строк SQL при включённым режиме standard_conforming_strings.

TARGET получатель

Указывает серверу, куда передавать резервную копию. Если выбрано значение client, используемое по умолчанию, данные резервной копии передаются клиенту. При значении server файлы копии записываются на сервере в каталог, заданный параметром TARGET_DETAIL. При значении blackhole данные никуда не передаются, а просто отбрасываются.

Чтобы установить значение server, нужно иметь права суперпользователя или роли pg_write_server_files.

TARGET_DETAIL дополнительная_информация

Дополнительная информация о получателе.

Сейчас этот параметр можно использовать, только когда получателем является server. Указывает каталог хранения данных на целевом сервере.

PROGRESS [ boolean ]

Если параметр включён (по умолчанию он отключён), запрашивается информация, необходимая для отслеживания прогресса операции. Сервер передаёт в ответ приблизительный размер в заголовке каждого табличного пространства, исходя из которого можно понять, насколько продвинулась передача потока. Для вычисления этого размера анализируются размеры всех файлов ещё до начала передачи, и это может негативно повлиять на производительность — в частности, может увеличиться задержка передачи первых данных. Так как файлы базы данных могут меняться во время резервного копирования, оценка размера не будет точной; размер базы может увеличиться или уменьшиться за время от вычисления этой оценки до передачи актуальных файлов.

CHECKPOINT { 'fast' | 'spread' }

Задаёт тип контрольной точки, которая будет выполняться в начале базового копирования. По умолчанию spread (протяжённая).

WAL [ boolean ]

Если параметр включён (по умолчанию он отключён), в резервную копию помещаются необходимые сегменты WAL. При этом в подкаталог pg_wal архива базового каталога будут помещены все файлы с начала до конца копирования.

WAIT [ boolean ]

Если параметр включён (по умолчанию), при копировании ожидается завершение архивации последнего требуемого сегмента WAL либо выдаётся предупреждение, если архивация WAL не включена. Если отключён, при копировании не будет ни ожидания, ни предупреждений, так что обеспечение наличия требуемого журнала становится задачей клиента.

COMPRESSION метод

Указывает серверу метод сжатия данных резервной копии. На данный момент поддерживаются следующие методы: gzip, lz4 и zstd.

COMPRESSION_DETAIL дополнительная_информация

Дополнительная информация для выбранного метода сжатия. Используется только вместе с параметром COMPRESSION. Если значение параметра — целое число, оно обозначает уровень сжатия. В противном случае значение должно представлять собой список ключевых слов, разделённых запятыми, в форме ключевое_слово или ключевое_слово=значение. На данный момент поддерживаются ключевые слова level, long и workers.

Ключевое слово level задаёт уровень сжатия. Для gzip уровень сжатия задаётся целым числом от 1 до 9 (по умолчанию Z_DEFAULT_COMPRESSION или -1), для lz4 — целым числом от 1 до 12 (по умолчанию 0 для максимально быстрого сжатия), а для zstd — целым числом от ZSTD_minCLevel() (обычно -131072) до ZSTD_maxCLevel() (обычно 22), по умолчанию ZSTD_CLEVEL_DEFAULT или 3.

Ключевое слово long включает режим поиска соответствий на большой дистанции для улучшения коэффициента сжатия за счёт повышения нагрузки на память. Этот режим поддерживается только для zstd.

Ключевое слово workers задаёт число параллельных потоков для сжатия. Сжатие в несколько параллельных потоков поддерживается только для zstd.

MAX_RATE скорость

Ограничивает (сдерживает) максимальный объём данных, передаваемый от сервера клиенту за единицу времени. Единица измерения этого параметра — килобайты в секунду. Если задаётся этот параметр, его значение должно быть равно нулю, либо должно находиться в диапазоне от 32 (килобайт/сек) до 1 Гбайта/сек (включая границы). Если передаётся ноль, либо параметр не задаётся, скорость передачи не ограничивается.

TABLESPACE_MAP [ boolean ]

Если параметр включён (по умолчанию он отключён), информация о символических ссылках, существующих в каталоге pg_tblspc, включается в файл tablespace_map. Файл карты табличных пространств содержит имена всех ссылок, содержащихся в каталоге pg_tblspc/, и полный путь для каждой ссылки.

VERIFY_CHECKSUMS [ boolean ]

Если параметр включён (по умолчанию), контрольные суммы проверяются в процессе резервного копирования, когда они присутствуют. При отключении параметра эта проверка опускается.

MANIFEST параметр_манифеста

Когда указывается этот параметр, и он имеет значение yes или force-encode, вместе с копией создаётся и передаётся манифест копии. Манифест содержит список всех файлов, содержащихся в копии, за исключением файлов WAL, которые могут быть добавлены дополнительно. В нём также сохраняется размер, дата последнего изменения и, возможно, контрольная сумма каждого файла. Значение force-encode указывает, что все имена файлов должны кодироваться в шестнадцатеричном виде; по умолчанию кодироваться будут только те имена, которые представлены не байтовыми последовательностями UTF-8. Это значение предназначено в первую очередь для тестирования, чтобы можно было проверить, что клиентские программы могут корректно прочитать закодированные имена. Для совместимости с предыдущими версиями подразумевается значение MANIFEST 'no'.

MANIFEST_CHECKSUMS алгоритм_контрольной_суммы

Задаёт алгоритм контрольных сумм, которые будут рассчитываться для всех файлов, описанных в манифесте копии. В настоящее время поддерживаются алгоритмы NONE (отсутствует), CRC32C, SHA224, SHA256, SHA384 и SHA512. По умолчанию применяется CRC32C.

INCREMENTAL

Запрашивает инкрементальную резервную копию. Обязательно выполните команду UPLOAD_MANIFEST перед началом базового резервного копирования с этим параметром.

Когда запускается копирование, сервер сначала передаёт два обычных набора результатов, за которыми следуют один или более результатов CopyOutResponse.

В первом обычном наборе результатов передаётся начальная позиция резервной копии, в одной строке с двумя столбцами. В первом столбце содержится стартовая позиция в формате XLogRecPtr, а во втором идентификатор соответствующей линии времени.

Во втором обычном наборе результатов передаётся по одной строке для каждого табличного пространства. Эта строка содержит следующие поля:

spcoid (oid)

OID табличного пространства либо NULL, если это базовый каталог.

spclocation (text)

Полный путь к каталогу табличного пространства либо NULL, если это базовый каталог.

size (int8)

Приблизительный размер табличного пространства (в килобайтах, размером 1024 байта), если была запрошена информация о прогрессе операции; в противном случае NULL.

За вторым обычным набором результатов следует сообщение CopyOutResponse. Полезной нагрузкой каждого последующего сообщения CopyData будет сообщение в одном из следующих форматов:

new archive (B)
Byte1('n')

Указывает, что это сообщение начинает новый архив. Сервер передаст один архив для основного каталога данных и по одному для каждого дополнительного табличного пространства. Данные в архиве представлены в формате tar («формате обмена ustar», описанном в стандарте POSIX 1003.1-2008).

String

Имя файла этого архива.

String

Для основного каталога данных пустая строка. Для других табличных пространств — полный путь к каталогу, для которого был создан архив.

manifest (B)
Byte1('m')

Указывает, что это сообщение начинает манифест копии.

archive or manifest data (B)
Byte1('d')

Указывает, что это сообщение передаёт данные архива или манифеста.

Byten

Байты данных.

progress report (B)
Byte1('p')

Указывает, что в этом сообщении передаётся отчёт о выполнении.

Int64

Объём обработанных данных в текущем табличном пространстве в байтах.

После передачи сообщения CopyOutResponse или всех таких сообщений передаётся обычный набор результатов, в котором содержится конечная позиция копии в WAL, в том же формате, что и стартовая позиция.

Архив tar каталога данных и всех табличных пространств будет содержать все файлы в этих каталогах, будь то файлы Postgres Pro или посторонние файлы, добавленные в эти каталоги. Исключение составляют только следующие файлы:

  • postmaster.pid

  • postmaster.opts

  • pg_internal.init (находится в нескольких каталогах)

  • Различные временные файлы и каталоги, создаваемые в процессе работы сервером Postgres Pro, в частности, файлы и каталоги с именами, начинающимися с pgsql_tmp, и временные отношения.

  • Нежурналируемые отношения, за исключением слоя инициализации, который необходим при восстановлении для пересоздания нежурналируемого отношения (пустого).

  • pg_wal, включая подкаталоги. Если в резервную копию включаются файлы WAL, в архив входит преобразованная версия pg_wal, в которой будут находиться только файлы, необходимые для восстановления копии, но не всё остальное содержимое этого каталога

  • pg_dynshmem, pg_notify, pg_replslot, pg_serial, pg_snapshots, pg_stat_tmp и pg_subtrans копируются как пустые каталоги (даже если это символические ссылки)

  • Файлы, кроме обычных файлов и каталогов, например, символические ссылки (кроме вышеупомянутых каталогов), а также файлы специальных устройств и файлы операционных систем, пропускаются (символические ссылки в pg_tblspc сохраняются).

Если файловая система сервера поддерживает это, в архив включается информация о владельце, группе и режиме файла.

Во всех вышеперечисленных командах значение_параметра можно не указывать, если это параметр типа boolean. Это равнозначно тому, чтобы указать значение TRUE.

Пред. Наверх След.
53.3. Аутентификация SASL Начало 53.5. Протокол логической потоковой репликации
53.4. Streaming Replication Protocol
Prev UpChapter 53. Frontend/Backend ProtocolHome Next

53.4. Streaming Replication Protocol #

To initiate streaming replication, the frontend sends the replication parameter in the startup message. A Boolean value of true (or on, yes, 1) tells the backend to go into physical replication walsender mode, wherein a small set of replication commands, shown below, can be issued instead of SQL statements.

Passing database as the value for the replication parameter instructs the backend to go into logical replication walsender mode, connecting to the database specified in the dbname parameter. In logical replication walsender mode, the replication commands shown below as well as normal SQL commands can be issued.

In either physical replication or logical replication walsender mode, only the simple query protocol can be used.

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_receivewal (for physical replication) or pg_recvlogical (for logical replication).

Replication commands are logged in the server log when log_replication_commands is enabled.

The commands accepted in replication mode are:

IDENTIFY_SYSTEM #

Requests the server to identify itself. Server replies with a result set of a single row, containing four fields:

systemid (text)

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 (int8)

Current timeline ID. Also useful to check that the standby is consistent with the primary.

xlogpos (text)

Current WAL flush location. Useful to get a known location in the write-ahead log where streaming can start.

dbname (text)

Database connected to or null.

SHOW name #

Requests the server to send the current setting of a run-time parameter. This is similar to the SQL command SHOW.

name

The name of a run-time parameter. Available parameters are documented in Chapter 18.

TIMELINE_HISTORY tli #

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, they effectively return raw bytes, with no encoding conversion:

filename (text)

File name of the timeline history file, e.g., 00000002.history.

content (text)

Contents of the timeline history file.

CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL | LOGICAL output_plugin } [ ( option [, ...] ) ] #

Create a physical or logical replication slot. See Section 25.2.6 for more about replication slots.

slot_name

The name of the slot to create. Must be a valid replication slot name (see Section 25.2.6.1).

output_plugin

The name of the output plugin used for logical decoding (see Section 47.6).

TEMPORARY

Specify that this replication slot is a temporary one. Temporary slots are not saved to disk and are automatically dropped on error or when the session has finished.

The following options are supported:

TWO_PHASE [ boolean ]

If true, this logical replication slot supports decoding of two-phase commit. With this option, commands related to two-phase commit such as PREPARE TRANSACTION, COMMIT PREPARED and ROLLBACK PREPARED are decoded and transmitted. The transaction will be decoded and transmitted at PREPARE TRANSACTION time. The default is false.

RESERVE_WAL [ boolean ]

If true, this physical replication slot reserves WAL immediately. Otherwise, WAL is only reserved upon connection from a streaming replication client. The default is false.

SNAPSHOT { 'export' | 'use' | 'nothing' }

Decides what to do with the snapshot created during logical slot initialization. 'export', which is the default, will export the snapshot for use in other sessions. This option can't be used inside a transaction. 'use' will use the snapshot for the current transaction executing the command. This option must be used in a transaction, and CREATE_REPLICATION_SLOT must be the first command run in that transaction. Finally, 'nothing' will just use the snapshot for logical decoding as normal but won't do anything else with it.

FAILOVER [ boolean ]

If true, the slot is enabled to be synced to the standbys so that logical replication can be resumed after failover. The default is false.

In response to this command, the server will send a one-row result set containing the following fields:

slot_name (text)

The name of the newly-created replication slot.

consistent_point (text)

The WAL location at which the slot became consistent. This is the earliest location from which streaming can start on this replication slot.

snapshot_name (text)

The identifier of the snapshot exported by the command. The snapshot is valid until a new command is executed on this connection or the replication connection is closed. Null if the created slot is physical.

output_plugin (text)

The name of the output plugin used by the newly-created replication slot. Null if the created slot is physical.

CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT | TWO_PHASE ] } #

For compatibility with older releases, this alternative syntax for the CREATE_REPLICATION_SLOT command is still supported.

ALTER_REPLICATION_SLOT slot_name ( option [, ...] ) #

Change the definition of a replication slot. See Section 25.2.6 for more about replication slots. This command is currently only supported for logical replication slots.

slot_name

The name of the slot to alter. Must be a valid replication slot name (see Section 25.2.6.1).

The following option is supported:

FAILOVER [ boolean ]

If true, the slot is enabled to be synced to the standbys so that logical replication can be resumed after failover.

READ_REPLICATION_SLOT slot_name #

Read some information associated with a replication slot. Returns a tuple with NULL values if the replication slot does not exist. This command is currently only supported for physical replication slots.

In response to this command, the server will return a one-row result set, containing the following fields:

slot_type (text)

The replication slot's type, either physical or NULL.

restart_lsn (text)

The replication slot's restart_lsn.

restart_tli (int8)

The timeline ID associated with restart_lsn, following the current timeline history.

START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ] #

Instructs server to start streaming WAL, starting at WAL location 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, the 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 skips COPY mode entirely.

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 location 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 two CommandComplete messages (one that ends the CopyData and the other ends the START_REPLICATION itself), and is ready to accept a new command.

WAL data is sent as a series of CopyData messages; see Section 53.6 and Section 53.7 for details. (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:

XLogData (B) #
Byte1('w')

Identifies the message as WAL data.

Int64

The starting point of the WAL data in this message.

Int64

The current end of WAL on the server.

Int64

The server's system clock at the time of transmission, as microseconds since midnight on 2000-01-01.

Byten

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.

Primary keepalive message (B) #
Byte1('k')

Identifies the message as a sender keepalive.

Int64

The current end of WAL on the server.

Int64

The server's system clock at the time of transmission, as microseconds since midnight on 2000-01-01.

Byte1

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):

Standby status update (F) #
Byte1('r')

Identifies the message as a receiver status update.

Int64

The location of the last WAL byte + 1 received and written to disk in the standby.

Int64

The location of the last WAL byte + 1 flushed to disk in the standby.

Int64

The location of the last WAL byte + 1 applied in the standby.

Int64

The client's system clock at the time of transmission, as microseconds since midnight on 2000-01-01.

Byte1

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.

Hot standby feedback message (F) #
Byte1('h')

Identifies the message as a hot standby feedback message.

Int64

The client's system clock at the time of transmission, as microseconds since midnight on 2000-01-01.

Int32

The standby's current global xmin, excluding the catalog_xmin from any replication slots. If both this value and the following catalog_xmin are 0, this is treated as a notification that hot standby feedback will no longer be sent on this connection. Later non-zero messages may reinitiate the feedback mechanism.

Int32

The epoch of the global xmin xid on the standby.

Int32

The lowest catalog_xmin of any replication slots on the standby. Set to 0 if no catalog_xmin exists on the standby or if hot standby feedback is being disabled.

Int32

The epoch of the catalog_xmin xid on the standby.

START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ] #

Instructs server to start streaming WAL for logical replication, starting at either WAL location XXX/XXX or the slot's confirmed_flush_lsn (see Section 52.19), whichever is greater. This behavior makes it easier for clients to avoid updating their local LSN status when there is no data to process. However, starting at a different LSN than requested might not catch certain kinds of client errors; so the client may wish to check that confirmed_flush_lsn matches its expectations before issuing START_REPLICATION.

The server can reply with an error, for example if the slot does not exist. On success, the 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, including two CommandComplete messages.

The output plugin associated with the selected slot is used to process the output for streaming.

SLOT slot_name

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.

XXX/XXX

The WAL location to begin streaming at.

option_name

The name of an option passed to the slot's logical decoding output plugin. See Section 53.5 for options that are accepted by the standard (pgoutput) plugin.

option_value

Optional value, in the form of a string constant, associated with the specified option.

DROP_REPLICATION_SLOT slot_name [ WAIT ] #

Drops a replication slot, freeing any reserved server-side resources. If the slot is a logical slot that was created in a database other than the database the walsender is connected to, this command fails.

slot_name

The name of the slot to drop.

WAIT

This option causes the command to wait if the slot is active until it becomes inactive, instead of the default behavior of raising an error.

UPLOAD_MANIFEST #

Uploads a backup manifest in preparation for taking an incremental backup.

BASE_BACKUP [ ( option [, ...] ) ] #

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 standard_conforming_strings turned on.

TARGET 'target'

Tells the server where to send the backup. If the target is client, which is the default, the backup data is sent to the client. If it is server, the backup data is written to the server at the pathname specified by the TARGET_DETAIL option. If it is blackhole, the backup data is not sent anywhere; it is simply discarded.

The server target requires superuser privilege or being granted the pg_write_server_files role.

TARGET_DETAIL 'detail'

Provides additional information about the backup target.

Currently, this option can only be used when the backup target is server. It specifies the server directory to which the backup should be written.

PROGRESS [ boolean ]

If set to true, 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 might as such have a negative impact on the performance. In particular, it might take longer before the first data is streamed. Since the database files can change during the backup, the size is only approximate and might both grow and shrink between the time of approximation and the sending of the actual files. The default is false.

CHECKPOINT { 'fast' | 'spread' }

Sets the type of checkpoint to be performed at the beginning of the base backup. The default is spread.

WAL [ boolean ]

If set to true, include the necessary WAL segments in the backup. This will include all the files between start and stop backup in the pg_wal directory of the base directory tar file. The default is false.

WAIT [ boolean ]

If set to true, the backup will wait until the last required WAL segment has been archived, or emit a warning if WAL archiving is not enabled. If false, the backup will neither wait nor warn, leaving the client responsible for ensuring the required log is available. The default is true.

COMPRESSION 'method'

Instructs the server to compress the backup using the specified method. Currently, the supported methods are gzip, lz4, and zstd.

COMPRESSION_DETAIL detail

Specifies details for the chosen compression method. This should only be used in conjunction with the COMPRESSION option. If the value is an integer, it specifies the compression level. Otherwise, it should be a comma-separated list of items, each of the form keyword or keyword=value. Currently, the supported keywords are level, long and workers.

The level keyword sets the compression level. For gzip the compression level should be an integer between 1 and 9 (default Z_DEFAULT_COMPRESSION or -1), for lz4 an integer between 1 and 12 (default 0 for fast compression mode), and for zstd an integer between ZSTD_minCLevel() (usually -131072) and ZSTD_maxCLevel() (usually 22), (default ZSTD_CLEVEL_DEFAULT or 3).

The long keyword enables long-distance matching mode, for improved compression ratio, at the expense of higher memory use. Long-distance mode is supported only for zstd.

The workers keyword sets the number of threads that should be used for parallel compression. Parallel compression is supported only for zstd.

MAX_RATE rate

Limit (throttle) the maximum amount of data transferred from server to client per unit of time. The expected unit is kilobytes per second. If this option is specified, the value must either be equal to zero or it must fall within the range from 32 kB through 1 GB (inclusive). If zero is passed or the option is not specified, no restriction is imposed on the transfer.

TABLESPACE_MAP [ boolean ]

If true, include information about symbolic links present in the directory pg_tblspc in a file named tablespace_map. The tablespace map file includes each symbolic link name as it exists in the directory pg_tblspc/ and the full path of that symbolic link. The default is false.

VERIFY_CHECKSUMS [ boolean ]

If true, checksums are verified during a base backup if they are enabled. If false, this is skipped. The default is true.

MANIFEST manifest_option

When this option is specified with a value of yes or force-encode, a backup manifest is created and sent along with the backup. The manifest is a list of every file present in the backup with the exception of any WAL files that may be included. It also stores the size, last modification time, and optionally a checksum for each file. A value of force-encode forces all filenames to be hex-encoded; otherwise, this type of encoding is performed only for files whose names are non-UTF8 octet sequences. force-encode is intended primarily for testing purposes, to be sure that clients which read the backup manifest can handle this case. For compatibility with previous releases, the default is MANIFEST 'no'.

MANIFEST_CHECKSUMS checksum_algorithm

Specifies the checksum algorithm that should be applied to each file included in the backup manifest. Currently, the available algorithms are NONE, CRC32C, SHA224, SHA256, SHA384, and SHA512. The default is CRC32C.

INCREMENTAL

Requests an incremental backup. The UPLOAD_MANIFEST command must be executed before running a base backup with this option.

When the backup is started, the server will first send two ordinary result sets, followed by one or more CopyOutResponse results.

The first ordinary result set contains the starting position of the backup, in a single row with two columns. The first column contains the start position given in XLogRecPtr format, and the second column contains the corresponding timeline ID.

The second ordinary result set has one row for each tablespace. The fields in this row are:

spcoid (oid)

The OID of the tablespace, or null if it's the base directory.

spclocation (text)

The full path of the tablespace directory, or null if it's the base directory.

size (int8)

The approximate size of the tablespace, in kilobytes (1024 bytes), if progress report has been requested; otherwise it's null.

After the second regular result set, a CopyOutResponse will be sent. The payload of each CopyData message will contain a message in one of the following formats:

new archive (B)
Byte1('n')

Identifies the message as indicating the start of a new archive. There will be one archive for the main data directory and one for each additional tablespace; each will use tar format (following the “ustar interchange format” specified in the POSIX 1003.1-2008 standard).

String

The file name for this archive.

String

For the main data directory, an empty string. For other tablespaces, the full path to the directory from which this archive was created.

manifest (B)
Byte1('m')

Identifies the message as indicating the start of the backup manifest.

archive or manifest data (B)
Byte1('d')

Identifies the message as containing archive or manifest data.

Byten

Data bytes.

progress report (B)
Byte1('p')

Identifies the message as a progress report.

Int64

The number of bytes from the current tablespace for which processing has been completed.

After the CopyOutResponse, or all such responses, have been sent, a final ordinary result set will be sent, containing the WAL end position of the backup, in the same format as the start position.

The tar archive for the data directory and each tablespace will contain all files in the directories, regardless of whether they are Postgres Pro files or other files added to the same directory. The only excluded files are:

  • postmaster.pid

  • postmaster.opts

  • pg_internal.init (found in multiple directories)

  • Various temporary files and directories created during the operation of the Postgres Pro server, such as any file or directory beginning with pgsql_tmp and temporary relations.

  • Unlogged relations, except for the init fork which is required to recreate the (empty) unlogged relation on recovery.

  • pg_wal, including subdirectories. If the backup is run with WAL files included, a synthesized version of pg_wal will be included, but it will only contain the files necessary for the backup to work, not the rest of the contents.

  • pg_dynshmem, pg_notify, pg_replslot, pg_serial, pg_snapshots, pg_stat_tmp, and pg_subtrans are copied as empty directories (even if they are symbolic links).

  • Files other than regular files and directories, such as symbolic links (other than for the directories listed above) and special device and operating system files, are skipped. (Symbolic links in pg_tblspc are maintained.)

Owner, group, and file mode are set if the underlying file system on the server supports it.

In all the above commands, when specifying a parameter of type boolean the value part can be omitted, which is equivalent to specifying TRUE.

Prev Up Next
53.3. SASL Authentication Home 53.5. Logical Streaming Replication Protocol