pg_basebackup

pg_basebackup — создать резервную копию кластера Postgres Pro

Синтаксис

pg_basebackup [параметр...]

Описание

Программа pg_basebackup предназначена для создания базовых копий работающего кластера баз данных Postgres Pro. Процедура создания копии не влияет на работу других клиентов базы. Полученные копии могут использоваться и для восстановления на момент времени (см. Раздел 24.3), и в качестве базового состояния ведомого сервера при реализации трансляции журнала или потоковой репликации (см. Раздел 25.2).

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

Копия создаётся через обычное подключение к Postgres Pro, и при этом используется протокол репликации. Соединение с сервером должен устанавливать пользователь с правом REPLICATION (см. Раздел 20.2) или суперпользователь, а в pg_hba.conf должно разрешаться подключение для репликации. Кроме того, на сервере должно быть установлено достаточно большое значение max_wal_senders, чтобы мог запуститься минимум один передатчик WAL для резервного копирования и ещё один для потоковой трансляции WAL (если она применяется).

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

С помощью pg_basebackup можно получить базовую копию не только с ведущего, но и с ведомого сервера. Чтобы сделать копию с ведомого, настройте его, чтобы он мог принимать подключения репликации (для этого нужно установить подходящие значения max_wal_senders, hot_standby и подкорректировать pg_hba.conf). При этом на ведущем необходимо также включить full_page_writes.

Заметьте, что при копировании с ведомого сервера есть некоторые ограничения:

  • Файл истории резервного копирования в целевом кластере баз данных не создаётся.

  • pg_basebackup не может принудительно переключить ведомый сервер на новый файл WAL в конце копирования. Поэтому, если используется режим -X none и активность записи на ведущем сервере низкая, pg_basebackup может довольно долго ждать переключения и архивирования последнего файла WAL, необходимого для полноты копии. В этом случае может иметь смысл выполнить на ведущем сервере pg_switch_wal для немедленного переключения файла WAL.

  • Если ведомый сервер повышается и становится ведущим в процессе копирования, копирование прерывается.

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

Когда pg_basebackup создаёт базовую копию, в представлении pg_stat_progress_basebackup отображается состояние этого процесса. За подробностями обратитесь к Подразделу 26.4.6.

Параметры

Следующие аргументы командной строки задают расположение и формат вывода:

-D каталог
--pgdata=каталог

Целевой каталог, куда будет записана копия. Если он не существует, pg_basebackup создаст его, а также отсутствующие родительские каталоги, при необходимости. Если он существует, он должен быть пустым.

Если копия создаётся в формате tar, в качестве целевого каталога можно задать - (минус), и тогда файл tar будет записан в stdout.

Этот флаг является обязательным.

-F формат
--format=формат

Устанавливает формат вывода. формат может принимать следующие значения:

p
plain

Записывает выводимые данные в обычные файлы, сохраняя структуру каталогов данных и табличных пространств как на исходном сервере. Если в кластере нет дополнительных табличных пространств, вся база будет помещена в заданный каталог. Иначе основной каталог хранения данных будет помещён в целевой каталог, а все остальные табличные пространства — в те же абсолютные пути, в которых они располагаются на исходном сервере. (Чтобы изменить эти пути, воспользуйтесь параметром --tablespace-mapping).

Это формат по умолчанию.

t
tar

Записывает в целевой каталог файлы в формате tar. Содержимое основного каталога данных будет записано в файл base.tar, а каждое дополнительное табличное пространство — в отдельный файл, содержащий в имени OID этого пространства.

Если в качестве имени целевого каталога задано - (минус), содержимое tar будет записано в устройство стандартного вывода, что позволяет, например, передать его программе gzip. Это возможно, только если в кластере нет дополнительных табличных пространств и не используется трансляция WAL.

-R
--write-recovery-conf

Создать файл standby.signal и добавить параметры конфигурации в файл postgresql.auto.conf в целевом каталоге (или внутри архива, если используется формат tar). Это упрощает настройку ведомого сервера при восстановлении этой копии.

В файл postgresql.auto.conf будут записаны параметры соединения и слот репликации, если его использует pg_basebackup, так что впоследствии при потоковой репликации будут использоваться те же параметры.

-t получатель
--target=получатель

