Перейти к основному содержимому

pg_upgrade. Обновление данных без их дампа или восстановления

Версия: 15.5 (собственной версии нет, соответствует версии ядра).

В исходном дистрибутиве установлено по умолчанию: да.

Связанные компоненты: отсутствуют.

pg_upgrade позволяет обновлять данные, хранящиеся в файлах данных PostgreSQL, до более поздней основной версии PostgreSQL без дампа/восстановления данных, обычно требуемых для обновления основных версий, например, с 9.5.8 до 9.6.4 или с 10.7 до 11.2. Это не требуется для незначительных обновлений версий, например, с 9.6.2 до 9.6.3 или с 10.1 до 10.2.

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

pg_upgrade делает все возможное, чтобы убедиться, что старые и новые кластеры являются двоично-совместимыми, например, проверяя совместимые настройки компиляции времени, включая 32-разрядные/64-разрядные двоичные файлы. Важно, чтобы любые внешние модули также были двоично-совместимы, хотя это не может быть проверено с помощью pg_upgrade.

Утилита поддерживает обновления с версии 9.2.X и выше до текущей основной версии PostgreSQL, включая моментальные снимки и бета-версии.

Доработка​

Доработка не проводилась.

Ограничения​

Ограничения отсутствуют.

Установка​

Устанавливается по умолчанию с ядром PostgreSQL, дополнительных действий не треубется.

Настройка​

pg_upgrade принимает следующие аргументы командной строки:

  • -b каталог_bin, --old-bindir=каталог_bin - каталог с исполняемыми файлами старой версии PostgreSQL; переменная окружения PGBINOLD;

  • -B каталог_bin, --new_bindir=каталог_bin - каталог с исполняемыми файлами новой версии PostgreSQL, по умолчанию это каталог, в котором располагается pg_upgrade; переменная окружения PGBINNEW;

  • -c, --check - только проверить кластеры, не изменять никакие данные;

  • -d каталог_конфигурации, --old-datadir=каталог_конфигурации - каталог конфигурации старого кластера; переменная окружения PGDATAOLD;

  • -D каталог_конфигурации, --new-datadir=каталог_конфигурации - каталог конфигурации нового кластера; переменная окружения PGDATANEW;

  • -j число_заданий, --jobs=число_заданий - число одновременно задействуемых процессов или потоков;

  • -k, --link - использовать жесткие ссылки вместо копирования файлов в новый кластер;

  • -l, --log-path - опция для изменения директории логирования pg_upgrade;

  • -N, --no-sync - по умолчанию, pg_upgrade будет ждать, пока все файлы обновленного кластера будут безопасно записаны на диск. Эта опция заставляет pg_upgrade вернуться без ожидания, что быстрее, но означает, что последующий сбой операционной системы может привести к повреждению каталога данных. В целом, эта опция полезна для тестирования, но не должна использоваться в производственной установке;

  • -o опции, --old-options опции - опции, которые должны быть переданы непосредственно команде старого postgres; несколько вызовов параметров добавляются;

  • -O опции, --new-options опции - параметры, которые должны быть переданы непосредственно новой команде postgres; несколько вызовов параметров добавляются;

  • -p порт, --old-port=порт - старый номер порта кластера; переменная среды PGPORTOLD;

  • -P порт, --new-port=порт - новый номер порта кластера; переменная среды PGPORTNEW;

  • -r, --retain - сохранять файлы SQL и журнала даже после успешного завершения;

  • -s директория, --socketdir=директория - директория для использования сокетов postmaster во время обновления; по умолчанию используется текущая рабочая директория; переменная окружения PGSOCKETDIR;

  • -U username, --username=username - имя пользователя установщика кластера; переменная окружения PGUSER;

  • -v, --verbose - включить подробное внутреннее ведение журнала;

  • -V, --version - отобразите информацию о версии, затем выйдите;

  • --clone - использование эффективного клонирования файлов (также известного как «reflinks» в некоторых системах) вместо копирования файлов в новый кластер. Это может обеспечить практически мгновенное копирование файлов данных, обеспечивая преимущества скорости -k/--link, при этом оставляя старый кластер нетронутым.

    Примечание:

    Клонирование файлов поддерживается только в некоторых операционных системах и файловых системах. Если оно выбрано, но не поддерживается, выполнение pg_upgrade завершится ошибкой. В настоящее время это поддерживается в Linux (ядро 4.5 или более поздней версии) с использованием Btrfs и XFS (в файловых системах, созданных с поддержкой reflink), а также в macOS с APFS.

  • -?, --help - показать справку, затем выйти.

