Миграция кластера баз данных в QHB

В настоящее время поддерживается миграция в QHB только начиная с версии PostgreSQL 12. Если используется более ранняя версия PostgreSQL, необходимо сначала выполнить обновление до версии 12. Также поддерживается миграция со старых версий QHB. Данная инструкция охватывает только основные моменты миграции, на которые нужно обратить внимание.

В данном примере рассматривается вариант миграции с PostgreSQL версии 12 на QHB текущей версии. Более подробно процедура миграции описана в разделе qhb_upgrade.

Подготовка к миграции

Пример исходных данных

Данные PostgreSQL
Каталог с запускаемыми файлами: /usr/pgsql-12/bin
Каталог с данными: /var/lib/pgsql/12/data/
Суперпользователь: postgres
Порт: 5432
Служба: postgresql-12

Данные QHB
Каталог с запускаемыми файлами: /usr/local/qhb/bin
Каталог с данными: /opt/qhb/data
Суперпользователь: qhb
Порт: 5432
Служба: qhb

Если необходимо, чтобы сервисы postgresql-12 и qhb работали одновременно (например, в целях тестирования работоспособности QHB), нужно изменить номер порта для QHB, т. е. изменить значение параметра port в файле параметров qhb.conf, например, на 5433. Для обновления через qhb_upgrade это не является обязательным, так как сервисы запускаются по очереди.

Внимание!
Если при установке QHB на машину, где уже расположен PostgreSQL, система выдает оповещение о необходимости откатить версии некоторых пакетов, которые были установлены PostgreSQL (например, llvm или llvm-libs), то рекомендуется отменить установку и затем установить пакет llvm-compat-libs-12.0.1 отдельно. Только после успешной установки пакета можно повторить установку QHB (при этом установка больше не будет требовать откатить версию, так как будет установлено сразу 2 версии llvm).

Языковые настройки

Заранее уточните значения параметров с языковыми настройками нового кластера баз данных QHB (locale, lc-collate, lc-ctype — соответственно локаль, порядок сортировки строк, классификация символов). Как правило, эти параметры имеют одинаковое значение и должны соответствовать настройкам исходного кластера баз данных PostgreSQL. Выяснить значения этих настроек в PostgreSQL можно через команду \l в psql, выведя список баз данных с их параметрами. В данном примере значения параметров одинаковы и равны en_US.UTF-8.

Переименование в кластере баз PostgreSQL суперпользователя postgres в qhb

Утилита qhb_upgrade должна работать от имени одного и того же пользователя как с PostgreSQL, так и с QHB. Рекомендуется использовать в качестве такого пользователя qhb. Так как суперпользователь qhb по умолчанию отсутствует в базе PostgreSQL, переименуем пользователя postgres в qhb. Для этого нужно зайти в PostgreSQL от имени другого суперпользователя. Если такого пользователя не существует, можно его создать, а после переименования пользователя postgres удалить.

Зайдем от имени суперпользователя postgres:

/usr/pgsql-12/bin/psql -d postgres -U postgres

Создадим нового суперпользователя temp_su, зайдем от его имени, переименуем пользователя postgres в qhb, подключимся под qhb и удалим уже ненужного пользователя temp_su:

CREATE ROLE temp_su LOGIN SUPERUSER;
\c postgres temp_su
ALTER USER postgres RENAME TO qhb;
\c postgres qhb
DROP ROLE temp_su;

Создание тестовой базы данных и таблицы в ней

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

CREATE DATABASE test;
\c test
CREATE TABLE test (id int, txt text);
INSERT INTO test VALUES(1, "test1");

Остановка работы сервисов и смена владельца каталога PostgreSQL

Остановка сервисов postgres-12 и qhb (если сервис qhb был запущен):

sudo systemctl stop postgresql-12
sudo systemctl stop qhb

Для того чтобы утилита qhb_upgrade нормально отработала от имени системного пользователя qhb, поменяем владельца для каталога данных PostgreSQL на qhb. Для верхних каталогов необходимо выдать на время права, позволяющие другим пользователям заходить в них и читать данные.

sudo chmod o+rx /var/lib/pgsql
sudo chmod o+rx /var/lib/pgsql/12
sudo chown -R qhb:qhb /var/lib/pgsql/12/data

Инициализация кластера баз данных QHB

Далее рекомендуется переключиться на системного пользователя qhb и выполнять последующие команды от его имени:

sudo su - qhb

Очистка каталога данных QHB

Здесь предполагается, что каталог /opt/qhb/data является корневым каталогом данных QHB, выбранном при установке и настройке базы данных. Если каталог не является к этому моменту пустым, необходимо его полностью очистить. В противном случае миграция данных не запустится.

rm -rf /opt/qhb/data/*

Инициализация нового кластера

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

/usr/local/qhb/bin/qhb_bootstrap \
--locale=en_US.UTF-8 \
--lc-collate=en_US.UTF-8 \
--lc-ctype=en_US.UTF-8 \
--encoding=UTF8 \
--data-dir /opt/qhb/data

Выполнение проверки возможности миграции базы с PostgreSQL на QHB

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

mkdir /tmp/qhb_upgrade
chmod 700 /tmp/qhb_upgrade
cd /tmp/qhb_upgrade

Внимание!
Версия qhb_upgrade при миграции из PostgreSQL в QHB должна быть не меньше 1.3.1. Проверка выполняется через запуск /usr/local/qhb/bin/qhb_upgrade --version.

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

/usr/local/qhb/bin/qhb_upgrade \
--new-bindir=/usr/local/qhb/bin \
--new-datadir=/opt/qhb/data \
--old-bindir=/usr/pgsql-12/bin \
--old-datadir=/var/lib/pgsql/12/data \
-U qhb -v --check

Результаты проверки выведутся на экран, а также в файл pg_upgrade_internal.log. В случае успешного завершения проверки на экран предпоследней строкой выведется сообщение *Clusters are compatible* (кластеры совместимы).

Выполнение миграции

Для выполнения миграции в предыдущей команде необходимо убрать параметр --check.

/usr/local/qhb/bin/qhb_upgrade \
--new-bindir=/usr/local/qhb/bin \
--new-datadir=/opt/qhb/data \
--old-bindir=/usr/pgsql-12/bin \
--old-datadir=/var/lib/pgsql/12/data \
-U qhb -v

В случае успешной миграции на экран предпоследней строкой выведется Upgrade Complete (обновление завершено). Также результаты работы утилиты будут зафиксированы в логе pg_upgrade_internal.log.

Возврат исходных прав для каталога

В общем случае в каталоге /var/lib/pgsql могут быть расположены несколько кластеров баз данных. Вернем исходные права доступа для верхних каталогов и вернем прежнего владельца для каталога с данными PostgreSQL /var/lib/pgsql/12/data. Это может понадобиться в случае отмены миграции и возврата к использованию баз PostgreSQL.

sudo chmod o-rx /var/lib/pgsql
sudo chmod o-rx /var/lib/pgsql/12
sudo chown -R postgres:postgres /var/lib/pgsql/12/data

Проверка переноса данных

Предварительно должны быть отредактированы все настройки в соответствующих файлах настроек (qhb.conf, qhb_hba.conf и qhb_ident.conf).

Запуск QHB и проверка перенесенных данных:

sudo systemctl start qhb
/usr/local/qhb/bin/psql -U qhb -d test -c "select * from test"