pg_receivewal

note

Эта страница переведена при помощи нейросети GigaChat.

pg_receivewal — выводит журналы предзаписи с сервера PostgreSQL.

Синтаксис

pg_receivewal [option...]

Описание

pg_receivewal предназначена для потоковой передачи WAL (журнала предзаписи) с работающего кластера PostgreSQL. Полученные данные сохраняются в локальный каталог, который может быть использован как архив для восстановления до определенного момента времени. Подробнее об этом в разделе «Непрерывное архивирование и восстановление до заданной точки во времени (PITR)»

В отличие от таких механизмов, как archive_command и archive_library, pg_receivewal начинает передачу WAL в режиме реального времени — по мере его генерации на сервере, без ожидания завершения сегментов. Поэтому при использовании утилиты нет необходимости задавать archive_timeout.

По умолчанию pg_receivewal, в отличие от встроенного WAL-приемника на реплицирующем сервере, сбрасывает данные WAL только после завершения сегмента. Чтобы обеспечить сброс в реальном времени, следует использовать параметр --synchronous. Однако поскольку pg_receivewal не применяет WAL, его не следует использовать в качестве синхронного резервного при значении remote_apply параметра synchronous_commit. В противном случае PostgreSQL будет считать его отстающей резервной копией, что приведет к блокировке фиксации транзакций. Чтобы этого избежать, нужно задать application_name для pg_receivewal, отличное от указанных в synchronous_standby_names, либо изменить synchronous_commit на другое значение.

Передача журналов предзаписи осуществляется через обычное подключение к PostgreSQL с использованием протокола репликации. Для корректной передачи WAL необходимо соблюдение следующих требований:

• Соединение устанавливает суперпользователь или пользователь с правом REPLICATION (подробнее описано в разделе «Атрибуты ролей»).
• В файле pg_hba.conf разрешено подключение для репликации.
• Параметр max_wal_senders установлен на достаточное значение, чтобы поток мог подключиться.

Определение точки начала потока WAL при запуске pg_receivewal происходит следующим образом:

1. Выполняется сканирование целевого каталога для поиска последнего завершенного сегмента WAL. В качестве стартовой точки берется начало следующего сегмента.

2. Если точка начала не определена и используется слот репликации, отправляется команда READ_REPLICATION_SLOT для получения restart_lsn — доступно, начиная с PostgreSQL 15.

3. Если предыдущие способы не дали результата, используется последняя позиция сохраненных данных в WAL, полученная через команду IDENTIFY_SYSTEM.

При потере соединения или невозможности его установить из-за некритической ошибки, pg_receivewal безостановочно пытается подключиться повторно, восстанавливая передачу при успешном соединении. Чтобы отключить этот режим, используйте параметр -n.

Если не возникнет фатальных ошибок, утилита будет работать непрерывно до получения сигнала завершения SIGINT (Ctrl+C) или SIGTERM.

Параметры

Для утилиты pg_receivewal существуют следующие параметры командной строки:

-D directory
--directory=directory

Устанавливает каталог для записи данных. Параметр обязателен.

-E lsn
--endpos=lsn

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

--if-not-exists

Отменяет вызов ошибки, если при использовании с параметром --create-slot, слот с заданным именем уже существует.

-n
--no-loop

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

--no-sync

Отключает принудительную запись данных WAL на диск. Это повышает производительность, но увеличивает риск потери данных при сбое системы. Используется, как правило, только для тестирования. Несовместим с параметром --synchronous.

-s interval
--status-interval=interval

Задает интервал между сообщениями о состоянии. Интервал указывается в секундах. Меньшие значения позволяют более точно отслеживать прогресс резервного копирования с сервера. Значение ноль полностью отключает периодические обновления статуса, хотя обновление все равно будет отправлено при запросе сервера, чтобы избежать отключения из-за тайм-аута. Значение по умолчанию составляет 10 секунд.

-S slotname
--slot=slotname

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

Если клиент настроен как синхронный реплицируемый сервер, но --synchronous не указан, это может привести к блокировке фиксации транзакций на основном сервере. Чтобы избежать такой ситуации, следует использовать --synchronous.

--synchronous

Сохраняет данные WAL на диск сразу после того, как они были получены и отправляет статус серверу сразу после синхронизации, независимо от --status-interval.

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