Указывает серверу, куда отправлять созданную копию. Получателем по умолчанию является client, то есть резервная копия будет отправлена на компьютер, где работает pg_basebackup. Если же в качестве получателя установлено server:/some/path, резервная копия будет сохранена на компьютере, где работает сервер, в каталоге /some/path. Для сохранения резервной копии на сервере требуются права суперпользователя или роли pg_write_server_files. Если в качестве получателя указать blackhole, содержимое копии отправляется в «чёрную дыру» и нигде не сохраняется. Этот вариант следует использовать только в целях тестирования, так как собственно резервной копии вы не получите.

Так как приём потока WAL реализован в pg_basebackup, а не на стороне сервера, этот параметр нельзя использовать вместе с -Xstream. Так как режим -Xstream используется по умолчанию, указывая данный параметр, необходимо также указать либо -Xfetch, либо -Xnone.

-T старый_каталог=новый_каталог
--tablespace-mapping=старый_каталог=новый_каталог

Переместить табличное пространство из старого_каталога в новый_каталог в процессе копирования. Чтобы перемещение произошло, в параметре старый_каталог путь табличного пространства должен задаваться в точности так, как он определён на исходном сервере. (Но не будет ошибкой, если на исходном сервере не окажется табличного пространства, на которое указывает старый_каталог.) В то же время, новый_каталог задаёт путь в файловой системе получающего сервера. Как и основной целевой каталог, новый_каталог может не существовать, но если он существует, он должен быть пустым. И старый_каталог, и новый_каталог должны задаваться абсолютными путями. Если в пути встречается символ =, его необходимо экранировать обратной косой чертой. Этот параметр можно добавить несколько раз для нескольких табличных пространств.

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

В настоящее время этот параметр работает только с обычным форматом вывода; если выбран формат tar, параметр игнорируется.

--waldir=каталог_wal

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

-X method
--wal-method=method

Включает в резервную копию все необходимые файлы журнала предзаписи (файлы WAL). В том числе включаются все файлы журнала, сгенерированные в процессе создания резервной копии. Любой метод, кроме none, позволяет запустить сервер с восстановленным каталогом, не используя архив WAL; таким образом будет получена полностью самодостаточная резервная копия.

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

n
none

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

f
fetch

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

Когда используется формат tar, файлы журнала предзаписи включаются в архив base.tar.

s
stream

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

Когда используется формат tar, файлы журнала предзаписи сохраняются в отдельном архиве с именем pg_wal.tar (если версия сервера ниже 10, файл будет называться pg_xlog.tar).

Это значение по умолчанию.

-z
--gzip

Включает gzip-сжатие выводимого tar-файла с уровнем компрессии по умолчанию. Сжатие поддерживается только для формата tar, при этом ко всем именам файлов tar добавляется суффикс .gz.

-Z уровень
-Z [{client|server}-]method[:дополнительная_информация]
--compress=уровень
--compress=[{client|server}-]method[:дополнительная_информация]

Запрашивает сжатие резервной копии. Если добавляется префикс client или server, он указывает, где должно выполняться сжатие. Когда сжатие выполняет сервер, объём передаваемых данных уменьшается, но увеличивается нагрузка на процессор сервера. По умолчанию используется client, за исключением случаев, когда используется ключ --target. В этих случаях резервная копия не передаётся клиенту, поэтому смысл имеет только сжатие на стороне сервера. В режиме -Xstream (выбираемом по умолчанию) сжатие на стороне сервера не распространяется на WAL. Чтобы WAL сжимался, примените сжатие на стороне клиента или используйте режим -Xfetch.

В качестве метода сжатия можно выбрать gzip, lz4, zstd, none без сжатия или целое число (если задать 0 — без сжатия, если больше нуля — gzip). В качестве дополнительной информации можно передать параметры сжатия. Если в строке информации передаётся целое число, оно задаёт уровень сжатия. В противном случае она должна содержать список элементов, разделённых запятыми, в форме ключевое_слово или ключевое_слово=значение. На данный момент поддерживаются ключевые слова level, long и workers. Если метод сжатия задан целым числом, строку информации использовать нельзя.

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

Когда формат tar сжимается методом gzip, lz4 или zstd, ко всем именам файлов tar автоматически добавляется суффикс .gz, .lz4 или .zst соответственно. Когда используется простой формат, сжатие на стороне клиента выполнить нельзя, но при этом можно запросить сжатие на стороне сервера. В таком случае сервер будет сжимать копию для передачи, а клиент будет распаковывать и извлекать из неё данные.

Когда этот параметр используется в сочетании с -Xstream, pg_wal.tar будет сжат методом gzip, если выбрано сжатие gzip на стороне клиента, и не будет сжат, если выбран любой другой алгоритм сжатия или выбрано сжатие на стороне сервера.