Использование модуля​

Обновление с помощью утилиты​

  1. При использовании каталога установки, специфичного для версии, например, /opt/PostgreSQL/15, не нужно перемещать старую группу. Все графические установщики используют каталоги установки, специфичные для версий.

Если каталог установки не является специфичным для версии, например, /usr/local/pgsql, необходимо переместить текущий каталог установки PostgreSQL, чтобы он не мешал новой установке PostgreSQL. После того, как сервер текущей PostgreSQL будет остановлен, можно безопасно переименовать каталог установки PostgreSQL; предполагая, что старый каталог /usr/local/pgsql, для переименования каталога вызовите:

mv /usr/local/pgsql /usr/local/pgsql.old

  1. Для установок из исходного кода создайте новую версию, собрав новый источник PostgreSQL с флагами configure, совместимыми со старым кластером. Утилита pg_upgrade проверит pg_controldata, чтобы убедиться, что все настройки совместимы перед началом обновления.

  2. Установите новые серверные двоичные файлы PostgreSQL и файлы поддержки. pg_upgrade включен в установку по умолчанию.

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

    make prefix=/usr/local/pgsql.new install

  3. Инициализируйте новый кластер с использованием initdb. Снова используйте совместимые флаги initdb, которые соответствуют старому кластеру. Многие предустановленные установщики выполняют этот шаг автоматически. Нет необходимости запускать новый кластер.

  4. Многие расширения и пользовательские модули, будь то из contrib или другого источника, используют общие объектные файлы (или DLL-файлы), например, pgcrypto.so. Если старый кластер использовал эти файлы, общие объектные файлы, соответствующие новому двоичному файлу сервера, должны быть установлены в новом кластере, обычно через команды операционной системы. Не загружайте определения схемы, например, CREATE EXTENSION pgcrypto, так как они будут продублированы из старого кластера. Если доступны обновления расширений, pg_upgrade сообщит об этом и создаст сценарий, который можно будет запустить позже для их обновления.

  5. Скопируйте любые пользовательские файлы полнотекстового поиска (словарь, синонимы, тезаурус, стоп-слова) со старого кластера на новый.

  6. pg_upgrade будет подключаться к старым и новым серверам несколько раз, поэтому настраивайте аутентификацию на peer в pg_hba.conf или используйте файл ~/.pgpass.

  7. Убедитесь, что оба сервера баз данных остановлены с использованием, например, в Unix:

    pg_ctl -D /opt/PostgreSQL/9.6 stop
    pg_ctl -D /opt/PostgreSQL/15 stop

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

  8. Запустите pg_controldata против старых основных и резервных кластеров. Убедитесь, что значения "Местоположение последней контрольной точки" совпадают во всех кластерах. Также убедитесь, что wal_level не установлен на minimal в файле postgresql.conf нового основного кластера.

  9. Всегда запускайте двоичный файл pg_upgrade нового сервера, а не старого. pg_upgrade требует указания каталогов данных и исполняемых файлов старой и новой кластеров (bin). Также можно указать значения пользователя и порта, а также нужно ли связать файлы данных или клонировать их вместо стандартного поведения копирования.

