pg_rewind

примечание

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

pg_rewind — синхронизирует каталог данных PostgreSQL с другим каталогом данных, который был создан из него.

Синтаксис

pg_rewind [option ...] {-D | --target-pgdata} directory {--source-pgdata=directory | --source-server=connstr}

Описание

pg_rewind — это инструмент для повторной синхронизации кластера PostgreSQL с другой копией того же кластера после расхождения их временных меток. Наиболее распространенный сценарий использования — возврат старого основного сервера в эксплуатацию после его сбоя, при этом он становится резервным сервером, синхронизированным с новым основным.

После успешной работы pg_rewind состояние целевого каталога данных становится эквивалентным новой базовой резервной копии от источника. Однако, в отличие от создания полноценной резервной копии или использования таких инструментов, как rsync, pg_rewind не затрагивает неизмененные блоки данных: из существующих файлов отношений копируются только измененные блоки, а все остальные файлы, включая новые файлы отношений, файлы конфигурации и сегменты WAL переносятся полностью. Благодаря этому pg_rewind выполняется гораздо быстрее, особенно при больших объемах данных и небольшом числе различий между кластерами.

Утилита анализирует историю временных меток целевого и исходного кластеров, чтобы найти точку расхождения, начиная с которой в каталоге pg_wal целевого сервера должны присутствовать соответствующие сегменты WAL. Эта точка может находиться как в текущей временной линии целевого или исходного сервера, так и у их общего предка. Обычно, если целевой сервер был остановлен вскоре после расхождения, необходимые файлы еще на месте. Но если он продолжал работу после расхождения, требуемые WAL-сегменты могли быть удалены. В этом случае можно вручную восстановить их из архива WAL или воспользоваться параметром -c, чтобы pg_rewind попытался загрузить их сам.

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

После завершения работы pg_rewind необходимо завершить процесс восстановления WAL-журнала. При запуске целевой сервер перейдет в режим восстановления и воспроизведет все изменения, зафиксированные на исходном сервере после последней контрольной точки перед расхождением. Если некоторые WAL-файлы не были доступны при запуске pg_rewind, они должны быть предоставлены при старте целевого сервера — для этого нужно создать файл recovery.signal и настроить параметр restore_command в конфигурационном файле postgresql.conf.

Для работы pg_rewind необходимо, чтобы в целевом кластере была либо активирован параметр wal_log_hints в postgresql.conf, либо включены контрольные суммы страниц при инициализации кластера (через initdb). По умолчанию ни одно из этих условий не выполняется, поэтому их нужно активировать вручную. Также требуется, чтобы параметр full_page_writes был установлен в значении on — включен по умолчанию.

Предупреждение!

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

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

Если pg_rewind обнаружит файлы, которые не может перезаписать (например, если оба сервера используют одни и те же файлы SSL-сертификатов в режиме только для чтения), он завершится ошибкой. В таких случаях рекомендуется предварительно удалить эти файлы на целевом сервере. После завершения pg_rewind некоторые файлы могут быть заново скопированы с исходного сервера, в этом случае может потребоваться удалить скопированные данные и восстановить ссылки/файлы, существовавшие до синхронизации.

Параметры

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

-D directory
--target-pgdata=directory

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

--source-pgdata=directory

Указывает путь к каталогу данных исходного сервера PostgreSQL. Сервер-источник должен быть корректно завершен перед использованием этого параметра.

--source-server=connstr

Задает строку подключения libpq для подключения к исходному серверу PostgreSQL. Подключение должно быть обычным (не репликацией) и выполняться от имени пользователя с достаточными правами для запуска необходимых функций pg_rewind (подробнее описано в разделе «Примечания»). В большинстве случаев требуется роль суперпользователя. Исходный сервер должен быть в рабочем состоянии и принимать соединения.

-R
--write-recovery-conf

Создает файл standby.signal и добавляет параметры подключения в postgresql.auto.conf в выходном каталоге. Использование этого параметра требует обязательного указания --source-server.

-n
--dry-run

Выполняет все этапы pg_rewind, кроме фактического изменения целевого каталога.

-N
--no-sync Завершает процесс pg_rewind без ожидания записи файлов на диск. Ускоряет выполнение, но при последующем сбое операционной системы может привести к повреждению каталога данных. По умолчанию утилита ждет полную синхронизацию данных с диском после копирования.