Описанные далее аргументы командной строки управляют формированием резервной копии и вызовом программы:

-c {fast|spread}
--checkpoint={fast|spread}

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

-C
--create-slot

Указывает, что до начала копирования должен быть создан слот репликации с именем, заданным в --slot. Если такой слот уже существует, выдаётся ошибка.

-l метка
--label=метка

Устанавливает метку для созданной резервной копии. Если не указана, то по умолчанию будет использовано значение «pg_basebackup base backup».

-n
--no-clean

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

Заметьте, что каталоги табличных пространств не очищаются в любом случае.

-N
--no-sync

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

-P
--progress

Включает отчёт о прогрессе. Если этот режим включён, то во время создания копии будет передаваться примерный процент выполнения. Так как данные в базе могут меняться во время копирования, это значение будет лишь приближённым и может достигать не точно 100%. В частности, когда в копию включается журнал WAL, конечный размер невозможно предсказать заранее, и в этом случае ожидаемый конечный размер будет увеличиваться, превысив ориентировочный полный размер без WAL.

-r скорость_передачи
--max-rate=скорость_передачи

Задаёт максимальную скорость, с которой данные будут загружаться с исходного сервера. Это может быть полезно для ограничения влияния pg_basebackup на сервер. Значение параметра задаётся в килобайтах в секунду. Для указания мегабайт в секунду нужно добавить к числу суффикс M. Так же принимается суффикс k, но он ничего не меняет. Допустимые значения лежат в диапазоне от 32 КБ/с до 1024 МБ/с.

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

-S имя_слота
--slot=имя_слота

Этот параметр может применяться только вместе с -X stream. Он выбирает слот репликации, который будет использоваться для передачи WAL. Если базовая копия предназначена для использования на ведомом сервере с потоковой репликацией через слот, это же имя слота должно задаваться на ведомом в качестве primary_slot_name. Тем самым гарантируется, что ведущий сервер не удалит никакие необходимые данные WAL после того, как базовая копия будет получена, и до того, как начнётся потоковая репликация на новом ведомом.

В случае отсутствия ключа -C требуется, чтобы указанный слот репликации уже существовал.

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

-v
--verbose

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

--manifest-checksums=алгоритм

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

Если выбран вариант NONE, манифест копии не будет содержать контрольные суммы. С любым другим вариантом в манифест будет записана контрольная сумма каждого файла в копии, рассчитанная по выбранному алгоритму. Помимо этого, в манифесте всегда сохраняется контрольная сумма его содержимого, рассчитанная по алгоритму SHA256. Алгоритмы семейства SHA требуют значительно больше процессорных ресурсов, чем CRC32C, поэтому выбор такого алгоритма может повлечь увеличение времени создания копии.

Функции хеширования SHA обеспечивают криптографическую стойкость хеша каждого файла, и таким образом полезны, когда нужны гарантии, что резервная копия не была модифицирована. С другой стороны, алгоритм CRC32C вычисляет контрольную сумму гораздо быстрее и вполне подходит для выявления изменений, внесённых не злонамеренно, а случайно. Заметьте, что такая защита от злоумышленника, имеющего доступ к сохранённой копии, будет эффективна, только если манифест копии хранится отдельно в безопасном месте или ещё каким-то образом проверяется, что манифест не был изменён с момента создания копии.

Для проверки целостности копии по созданному манифесту можно воспользоваться программой pg_verifybackup.

--manifest-force-encode

Принудительно включает шестнадцатеричное кодирование всех имён файлов в манифесте. Если этот параметр не задаётся, в шестнадцатеричном виде кодируются только имена файлов не в кодировке UTF-8. Этот параметр в первую очередь предназначен для проверки того, что средства чтения манифеста могут правильно разобрать такие имена.

--no-estimate-size

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

Без этого указания процесс копирования начнётся с перечисления файлов для подсчёта размера всей базы данных, а затем продолжится отправкой непосредственно данных. Это может немного увеличить общую длительность процесса, в частности, пройдёт больше времени до начала передачи данных. Данный параметр полезен, когда время расчёта объёма оказывается слишком большим.

Этот параметр нельзя использовать вместе с параметром --progress.

--no-manifest

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

--no-slot

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

По умолчанию, если выбрана передача журнала, но имя слота в -S не задано, создаётся временный слот репликации (при условии, что это поддерживает исходный сервер).

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

--no-verify-checksums

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

