qhb_upgrade

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

Синтаксис

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

Описание

Утилита qhb_upgrade позволяет обновлять данные, хранящиеся в файлах данных QHB до более поздней версии QHB без выгрузки/ восстановления данных, обычно требующихся для обновлений основных версий (например с 1.1.0 до 1.3.1 или с 1.4 до 1.5). Для обновлений минорных (например с 1.3.0 до 1.3.1) или корректирующих версий она не нужна.

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

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

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

Исходная база данных ------QHB 1.1.xQHB 1.2.xQHB 1.3.xQHB 1.4.xQHB 1.5.x
QHB 1.1.x++++
QHB 1.2.x+++
QHB 1.3.x++
QHB 1.4.x+
PostgreSQL 12.x+++++
PostgreSQL 13.x+
PostgreSQL 14.x+

ВАЖНО!
Вследствие использования генерируемых ключей для шифрования в 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.

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

-k
--link
использовать жесткие ссылки вместо копирования файлов в новый кластер (данный параметр можно применять только для обновления. Для миграции с PostgreSQL его применять нельзя).

-o параметры
--old-options параметры
параметры, подлежащие передаче непосредственно старой команде qhb; при введении нескольких параметров они конкатенируют.

-O параметры
--new-options параметры
параметры, подлежащие передаче непосредственно новой команде qhb; при введении нескольких параметров они конкатенируют.

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

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

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

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

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

-U имя_пользователя
--username=имя_пользователя
имя пользователя, устанавливающего кластер; переменная среды PGUSER.

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

-V
--version
показать информацию о версии и завершиться.

--clone Использовать эффективное клонирование файлов (в некоторых системах также известное как «reflinks») вместо копирования файлов в новый кластер. Это приводит к почти мгновенному копированию файлов данных, давая преимущества в скорости параметра -k/--link, но при этом оставляя старый кластер нетронутым.
Клонирование файлов поддерживается лишь в некоторых операционных и файловых системах. Если оно выбрано, но не поддерживается, запуск qhb_upgrade вызовет ошибку. В настоящее время оно поддерживается в Linux (с ядром 4.5 или новее) с Btrfs и XFS (в файловых системах, созданных с поддержкой reflink) и в macOS с APFS.

--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 с флагами скрипта configure, совместимыми со старым кластером. qhb_upgrade проверит qhb_controldata, чтобы убедиться, что все параметры совместимы, прежде чем начать обновление.

  1. Установить новые исполняемые файлы QHB

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

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

make prefix=/usr/local/qhb.new install
  1. Инициализировать новый кластер QHB

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

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

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

  1. Скопировать пользовательские файлы полнотекстового поиска

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Сохраните файлы конфигурации
    Сохраните все файлы конфигурации из старых каталогов конфигурации резервных серверов, такие как qhb.conf (и все включенные в него файлы), qhb.auto.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 (и все включенные в него файлы), qhb.auto.conf.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания

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

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

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

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

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

regcollation
regconfig
regdictionary
regnamespace
regoper
regoperator
regproc
regprocedure
(столбцы regclass, regrole и regtype обновлять можно.)

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

См. также

qhb_bootstrap, qhb_ctl, qhb_dump, qhb

Copyright © KVANTOM LLC, 2019-2023