Параметр используется при тестировании и не предназначен для производственной среды.

-P
--progress

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

-c
--restore-target-wal

Восстанавливает WAL-файлы, отсутствующие в каталоге pg_wal целевого кластера, из архива WAL при необходимости, используя команду restore_command, определенную в конфигурации PostgreSQL целевого сервера.

--config-file=filename

Указывает основной конфигурационный файл PostgreSQL целевого кластера. Это влияет на поведение postgres, которую вызывает pg_rewind в процессе операции синхронизации в данном кластере (для получения restore_command при вызове с параметром -c/--restore-target-wal и для выполнения процедуры восстановления после сбоя).

--debug

Включает подробный отладочный вывод. Полезно для диагностики и разработки.

--no-ensure-shutdown

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

Параметр отключает такую автоматическую обработку: если сервер не был остановлен должным образом, pg_rewind немедленно завершит работу с ошибкой. В таком случае пользователь должен вручную завершить восстановление или выключить сервер.

--sync-method=method

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

На платформе Linux вместо syncfs можно использовать syncfs, чтобы попросить операционную систему синхронизировать всю файловую систему, содержащую каталог данных, файлы WAL и каждое табличное пространство..

Эта опция не оказывает влияния, если используется --no-sync.

-V
--version

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

-?
--help

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

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

Когда используется параметр --source-server, pg_rewind также использует переменные окружения, поддерживаемые libpq.

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

Примечания

При запуске pg_rewind с подключением к работающему кластеру в качестве источника, необязательно использовать суперпользователя. Достаточно роли с правами на выполнение определенных SQL-функций, необходимых для работы pg_rewind. Ниже пример создания такой роли — в данном случае она называется rewind_user:

CREATE USER rewind_user LOGIN;
GRANT EXECUTE ON function pg_catalog.pg_ls_dir(text, boolean, boolean) TO rewind_user;
GRANT EXECUTE ON function pg_catalog.pg_stat_file(text, boolean) TO rewind_user;
GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text) TO rewind_user;
GRANT EXECUTE ON function pg_catalog.pg_read_binary_file(text, bigint, bigint, boolean) TO rewind_user;

Как это работает

Суть работы pg_rewind — в синхронизации кластеров путем копирования различий на уровне файловой системы. Процесс включает следующие шаги:

1. Сначала сканируется WAL-журнал целевого кластера, начиная с последней контрольной точки, предшествующей расхождению временных линий с источником. Для каждой записи WAL фиксируются блоки, к которым был осуществлен доступ, чтобы определить, какие блоки были изменены после расхождения.

   Если нужные файлы WAL отсутствуют, можно повторно запустить pg_rewind с параметром -c для загрузки недостающих сегментов из архива WAL.

2. Определенные в предыдущем шаге измененные блоки копируются из источника в целевой кластер. Это выполняется либо напрямую через файловую систему (--source-pgdata), либо по SQL-протоколу (--source-server). В результате файлы отношений в целевом кластере будут соответствовать состоянию на момент последнего контрольного пункта до расхождения, с учетом всех изменений, произошедших на целевом сервере после этого момента.

3. Все остальные файлы, включая вновь созданные отношения, WAL-сегменты, содержимое pg_xact, а также конфигурационные файлы, также копируются из источника. Как и при создании базовой резервной копии, содержимое следующих каталогов не копируется: pg_dynshmem/, pg_notify/, pg_replslot/, pg_serial/, pg_snapshots/, pg_stat_tmp/, pg_subtrans/. Также исключаются файлы: backup_label, tablespace_map, pg_internal.init, postmaster.opts, postmaster.pid, а также все файлы и каталоги, начинающиеся с pgsql_tmp.

4. Создается файл backup_label, чтобы указать начало воспроизведения WAL с контрольной точки. Также обновляется файл pg_control, в который заносится LSN минимально согласованного состояния из:

   • pg_current_wal_insert_lsn() при подключении к работающему источнику;
   • LSN последней контрольной точки при использовании остановленного источника.

5. После запуска целевого кластера PostgreSQL воспроизводит все необходимые WAL-записи, в результате чего база данных приходит в полностью согласованное состояние.