-v
--verbose

Включает режим подробного вывода.

-Z level
-Z method[:detail]
--compress=level
--compress=method[:detail]

Включает сжатие журналов предзаписи.

Метод может быть gzip, lz4 (при наличии поддержки --with-lz4) или none для отсутствия сжатия. Если указан только уровень (целое число), то при значении больше 0 используется gzip, при 0 — сжатие не применяется.

Дополнительно могут быть заданы параметры в формате keyword или keyword=value. В настоящее время поддерживается только ключевое keyword=level. При включении сжатия к именам файлов добавляется соответствующий суффикс: .gz для gzip, .lz4 — для lz4.

-d connstr
--dbname=connstr

Задает параметры подключения к серверу. Параметры указываются в виде строки подключения. Они переопределят любые конфликтующие параметры командной строки.

Этот параметр называется --dbname для согласованности с другими клиентскими приложениями, но поскольку pg_receivewal не подключается ни к какой конкретной базе данных в кластере, любое имя базы данных, включенное в строку подключения, будет проигнорировано сервером. Однако указанное таким образом имя базы данных заменяет имя базы данных по умолчанию (replication) для поиска пароля репликационного подключения в файле ~/.pgpass. Аналогично, промежуточное ПО или прокси-серверы, используемые для подключения к PostgreSQL, могут использовать имя для таких целей, как маршрутизация соединений.

-h host
--host=host

Указывает хост компьютера, на котором запущен сервер. Значение по умолчанию берется из переменной окружения PGHOST. Если она не установлена, выполняется подключение к Unix-сокету (каталог Unix-сокета начинается с косой черты).

-p port
--port=port

Указывает TCP-порт или расширение файла локального Unix-сокета для подключения к серверу. Значение по умолчанию берется из переменной окружения PGPORT или задается при компиляции.

-U username
--username=username

Указывает имя пользователя для подключения.

-w
--no-password

Отключает запрос на ввод пароля. Если сервер требует аутентификации по паролю и пароль недоступен другими способами, такими как файл .pgpass, попытка подключения завершится неудачей. Параметр полезен в пакетных заданиях и сценариях, где нет пользователя, который мог бы ввести пароль.

-W
--password

Запрашивает пароль перед подключением к основному серверу.

Параметр не является обязательным, поскольку pg_receivewal автоматически запросит пароль, если сервер требует аутентификацию паролем. Однако утилита потратит попытку подключения, чтобы выяснить, что сервер хочет пароль. В некоторых случаях стоит ввести -W, чтобы избежать дополнительной попытки подключения.

--create-slot

Создает новый физический слот репликации с именем, указанным в --slot и завершает выполнение.

--drop-slot

Удаляет физический слот репликации с именем, указанным в --slot, и завершает выполнение.

-V
--version

Выводит версию pg_receivewal и завершается.

-?
--help

Показывает справку о параметрах командной строки утилиты pg_receivewal и завершается.

Код завершения

pg_receivewal завершает работу со следующими кодами завершения:

• Код 0 — при получении сигнала SIGINT, что считается нормальным завершением и не расценивается как ошибка.
• Ненулевой код — в случае фатальной ошибки или завершения по другим сигналам.

Переменные окружения

Утилита pg_receivewal использует переменные окружения, поддерживаемые libpq.

Переменная окружения PG_COLOR указывает, использовать ли цвет в диагностических сообщениях. Возможные значения — always, auto и never.

Примечания

Если pg_receivewal используется в качестве основного механизма архивирования WAL вместо archive_command или archive_library, рекомендуется задействовать слоты репликации. Без этого сервер может преждевременно удалить или перезаписать WAL-файлы, поскольку у него не будет сведений от archive_command, archive_library или репликационных слотов о том, какие данные уже заархивированы. Однако стоит учитывать, что при недостаточной скорости приема данных со стороны pg_receivewal, слот репликации может привести к заполнению дискового пространства на сервере.

Кроме того, при сохранении WAL-файлов pg_receivewal сохраняет групповые права доступа, если они были включены в исходном кластере.

Примеры

Передача журнала предзаписи с сервера на mydbserver и его хранение в локальном каталоге /usr/local/pgsql/archive:

$ pg_receivewal -h mydbserver -D /usr/local/pgsql/archive

Сотрите также

pg_basebackup