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

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

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

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

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

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-бит и параметры сборки). Внешние модули также должны быть двоично-совместимы (утилита это не проверяет).

Поддерживаются обновления с версии 9.2.x и выше до текущей основной версии PostgreSQL (включая снепшоты и beta).

Пример миграции с оригинального PostgreSQL на Pangolin приведен в разделе Миграция с оригинального PostgreSQL на Pangolin.

Доработка​

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

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

Утилита не поддерживает базы с системными типами regcollation, regconfig, regdictionary, regnamespace, regoper, regoperator, regproc, regprocedure.

Расширения и внешние модули должны быть собраны заново для новой версии.

Старый и новый кластеры должны быть одинаковой разрядности (32/64-бит).

Для режима --link и --clone требуется, чтобы каталоги находились на одной файловой системе.

При обновлении экземпляра СУБД, содержащего нелоггируемые (unlogged) таблицы, данные из этих таблиц могут быть удалены. Для сохранения данных рекомендуется явно изменить признак журналируемости таких таблиц.

Установка​

Устанавливается по умолчанию с ядром 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.

  • --test – запуск утилиты pg_upgrade для экземпляров (кластеров) с одинаковой версией системного каталога;

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

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

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

  1. Определите тип каталога инсталляции:

    • если используете версионный каталог (например, /opt/PostgreSQL/15) — ничего не перемещайте.
    • если используете не версионный каталог (например, /usr/local/pgsql) — переименуйте старую инсталляцию после остановки сервера:
    mv /usr/local/pgsql /usr/local/pgsql.old

  2. Соберите (для исходных установок) или установите новую версию PostgreSQL. Для пользовательского пути установки выполните:

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

  3. Инициализируйте новый кластер initdb с флагами, совместимыми со старым кластером. Новый кластер не запускайте.

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

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

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

  7. Остановите оба кластера:

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

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

  8. Проверьте состояние старого primary и standby с помощью pg_controldata. Убедитесь, что местоположение последней контрольной точки совпадает, а в postgresql.conf нового primary wal_level не равен minimal.

  9. Запустите pg_upgrade из новой версии. Укажите каталоги данных и bin старого/нового кластеров, при необходимости — пользователя и порты.

    При использовании --link обновление проходит быстрее и требует меньше места, но старый кластер после запуска нового использовать нельзя, для --link каталоги данных должны быть на одной ФС. --clone дает ту же скорость/экономию и сохраняет работоспособность старого кластера (также требует одной ФС и поддержки ОС/ФС).

    Задайте --jobs для параллелизма. Выполните --check для предварительных проверок (при планировании --link/--clone укажите их вместе с --check). Утилите требуется право записи в текущий каталог.

    Во время обновления исключите клиентские подключения (по умолчанию используется порт 50432).

  10. Обновите standby при режиме ссылок/клонирования с помощью rsync (на primary), либо пересоздайте реплики после запуска нового primary:

    • установите новые бинарии и расширения на все standby;
    • убедитесь, что новые каталоги данных standby отсутствуют или пусты (при необходимости удалите результаты initdb);
    • сохраните нужные конфигурационные файлы (postgresql.conf, postgresql.auto.conf, pg_hba.conf);
    • выполните rsync для каталогов кластера, табличных пространств и отдельного pg_wal (если вынесен);
    • настройте логическую репликацию (слоты не копируются и создаются заново).

  11. Восстановите изменения в pg_hba.conf и, при необходимости, приведите postgresql.conf/postgresql.auto.conf нового кластера к требуемым значениям.

  12. Запустите новый сервер, затем — обновленные standby (если применимо).

  13. Выполните пост-скрипты, сгенерированные pg_upgrade (находятся в pg_upgrade_output.d):

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

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

    Внимание!

    До завершения скриптов перестройки не обращайтесь к таблицам, на которые они ссылаются (риск неверных результатов/низкой производительности). К остальным таблицам доступ разрешен сразу.

  14. Перестройте статистику планировщика:

    vacuumdb --all --analyze-only --jobs=4

    При необходимости ускорьте первичный сбор статистики опцией --analyze-in-stages и/или PGOPTIONS='-c vacuum_cost_delay=0'.

  15. Удалите каталоги данных старого кластера, запустив скрипт, указанный pg_upgrade (автоудаление невозможно при наличии пользовательских табличных пространств). При желании удалите каталоги старой инсталляции (bin, share).

  16. Вернитесь к старому кластеру при необходимости:

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

    • если использовался --link:

      • pg_upgrade прервался до расстановки ссылок — перезапустите старый кластер;
      • новый кластер не запускался — удалите суффикс .old у $PGDATA/global/pg_control и перезапустите старый кластер;
      • новый кластер запускался — общий набор файлов изменен, восстановите старый кластер из резервной копии.

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

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

Утилита запускает временные postmaster в старом и новом каталогах данных. По умолчанию сокеты Unix создаются в текущем рабочем каталоге; при слишком длинном пути используйте -s для указания более короткого пути и обеспечьте недоступность каталога для чтения/записи посторонним.

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

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

pg_upgrade не поддерживает обновление баз данных, содержащих столбцы с reg*-типами, ссылающимися на OID: regcollation, regconfig, regdictionary, regnamespace, regoper, regoperator, regproc, regprocedure.

примечание

regclass, regrole, regtype поддерживаются.

Если требуется --link, но необходимо исключить изменения старого кластера при запуске нового, используйте --clone. Если недоступно — сделайте копию старого кластера и обновите ее в режиме ссылок. Для валидной копии выполните rsync (грязная копия при работающем сервере), затем остановите сервер и повторите rsync --checksum для согласования. При необходимости исключите служебные файлы (например, postmaster.pid) или задействуйте снепшоты/копирование-при-записи — снимки/копии должны создаваться одновременно или при остановленном сервере.

Тестовый режим​

При запуске утилиты с опцией --test она переходит в тестовый режим, который проверяет готовность к миграции табличных пространств без выполнения фактического переноса данных. Режим сопровождается использованием параметров --old-tablespace и --new-tablespace, предназначенных для указания путей к текущим и целевым табличным пространствам.

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

Параметры --test, --old-tablespace и --new-tablespace разработаны исключительно для тестирования и не вызывают изменений в действующих базах данных.

Цель данной комбинации параметров — тестирование готовности инфраструктуры к миграции табличных пространств безопасным способом, исключающим потерю данных.