При использовании режима ссылки, обновление будет происходить намного быстрее (без копирования файлов) и использовать меньше дискового пространства, но после начала работы нового кластера доступа к старому кластеру не будет. Режим ссылок также требует, чтобы каталоги данных старого и нового кластеров находились в одной файловой системе. Табличные пространства и pg_wal могут находиться в разных файловых системах. Режим клонирования обеспечивает те же преимущества скорости и использования дискового пространства, но не приводит к тому, что старый кластер становится непригодным для использования при запуске нового кластера. Режим клонирования также требует, чтобы старые и новые каталоги данных находились в одной файловой системе. Этот режим доступен только в некоторых операционных системах и файловых системах.

Параметр --jobs позволяет использовать несколько ядер процессора для копирования файлов или ссылок на них, а также для параллельного сброса и восстановления схем баз данных. Можно начинать с максимального количества ядер процессора и табличных пространств. Эта опция может значительно сократить время обновления многопользовательского сервера, работающего на многопроцессорной машине.

После запуска pg_upgrade проверит совместимость двух кластеров и выполнит обновление. Можно использовать pg_upgrade --check, чтобы выполнить только проверки, даже если старый сервер все еще работает. pg_upgrade --check также укажет любые ручные настройки, которые нужно будет внести после обновления. При использовании режима ссылок или клонирования, следует использовать параметр --link или --clone с --check, чтобы включить проверки, специфичные для режима. pg_upgrade требует разрешения на запись в текущем каталоге.

Никто не должен иметь доступ к кластерам во время обновления. pg_upgrade по умолчанию запускает серверы на порту 50432, чтобы избежать непреднамеренных клиентских подключений. Можно использовать один и тот же номер порта для обоих кластеров при обновлении, потому что старые и новые кластеры не будут работать одновременно. Однако при проверке работающего старого сервера старые и новые номера портов должны быть разными.

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

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

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

  1. Убедитесь, что новые двоичные файлы и файлы поддержки установлены на всех резервных серверах.

  2. Убедитесь, что новые каталоги данных Standby не существуют или пусты. Если был выполнен initdb, удалите новые каталоги данных серверов Standby.

  3. Установите те же общие объектные файлы расширений на новых резервных копиях, которые установлены в новом основном кластере.

  4. Если резервные серверы все еще работают, остановите их сейчас с помощью вышеуказанных инструкций.

  5. Сохраните любые файлы конфигурации из каталогов конфигурации старых резервных копий, которые необходимо сохранить, например, postgresql.conf (и любые файлы, включенные в него), postgresql.auto.conf, pg_hba.conf, потому что они будут перезаписаны или удалены на следующем шаге.

  6. При использовании режима ссылки резервные серверы могут быть быстро обновлены с помощью rsync. Для запуска из каталога на основном сервере, который находится выше старых и новых каталогов кластера баз данных, выполните на основном для каждого резервного сервера:

    rsync --archive --delete --hard-links --size-only --no-inc-recursive old_cluster new_cluster remote_dir

    где old_cluster и new_cluster относительно текущего каталога на главном, а remote_dir - выше старых и новых каталогов кластеров на резервной копии. Структура каталогов под указанными каталогами на первичном и вторичном серверах должна совпадать. Обратитесь к странице руководства rsync для получения подробной информации о том, как указать удаленный каталог, например:

    rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/PostgreSQL/9.5 \
    /opt/PostgreSQL/9.6 standby.example.com:/opt/PostgreSQL

    Можно проверить, что команда будет делать, используя параметр --dry-run. Хотя rsync должен работать на первичном сервере хотя бы для одного резервного сервера, возможно запустить rsync на обновленном резервном сервере для обновления других резервных серверов при условии, что обновленный резервный сервер не был запущен.

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

    Если имеются табличные пространства, необходимо выполнить аналогичную команду rsync для каждого каталога табличного пространства, например:

    rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_9.5_201510051 \
    /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp

    Если pg_wal был перемещен за пределы каталогов данных, rsync также должен быть запущен на этих каталогах.

  7. Настройте серверы для логической репликации. Не нужно запускать pg_backup_start() и pg_backup_stop() или выполнять резервное копирование файловой системы, поскольку резервные копии все еще синхронизированы с основной системой. Слоты репликации не копируются и должны быть воссозданы.

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

  9. Новый сервер теперь можно безопасно запустить, а затем любые резервные серверы rsync.

  10. Если требуется пост-обработка после обновления, pg_upgrade будет выдавать предупреждения по мере завершения работы. Он также создаст файлы сценариев, которые должны быть запущены администратором. Файлы скриптов будут подключаться к каждой базе данных, требующей пост-обработки. Каждый сценарий должен запускаться с использованием:

