F.26. pg_arman
F.26.1. Имя
pg_arman — менеджер резервного копирования и восстановления для Postgres Pro
F.26.2. Синтаксис
pg_arman [ OPTIONS ]
{ init |
backup |
restore |
show [ DATE | timeline ] |
validate [ DATE ] |
delete DATE }Здесь DATE задаёт время начала резервного копирования в формате ISO: (YYYY-MM-DD HH:MI:SS). Заданная дата сравнивается с именами файлов резервных копий как префикс.
F.26.3. Описание
pg_arman — это служебная программа для резервного копирования и восстановления базы данных Postgres Pro.
Она предоставляет следующие возможности:
Резервное копирование во время работы базы данных, включая табличные пространства, с помощью всего одной команды
Восстановление из резервной копии всего одной командой, с нестандартными вариантами, включая использование PITR.
Поддержка полного и дифференциального копирования + дифференциальное копирование ptrack
Управление резервными копиями со встроенными каталогами
F.26.4. Команды
pg_arman поддерживает следующие команды. Дополнительные подробности описаны в разделе Параметры.
init:
Инициализировать каталог резервных копий.backup:
Выполнить резервное копирование «на ходу».restore:
Выполнить восстановление.show:
Показать историю резервного копирования. С параметром timeline показывается линия времени резервной копии и линия времени родителя для каждой копии.validate:
Проверить файлы резервных копий.delete:
Удалить файлы резервных копий.
F.26.4.1. Инициализация
Сначала вы должны создать «каталог резервного копирования», в котором будут храниться файлы копий и их метаданные. До инициализации этого каталога рекомендуется настроить параметры archive_mode и archive_command в postgresql.conf. Если переменные инициализированы, pg_arman может скорректировать файл конфигурации. В этом случае вы должны задать путь к кластеру баз данных для Postgres Pro. Его можно задать в переменной окружения PGDATA или в параметре -D/--pgdata.
$ pg_arman init -B /path/to/backup/
F.26.4.2. Резервное копирование
Возможен один из следующих вариантов резервного копирования:
Полное резервное копирование, копируется весь кластер баз данных.
Дифференциальное резервное копирование: копируются только файлы или страницы, изменённые после последней проверенной копии. Для этого выполняется сканирование записей WAL от позиции последнего копирования до LSN выполнения pg_start_backup и все изменённые блоки записываются и отслеживаются как часть резервной копии. Так как просканированные сегменты WAL должны находиться в архиве WAL, последний сегмент, задействованный после запуска pg_start_backup, должен быть переключен принудительно.
Дифференциальная копия ptrack, использует файл битовой карты ptrack для отслеживания изменённых страниц. Чтобы использовать этот вариант, необходимо задать для параметра ptrack_enable значение "on".
После резервного копирования рекомендуется проверять файлы копий как только это будет возможно. Непроверенные копии нельзя использовать в операциях восстановления и резервного копирования.
F.26.4.3. Восстановление
Сервер Postgres Pro должен быть остановлен до начала восстановления. Если кластер баз данных всё ещё существует, команда восстановления сохранит незаархивированный журнал транзакций и удалит все файлы баз данных. После восстановления файлов pg_arman создаёт recovery.conf в $PGDATA. Этот конфигурационный файл содержит параметры для восстановления. Также возможно отредактировать этот файл вручную.
После успешного восстановления рекомендуется при первой же возможности сделать полную резервную копию.
Если ключ "--recovery-target-timeline" не задан, целевой линией восстановления будет TimeLineID последней контрольной точки в управляющем файле ($PGDATA/global/pg_control). Если файл pg_control отсутствует, целевой линией будет TimeLineID в полной резервной копии, используемой при восстановлении.
F.26.4.4. Примеры
Чтобы уменьшить число аргументов командной строки, вы можете установить в переменной окружения BACKUP_PATH абсолютный путь к каталогу резервного копирования и записать конфигурацию в файл {BACKUP_PATH}/pg_arman.ini.
$ cat $BACKUP_PATH/pg_arman.ini ARCLOG_PATH = /home/postgres/arclog BACKUP_MODE = FULL KEEP_DATA_GENERATIONS = 3 KEEP_DATA_DAYS = 120
F.26.4.5. Выполнение резервного копирования
Этот пример демонстрирует создание полной резервной копии всей базы данных с последующей проверкой всех непроверенных копий.
$ pg_arman backup --backup-mode=full $ pg_arman validate
F.26.4.6. Восстановление из резервной копии
Для восстановления базы из копии выполняется следующие команды:
$ pg_ctl stop -m immediate $ pg_arman restore $ pg_ctl start
F.26.4.7. Просмотр резервных копий
$ pg_arman show =================================================================================== Start Mode Current TLI Parent TLI Time Data Backup Status =================================================================================== 2013-12-25 03:02:31 PAGE 1 0 0m 203kB 67MB DONE 2013-12-25 03:02:31 PAGE 1 0 0m 0B 0B ERROR 2013-12-25 03:02:25 FULL 1 0 0m 33MB 364MB OK
Команда выводит следующие поля:
Start: время начала копирования
Mode: режим резервного копирования: FULL (полный) или PAGE (дифференциальный по страницам) или PTRACK (дифференциальный по ptrack)
Current TLI: текущая линия времени резервной копии
Parent TLI: родительская линия времени резервной копии
Time: время, потребовавшееся для выполнения создания резервной копии
Data: размер файлов данных
Log: размер прочитанных файлов журналов сервера
Backup: размер резервной копии (= записанный размер)
Status: состояние резервной копии. Возможные варианты:
OK: резервная копия сделана и проверена.
DONE: резервная копия сделана, но ещё не проверена.
RUNNING: резервная копия выполняется.
DELETING: резервная копия удаляется.
DELETED: резервная копия удалена.
ERROR: резервная копия недоступна, так как в процессе копирования произошли ошибки.
CORRUPT: резервная копия недоступна, так как она испорчена.
Когда указывается дата, выдаются дополнительные подробности о резервной копии:
$ pg_arman show '2011-11-27 19:15:45' # configuration BACKUP_MODE=FULL # result TIMELINEID=1 START_LSN=0/08000020 STOP_LSN=0/080000a0 START_TIME='2011-11-27 19:15:45' END_TIME='2011-11-27 19:19:02' RECOVERY_XID=1759 RECOVERY_TIME='2011-11-27 19:15:53' DATA_BYTES=25420184 BLOCK_SIZE=8192 XLOG_BLOCK_SIZE=8192 STATUS=OK
Вы можете определить "RECOVERY_XID" и "RECOVERY_TIME", которые будут использоваться для параметров восстановления "--recovery-target-xid", "--recovery-target-time".
Команда delete удаляет файлы резервных копий, не требующиеся для восстановления, после указанной даты. Эта команда также вычищает в архиве WAL все сегменты журналов, оказавшиеся ненужными для восстановления из оставшихся копий.
F.26.4.8. Параметры
pg_arman принимает следующие параметры командной строки. Некоторые из них могут также задаваться в переменных окружениях. Подробнее они описаны в разделе Параметры.
F.26.4.9. Общие параметры
Как правило, пути к данным должны задаваться как абсолютные; относительные пути не допускаются.
-D PATH / --pgdata=PATH:
Абсолютный путь кластера баз данных. Требуется при резервном копировании и восстановлении.
-A PATH / --arclog-path=PATH:
Абсолютный путь каталога архива WAL. Требуется для команд восстановления и просмотра.
-B PATH / --backup-path=PATH:
Абсолютный путь каталога резервного копирования. Этот параметр является обязательным.
-c / --check:
Если указывается, pg_arman не выполняет фактических действий, а только проверяет параметры и требуемые ресурсы. Этот параметр обычно используется с ключом --verbose для проверки корректности операции.
F.26.4.10. Параметры резервного копирования
-b BACKUPMODE / --backup-mode==BACKUPMODE:
Задаёт режим резервного копирования. Возможные варианты: "full", "page" или "ptrack".
-C1 / --smooth-checkpoint:
При каждом резервном копировании выполняется контрольная точка. Если задан этот параметр, выполняется «мягкая» контрольная точка. См. также описание второго аргумента pg_start_backup().
--validate:
Проверить резервную копию после её создания. Другие резервные копии, созданные ранее, игнорируются.
--keep-data-generations=NUMBER / --keep-data-days=DAYS:
Задаёт, как долго будут храниться скопированные файлы данных. Ключ --keep-data-generations задаёт число поколений копирования, а --keep-data-days — число дней, которое будет храниться данные. Удаляться будет только те файлы, для которых превышается одно из этих ограничений.
-j=NUMBER / --threads=NUMBER: Число потоков для процесса резервного копирования.
--stream: Включает потоковую репликацию для сохранения WAL в процессе резервного копирования.
--disable-ptrack-clear: Отключает очистку файлов ptrack для postgres без дополнения ptrack.
F.26.4.11. Параметры восстановления
Параметры с именами, начинающимися с --recovery, относятся к тем же параметрам, что и в recovery.conf.
--recovery-target-timeline=TIMELINE:
Устанавливает восстановление в определённую линию времени. Если не задано, используется текущая линия времени.
--recovery-target-time=TIMESTAMP:
Этот параметр задаёт отметку времени, до которой будет выполняться восстановление.
--recovery-target-xid=XID:
Этот параметр задаёт идентификатор транзакции, до которой будет выполняться восстановление.
--recovery-target-inclusive:
Указывает, будет ли сервер приостановлен по достижении цели восстановления.
-j=NUMBER / --threads=NUMBER: Число потоков для восстановления.
--stream: Восстановить без recovery.conf и использовать WAL в pg_xlog. Перед этим вы должны сделать резервную копию с ключом --stream. Этот параметр отключит все параметры --recovery-.
F.26.4.12. Параметры каталога
-a / --show-all:
Показать все существующие копии, включая удалённые.
F.26.4.13. Параметры подключения
Параметры для подключения к серверу Postgres Pro.
-d DBNAME / --dbname=DBNAME:
Имя базы данных, к которой нужно подключиться для выполнения pg_start_backup() and pg_stop_backup().
-h HOSTNAME / --host=HOSTNAME:
Указывает имя компьютера, на котором работает сервер. Если значение начинается с косой черты, оно определяет каталог Unix-сокета.
-p PORT / --port=PORT:
Указывает TCP-порт или расширение файла локального Unix-сокета, через который сервер принимает подключения.
-U USERNAME / --username=USERNAME:
Имя пользователя, под которым производится подключение.
-w / --no-password:
Не выдавать запрос на ввод пароля. Если сервер требует аутентификацию по паролю и пароль недоступен с помощью других средств, таких как файл .pgpass, попытка соединения не удастся. Этот параметр может быть полезен в пакетных заданиях и скриптах, где нет пользователя, который вводит пароль.
-W / --password:
Принудительно запрашивать пароль перед подключением к базе данных. Это несущественный параметр, так как pg_arman запрашивает пароль автоматически, если сервер проверяет подлинность по паролю. Однако, чтобы понять это, pg_arman лишний раз подключается к серверу. Поэтому иногда имеет смысл ввести -W, чтобы исключить эту ненужную попытку подключения.
F.26.4.14. Глобальные параметры
--help:
Показать справку, затем завершиться.
-V / --version:
Показать версию, затем завершиться.
-v / --verbose:
С этим ключом pg_arman при работе выводит подробные сообщения.
F.26.5. Параметры
Некоторые из этих параметров можно задать как аргументы командной строки, в переменных окружения или в файле конфигурации, следующим образом:
Short Long Env File
-h --host PGHOST No
-p --port PGPORT No
-d --dbname PGDATABASE No
-U --username PGUSER No
PGPASSWORD No
-w --password No
-W --no-password No
-D --pgdata PGDATA Yes
-B --backup-path BACKUP_PATH Yes
-A --arclog-path ARCLOG_PATH Yes
-b --backup-mode BACKUP_MODE Yes
-C --smooth-checkpoint SMOOTH_CHECKPOINT Yes
--validate VALIDATE Yes
--keep-data-generations KEEP_DATA_GENERATIONS Yes
--keep-data-days KEEP_DATA_DAYS Yes
--recovery-target-timeline RECOVERY_TARGET_TIMELINE Yes
--recovery-target-xid RECOVERY_TARGET_XID Yes
--recovery-target-time RECOVERY_TARGET_TIME Yes
--recovery-target-inclusive RECOVERY_TARGET_INCLUSIVE YesИмена переменных в файле конфигурации совпадают с длинными именами параметров и именами переменных окружения. Однако пароль нельзя задать в командной строке и файле конфигурации из соображений безопасности.
Эта утилита, как и большинство других утилит Postgres Pro, также использует переменные среды, поддерживаемые libpq (см. описание переменных окружения).
F.26.6. Ограничения
pg_arman имеет ряд ограничений, которые описаны ниже.
Требуется права чтения каталога баз данных и записи в каталог резервного копирования. Обычно для этого на сервере БД требуется смонтировать диск, где размещён каталог резервных копий, используя NFS или другую технологию.
Основные версии pg_arman и сервера должны совпадать.
Размеры блоков pg_arman и сервера должны совпадать.
Если в каталоге с журналами сервера или каталоге с архивом WAL оказываются нечитаемые файлы/каталоги, резервное копирование или восстановление завершится сбоем, вне зависимости от выбранного режима копирования.
F.26.7. Подробности
F.26.7.1. Восстановление на момент времени
pg_arman может произвести восстановление на момент времени, если в recovery.conf задаётся линия времени и идентификатор транзакции или время. Чтобы определить момент для восстановления, может быть полезен дополнительный модуль xlogdump, входящий в основной набор модулей Postgres Pro и позволяющий просматривать содержимое файлов WAL.
F.26.7.2. Файл конфигурации
Установка параметров в файле конфигурации выполняется в виде "имя=значение". Кавычки требуются, если значение содержит пробелы. Комментарии начинаются с "#" и автоматически игнорируются при разборе. Пробелы и табуляции игнорируются везде, кроме содержимого значений.
F.26.7.3. Ограничения
Чтобы pg_arman работал, в экземпляре Postgres Pro, в котором выполняются резервное копирование, должны быть включены контрольные суммы данных или параметр wal_log_hints.
pg_arman рассчитан на работу с Postgres Pro 9.5 и более новыми версиями.
Для использования функции ptrack потребуется особая версия Postgres и уровень wal_level, равный archive или hot_standby; также необходимо включить параметр ptrack_enable.
Для трансляции потока вы должны настроить потоковую репликацию на вашем сервере Postgres Pro.
F.26.7.4. Код ошибки
pg_arman возвращает следующие коды выхода для различных состояний ошибок.
Код Имя Описание 0 SUCCESS Операция успешна 1 ERROR Общая ошибка 2 FATAL Выход из-за повторяющихся ошибок 3 PANIC Необрабатываемое критическое состояние
F.26.8. Автор
pg_arman — это ответвление проекта pg_arman, изначально разрабатываемого в NTT. Теперь его разрабатывает и поддерживает Микаэль Пакье. Потоки, поддержка дифференциальных копий с WAL и ptrack, поддержка трансляции WAL и некоторые другие функции разработал Юрий Журавлёв (stalkerg) из компании PostgresPro.
Пожалуйста сообщайте об ошибках на странице https://github.com/postgrespro/pg_arman/issues.