По умолчанию контрольные суммы проверяются, и при выявлении их несоответствия выдаётся ненулевой код завершения. Однако базовая резервная копия в этом случае не удаляется, как и с ключом --no-clean. Ошибки контрольных сумм также можно просмотреть в представлении pg_stat_database.

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

-d строка_подключения
--dbname=строка_подключения

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

Параметр называется --dbname для согласованности с другими клиентскими приложениями, но так как pg_basebackup не подключается к какой-либо конкретной базе, любое имя базы данных в строке подключения игнорируется.

-h сервер
--host=сервер

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

-p порт
--port=порт

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

-s interval
--status-interval=interval

Указывает интервал в секундах между сообщениями о состоянии, передаваемыми исходному серверу. Чем меньше указанное значение, тем точнее будет информация о процессе резервного копирования на сервере. Нулевое значение полностью отключает периодическое обновление состояния, хотя эти сообщения будут всё равно посылаться по запросу сервера во избежание отключения по тайм-ауту. Значение по умолчанию — 10 секунд.

-U имя_пользователя
--username=имя_пользователя

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

-w
--no-password

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

-W
--password

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

Это несущественный параметр, так как pg_basebackup запрашивает пароль автоматически, если сервер проверяет подлинность по паролю. Однако чтобы понять это, pg_basebackup лишний раз подключается к серверу. Поэтому иногда имеет смысл ввести -W, чтобы исключить эту ненужную попытку подключения.

Другие флаги:

-V
--version

Вывести версию pg_basebackup и завершиться.

-?
--help

Вывести справку по аргументам командной строки pg_basebackup и завершиться.

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

Как и большинство других утилит Postgres Pro, приложение также использует переменные окружения, поддерживаемые libpq (см. Раздел 32.15).

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

Примечания

До начала копирования на исходном сервере необходимо выполнить контрольную точку. И если копирование запускается без ключа --checkpoint=fast, это может занять некоторое время, в течение которого pg_basebackup не будет проявлять никакой активности.

Резервная копия будет включать в себя все файлы каталога хранения данных и табличных пространств, а также конфигурационные файлы и прочие файлы, размещённые в каталоге данных, за исключением определённых временных файлов, принадлежащих Postgres Pro. Однако копируются лишь простые файлы и каталоги, кроме них, сохраняются только символические ссылки на табличные пространства. Символические ссылки, указывающие на определённые каталоги, известные Postgres Pro, копируются как пустые каталоги. Другие символические ссылки и файлы спецустройств игнорируются. За дополнительными подробностями обратитесь к Разделу 53.4.

Если не указан параметр --tablespace-mapping, в простом формате табличные пространства будут копироваться в тот же путь, который они имеют на исходном сервере. Поэтому при наличии табличных пространств создать базовую копию в простом формате на том же сервере не удастся, так как копия будет направлена в те же каталоги, где располагаются исходные табличные пространства.

Когда применяется формат tar, пользователь должен позаботиться о том, чтобы все архивы tar были распакованы до запуска сервера Postgres Pro, который будет работать с этими данными. Если имеются дополнительные табличные пространства, архивы tar для них должны быть распакованы в правильные каталоги. В таком случае для этих табличных пространств сервером будут созданы символические ссылки согласно содержимому файла tablespace_map, включённого в архив base.tar.

pg_basebackup совместим с серверами той же или более младших версий, но не ниже версии 9.1. Однако режим трансляции WAL (-X stream) работает только с серверами версии 9.3 и новее, а формат tar (--format=tar) поддерживается только с версиями не ниже 9.5.

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

Примеры

Создание резервной копии сервера mydbserver и сохранение её в локальном каталоге /usr/local/pgsql/data:

$ pg_basebackup -h mydbserver -D /usr/local/pgsql/data

Создание резервной копии локального сервера в отдельных сжатых файлах tar для каждого табличного пространства и сохранение их в каталоге backup с индикатором прогресса в процессе выполнения:

$ pg_basebackup -D backup -Ft -z -P

Создание резервной копии локальной базы данных с одним табличным пространством и сжатие её с помощью bzip2:

$ pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2

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

Создание резервной копии локальной базы данных с перемещением табличного пространства /opt/ts в ./backup/ts:

$ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts

Создание резервной копии локального сервера в отдельных сжатых файлах tar для каждого табличного пространства (при этом используется метод сжатия gzip и уровень сжатия 9) и сохранение их в каталоге backup:

$ pg_basebackup -D backup -Ft --compress=gzip:9