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

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.

Доработка​

В pg_upgrade добавлена поддержка аутентификации по сертификату (PEM, PKCS#12) при обновлении СУБД Pangolin.

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

LOG:  cert authentication is only supported on hostssl connections
FATAL:  could not load pg_hba.conf

Для устранения ограничения в pg_upgrade реализован режим запуска временных процессов postmaster на TCP/IP-сокете с прослушиванием localhost. Режим активируется опцией --use-tcp (-t). Использование TCP/IP позволяет применять SSL/TLS и настраивать аутентификацию по сертификату через правила hostssl в pg_hba.conf.

Опции для настройки SSL-подключения​

Для задания SSL-параметров в pg_upgrade добавлены опции подключения к старому и новому кластеру.

Параметры для старого кластера:

  • --old-sslmode — режим SSL (disable, allow, prefer, require, verify-ca, verify-full);
  • --old-sslcert — путь к клиентскому сертификату;
  • --old-sslkey — путь к закрытому ключу для клиентского сертификата;
  • --old-sslrootcert — путь к доверенному сертификату;
  • --old-sslrootpath — путь к директории с доверенными сертификатами;
  • --old-sslcrl — путь к файлу со списком отозванных сертификатов (CRL);
  • --old-sslcrldir — путь к директории с файлами CRL;
  • --old-pkcs12-config-path — путь к настроечному файлу .p12.cfg, содержащему путь до локального контейнера PKCS#12;
  • --old-sslconnstr — строка подключения (поддерживает использование только SSL-параметров).

Параметры для нового кластера:

  • --new-sslmode;
  • --new-sslcert;
  • --new-sslkey;
  • --new-sslrootcert;
  • --new-sslrootpath;
  • --new-sslcrl;
  • --new-sslcrldir;
  • --new-pkcs12-config-path;
  • --new-sslconnstr.

Если один и тот же SSL-параметр указан и в --old(new)-sslconnstr, и в соответствующей опции командной строки pg_upgrade, приоритет имеет значение, заданное отдельной опцией командной строки.

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

Сохранена возможность настройки SSL-параметров через переменные окружения с меньшим приоритетом по сравнению с --old(new)-sslconnstr и опциями командной строки:

  • PGSSLMODE — аналог --old(new)-sslmode;
  • PGSSLCERT — аналог --old(new)-sslcert;
  • PGSSLKEY — аналог --old(new)-sslkey;
  • PGSSLROOTCERT — аналог --old(new)-sslrootcert;
  • PGSSLROOTPATH — аналог --old(new)-sslrootpath;
  • PGSSLCRL — аналог --old(new)-sslcrl;
  • PGSSLCRLDIR — аналог --old(new)-sslcrldir;
  • PKCS12_CONFIG_PATH — аналог --old(new)-pkcs12-config-path;
  • PKCS12_PASSPHRASE — парольная фраза для доступа к контейнеру PKCS#12.

Ввод пароля и парольной фразы PKCS#12​

Для управления интерактивным вводом секретов в pg_upgrade добавлены опции:

  • --password-prompt (-W) — запрос пароля или парольной фразы;
  • --password-prompt-timeout — время ожидания ввода (по умолчанию 30 секунд);
  • --no-passphrase-prompt — не использовать введенный текст как парольную фразу PKCS#12;
  • --use-pty — использовать pseudo-terminal для ввода пароля (рекомендуется при --jobs).

Если парольная фраза для PKCS#12 отсутствует в .p12.cfg (поле passphrase), для аутентификации требуется ввод парольной фразы вручную. При использовании --jobs необходимо указывать --use-pty, иначе возможны ошибки чтения парольной фразы утилитами pg_dump и pg_restore.

Доработки вспомогательных утилит​

Утилиты pg_dump, pg_restore и vacuumdb, используемые в процессе обновления, могут многократно подключаться к СУБД и запрашивать парольную фразу для PKCS#12. Для сокращения числа запросов парольной фразы в них добавлен параметр --passphrase-pkcs12.

Логирование плагина PKCS#12​

Введен параметр --plugin-log-level для настройки уровня логирования сообщений плагина извлечения сертификата и закрытого ключа из контейнера PKCS#12. Значение по умолчанию — WARNING.

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

Утилита не поддерживает базы с системными типами 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 разработаны исключительно для тестирования и не вызывают изменений в действующих базах данных.

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