psql --username=postgres --file=script.sql postgres

Сценарии могут выполняться в любом порядке и могут быть удалены после их запуска.

Внимание!

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

  1. Поскольку оптимизатор статистики не передается с помощью pg_upgrade, предлагается выполнить команду для регенерации этой информации в конце обновления. Возможно, потребуется настроить параметры подключения в соответствии с новым кластером.
  2. После можно удалить каталоги данных старого кластера, запустив сценарий, упомянутый при завершении работы pg_upgrade. Автоматическое удаление невозможно, если есть пользовательские табличные пространства внутри старого каталога данных. Также можно удалить старые установочные каталоги (например, bin, share).
  3. Если после запуска pg_upgrade потребуется вернуться к старому кластеру, существуют несколько вариантов:

  • Если использовался параметр --check, старый кластер остался неизменным; его можно перезапустить.

  • Если параметр --link не был использован, старый кластер остался неизменным; его можно перезапустить.

  • Если использовался параметр --link, файлы данных могут быть общими для старого и нового кластера:

    • Если pg_upgrade прервался до начала связывания, старый кластер остался неизменным; его можно перезапустить.
    • Если не был запущен новый кластер, старый кластер остался неизменным, за исключением того, что при запуске связывания к нему была добавлен .old-суффикс. Чтобы повторно использовать старый кластер, удалите суффикс .old из $PGDATA/global/pg_control; затем можно перезапустить старый кластер.
    • Если запущен новый кластер, данные записаны в общие файлы, использование старого кластера становится небезопасным. В этом случае старый кластер придется восстановить из резервной копии.

Особенности использования​

pg_upgrade создает различные рабочие файлы, такие как дампы схем, хранящиеся внутри pg_upgrade_output.d в каталоге нового кластера. Каждый запуск создает новый подкаталог с именем временной метки, отформатированной в соответствии со стандартом ISO 8601 (%Y%m%dT%H%M%S), где хранятся все его сгенерированные файлы. pg_upgrade_output.d и содержащиеся в нем файлы будут автоматически удалены, если pg_upgrade завершится успешно. В случае возникновения проблем эти файлы могут предоставить полезную информацию для отладки.

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

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

Для тестирования развертывания создайте копию старой схемы только со схемой, вставьте фиктивные данные и обновите их.

pg_upgrade не поддерживает обновление баз данных, содержащих столбцы таблиц, использующие эти reg*-системные типы данных, ссылающиеся на OID:

  • regcollation;
  • regconfig;
  • regdictionary;
  • regnamespace;
  • regoper;
  • regoperator;
  • regproc;
  • regprocedure.

Примечание:

regclass, regrole, и regtype могут быть обновлены.

Если необходимо использовать режим ссылки, чтобы старый кластер был изменен при запуске нового кластера, рассмотрите возможность использования режима клонирования. Если это недоступно, сделайте копию старого кластера и обновите его в режиме ссылки. Чтобы сделать действительную копию старого кластера, используйте rsync для создания грязной копии старого кластера во время работы сервера, затем выключите старый сервер и снова запустите rsync --checksum, чтобы обновить копию любыми изменениями, чтобы она была согласованной. Опция --checksum необходима, потому что rsync гранулярность изменения файла модификации времени в одну секунду. Если необходимо исключить некоторые файлы, например, postmaster.pid или если файловая система поддерживает моментальные снимки файловой системы или копирование файлов при записи, можно использовать их для создания резервной копии старого кластера и табличных пространств, хотя снимок и копии должны быть созданы одновременно или когда сервер базы данных отключен.