qhb_upgrade

qhb_upgrade — обновить экземпляр сервера QHB

Синтаксис

qhb_upgrade -b старый_каталог_bin -B новый_каталог_bin -d старый_каталог_конфигурации -D новый_каталог_конфигурации [параметр...]

Описание

Программа qhb_upgrade позволяет обновлять данные, хранящиеся в файлах данных QHB (в т. ч. PostgreSQL 12), до более поздней версии QHB без выгрузки/перезагрузки данных, обычно требующейся для обновлений основных версий (например, с 1.1.1 до 1.4.1 или с 1.4 до 2.1). Это не требуется для обновлений минорных (например, с 1.1.1 до 1.1.2) или корректирующих версий.

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

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

Важно!!!
Вследствие использования генерируемых ключей для шифрования в QHB 1.4.0 qhb_upgrade не может обновлять на эту и более новые версии QHB с версии qhb_upgrade 1.3.0 и более ранних, если они используют шифрование (qss_mode = 1).

Параметры

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

-b каталог_bin
--old-bindir=каталог_bin

каталог исполняемых файлов старой версии QHB; переменная окружения PGBINOLD

-B каталог_bin
--new-bindir=каталог_bin

каталог исполняемых файлов новой версии QHB; по умолчанию это каталог, в котором располагается qhb_upgrade; переменная окружения PGBINNEW

-c
--check

только проверить кластеры, не изменять никакие данные

-d каталог_конфигурации
--old-datadir=каталог_конфигурации

каталог конфигурации старого кластера базы данных; переменная окружения PGDATAOLD

-D каталог_конфигурации
--new-datadir=каталог_конфигурации

каталог конфигурации нового кластера базы данных; переменная окружения PGDATANEW

-s каталог
--socketdir=каталог

каталог, используемый для сокетов процесса postmaster во время обновления; по умолчанию это текущий рабочий каталог; переменная окружения PGSOCKETDIR

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

имя пользователя, устанавливающего кластер; переменная окружения PGUSER

-v
--verbose

включить подробные внутренние сообщения

-V
--version

показать версию и завершить работу

--help

показать справку и завершить работу

Использование

Далее пошагово описано выполнение обновления с помощью qhb_upgrade:

  1. Переместить старый кластер (необязательно)

Если вы используете установочный каталог, привязанный к конкретной версии, например /opt/QHB/1, то перемещать старый кластер не требуется. Все графические установщики используют установочные каталоги, привязанные к конкретной версии.

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

mv /usr/local/qhb /usr/local/qhb.old
  1. Установить новые исполняемые файлы QHB

Установите новые исполняемые файлы сервера и вспомогательные файлы. Программа qhb_upgrade включена в установку по умолчанию.

  1. Инициализировать новый кластер QHB

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

  1. Установить дополнительные разделяемые объектные файлы

Установите в новый кластер все дополнительные разделяемые объектные файлы (или DLL), которые использовались старым кластером, например pgcrypto.so, где бы они ни находились — в contrib или в другом месте. Нет необходимости устанавливать определения схемы, (например, CREATE EXTENSION pgcrypto), так как они будут перенесены из старого кластера. Кроме того, в новый кластер нужно скопировать все нестандартные файлы поддержки полнотекстового поиска (словарь, синоним, тезаурус, стоп-слова).

  1. Настроить аутентификацию

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

  1. Остановить оба сервера

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

pg_ctl -D /opt/pgsql/12 stop
qhb_ctl -D /opt/PostgreSQL stop

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

  1. Подготовиться к обновлению резервного сервера

Если вы обновляете резервные серверы, используя методы, описанные в шаге 9, убедитесь, что старые резервные серверы находятся в актуальном состоянии, запустив qhb_controldata в старых основном и резервном кластерах. Убедитесь, что значения «Последнее положение контрольной точки» совпадают во всех кластерах. (Несоответствие возникнет, если старые резервные серверы все еще работают или были отключены раньше старого основного.) Также измените значение wal_level на replica в файле qhb.conf нового основного кластера.

  1. Запустить qhb_upgrade

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

После запуска qhb_upgrade проверит совместимость двух кластеров, а затем выполнит обновление. Если нужно выполнить только проверки, можно использовать qhb_upgrade --check (старый сервер при этом останавливать необязательно). Также qhb_upgrade --check сообщит какие корректировки потребуется сделать вручную после обновления.

Очевидно, что во время обновления никто не должен иметь доступ к кластерам. По умолчанию qhb_upgrade запускает серверы на порту 5432, чтобы избежать непреднамеренных клиентских подключений.

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

  1. Обновить резервные серверы с потоковой репликацией и трансляцией журнала

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

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

  • Установите новые исполняемые файлы QHB на резервных серверах

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

  • Убедитесь, что на резервных серверах новых каталогов данных не существует (или они пустые)

    Если запускалась qhb_bootstrap, удалите на резервных серверах новые каталоги данных.

  • Установите дополнительные разделяемые объектные файлы

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

  • Остановите резервные серверы

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

  • Сохраните файлы конфигурации

    Сохраните все файлы конфигурации из старых каталогов конфигурации резервных серверов, такие как qhb.conf и qhb_hba.conf, так как на следующем этапе они будут перезаписаны или удалены.

  • Запустите rsync

    При использовании режима ссылок резервные серверы можно быстро обновить с помощью 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 \
      /opt/PostgreSQL standby.example.com:/opt/PostgreSQL

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

    Во время этой операции записываются ссылки, созданные в режиме ссылок qhb_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 следует запустить и в этих каталогах.

  • Настройте резервные серверы с потоковой репликации и трансляцией журнала

    Настройте серверы для трансляции журнала. (Запускать pg_start_backup() и pg_stop_backup() или делать резервную копию файловой системы не требуется, так как резервные серверы по-прежнему синхронизированы с основным.)

  1. Восстановить qhb_hba.conf

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

  1. Запустить новый сервер

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

  1. Действия после обновления

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

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

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

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

  1. Статистика

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

  1. Удалить старый кластер

Если вы удовлетворены обновлением, можно удалить каталоги данных старого кластера, а также каталоги старой установки (например, bin, share).

  1. Возврат к старому кластеру

Если после запуска qhb_upgrade вы хотите вернуться к старому кластеру, есть несколько вариантов:

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

  • Если qhb_upgrade была прервана до начала связывания, то старый кластер не изменился; просто перезапустите его.

Примечания

Программу qhb_upgrade следует запускать пользователю, от имени которого будет запускаться новый сервер. Также можно указать его параметром -U.

qhb_upgrade нельзя запускать под пользователем root.

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

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

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

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

qhb_upgrade не поддерживает обновление баз данных, содержащих таблицы со столбцами, имеющими следующие системные типы данных reg, ссылающиеся на OID: regproc, regprocedure, regoper, regoperator, regconfig и regdictionary. (Тип regtype обновить можно.)

См. также

qhb_bootstrap, qhb_ctl, qhb_dump, qhb