pg_basebackup

примечание

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

pg_basebackup — создает резервную копию кластера баз данных PostgreSQL.

Синтаксис

pg_basebackup [option...]

Описание

pg_basebackup — утилита для создания базовой резервной копии кластера баз данных PostgreSQL без влияния на другие клиентские соединения. Используется как для восстановления до заданной точки во времени (подробнее описано в разделе «Непрерывное архивирование и восстановление до заданной точки во времени (PITR)»), так и в качестве отправной точки для резервного сервера с логической передачей или потоковой репликацией (подробнее описано в разделе «Резервные серверы с передачей журналов»).

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

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

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

Состояние процесса резервного копирования отображается в представлении pg_stat_progress_basebackup.

Резервное копирование с основного сервера

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

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

Резервное копирование с резервного сервера

Утилита pg_basebackup позволяет создавать резервную копию с резервного сервера.

Чтобы создать базовую резервную копию с резервного сервера с помощью pg_basebackup, необходимо:

1. Настроить резервный сервер на прием подключений для репликации:

   • установить параметр max_wal_senders на соответствующее значение;
   • включить параметр hot_standby;
   • скорректировать настройки доступа в pg_hba.conf.

2. Включить параметр full_page_writes на основном сервере.

При создании резервной копии с резервного сервера существуют ограничения:

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

Параметры

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

-D directory
--pgdata=directory

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

Для указания целевого каталога необходимо учитывать следующие условия:

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

-F format
--format=format

Выбирает формат вывода.

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

p
plain : Стандартные файлы c исходной структурой каталогов данных и табличных пространств. Если в кластере отсутствуют дополнительные табличные пространства, вся база данных будет сохранена в указанный каталог. Иначе основной каталог данных будет помещен в целевой каталог, а остальные табличные пространства сохранятся в тех же абсолютных путях, что и на исходном сервере. Для изменения этих путей используйте параметр --tablespace-mapping.

Формат используется по умолчанию.

t
tar : Файлы в формате tar в целевом каталоге. Основной каталог данных сохраняется в файле base.tar, а каждое дополнительное табличное пространство — в отдельном файле, в названии которого указывается OID соответствующего пространства.

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

-i old_manifest_file
--incremental=old_manifest_file

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

-R
--write-recovery-conf

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

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

-t targ
-target
--target=target

Указывает серверу место хранения базовой резервной копии.

Возможные значения параметра и их действия:

• client — сохранение копии на той же машине, где используется pg_basebackup, значение по умолчанию.
• server:/some/path — сохранение копии на сервере в каталоге /some/path. Требуются права супервользователя или роль pg_write_server_files.
• blackhole — режим для тестирования, фактическая резервная копия копия не создается.

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

-T olddir=newdir
--tablespace-mapping=olddir=newdir

Перемещает табличное пространство из olddir в newdir в процессе копирования.

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

Путь newdir указывает на каталог в файловой системе резервного сервера (может не существовать, но если он существует, должен быть пустым).

olddir и newdir должны иметь абсолютные пути. Если в пути встречается знак =, необходимо использовать символ «\» для экранирования. Параметр можно использовать несколько раз для разных табличных пространств.

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

Параметр работает только с форматом вывода plain (игнорируется при использовании tar).

--waldir=waldir

Устанавливает каталог для записи WAL файлов (журнал предзаписи). По умолчанию файлы записываются в подкаталог pg_wal целевого каталога.

Путь waldir должен быть абсолютным, если каталог отсутствует, то он будет создан (если существует — он должен быть пустым).

Параметр работает только с форматом вывода plain.

-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 level
-Z [{client|server}-]method[:detail]
--compress=level
--compress=[{client|server}-]method[:detail]

Запрашивает сжатие резервной копии.

Префикс client или server указывает, где должно выполняться сжатие:

• на сервере уменьшает объем передаваемых данных, но увеличивает нагрузку на процессор сервера;
• на клиенте используется по умолчанию.

Если указан параметр --target, резервная копия не передается клиенту, поэтому сжатие выполняется на стороне сервера.

В режиме -Xstream (используется по умолчанию) сжатие на стороне сервера не применяется к журналу предзаписей (чтобы сжать WAL, необходимо либо применить сжатие на стороне клиента, либо использовать режим -Xfetch).

Метод сжатия может быть задан как gzip, lz4, zstd, none для отсутствия сжатия или целое число (без сжатия, если 0, gzip, если больше 0). Строка детализации сжатия может дополнительно задаваться. Если строка детализации представляет собой целое число, оно определяет уровень сжатия. Иначе она должна представлять собой список элементов, разделенных запятыми, каждый элемент которого имеет вид keyword или keyword=value. На текущий момент поддерживаемые ключевые слова: level, long и workers. Строка детализации не может быть использована, если метод сжатия указан просто как целое число.

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

При использовании формата tar с методами сжатия gzip, lz4 или zstd, ко всем именам tar-файлов автоматически добавляется суффикс .gz, .lz4 или .zst, соответственно. При использовании формата plain сжатие выполняется только на стороне сервера. Сервер сжимает копию для передачи, а клиент распаковывает и извлекает данные из нее.

В режиме -Xstream pg_wal.tar будет сжат методом gzip, если выбрано сжатие gzip на стороне клиента, и не будет сжат, если выбран другой метод сжатия или сжатие происходит на стороне сервера.

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

Устанавливает режим контрольных точек:

• fast (быстрый);
• spread (протяженный, по умолчанию).

-C
--create-slot

Создает слот репликации до начала резервного копирования. Имя слота репликации берется из параметра --slot (выдается ошибка, если такой слот уже существует).

-l label
--label=label

Задает метку для создания резервной копии. По умолчанию имеет значение pg_basebackup base backup.

-n
--no-clean

Отключает очистку созданных каталогов.

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

-N
--no-sync

Записывает файлы на диск без ожидания.

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

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

-P
--progress

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

-r rate
--max-rate=rate

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

Значение задается в килобайтах в секунду, при добавлении суффикса M задается значение в мегабайтах (суффикс k допустим, но не имеет эффекта). Допустимые значения опции в диапазоне от 32 КБ/с до 1024 МБ/с.

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

-S slotname
--slot=slotname

Указывает слот репликации для передачи WAL. Применяется только с режимом -Xstream.

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

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

--sync-method=method

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

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

Этот параметр не имеет эффекта при использовании --no-sync.

-v
--verbose

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

--manifest-checksums=algorithm

Задает алгоритм подсчета контрольных сумм. Для всех файлов в манифесте копии, будут подсчитываться контрольные суммы с использованием одного из следующих алгоритмов: 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 connstr
--dbname=connstr

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

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

-h host
--host=host

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

-p port
--port=port

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

-s interval
--status-interval=interval

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

-U username
--username=username

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

-w
--no-password

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

-W
--password

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

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

-V
--version

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

-?
--help

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

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

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

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

Примечания

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

Резервная копия будет включать все файлы в каталоге данных и табличных пространствах, включая файлы конфигурации и любые дополнительные файлы, помещенные в каталог третьими лицами, за исключением определенных временных файлов, управляемых PostgreSQL. Но копируются только обычные файлы и каталоги, за исключением того, что символические ссылки, используемые для табличных пространств, сохраняются. Символические ссылки, указывающие на определенные каталоги, известные PostgreSQL, копируются как пустые каталоги. Другие символические ссылки и специальные файлы устройств пропускаются. Подробнее об этом можно ознакомится в разделе «Протокол потоковой репликации».

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

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

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

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

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

pg_dump, «Отчет о прогрессе VACUUM»