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.