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

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

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

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

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

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

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

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

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

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

Утилита qhb_upgrade должна работать от имени одного и того же пользователя как с Postgres, так и с QHB. Рекомендуется использовать в качестве такого пользователя qhb. Так как суперпользователь qhb по умолчанию отсутствует в базе Postgres, переименуем пользователя postgres в qhb. Для этого нужно зайти в Postgres от имени другого суперпользователя. Если такого пользователя не существует, можно его создать, а после переименования пользователя 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;

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

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

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

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

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

sudo systemctl stop postgresql-12
sudo systemctl stop qhb

Для того чтобы утилита qhb_upgrade нормально отработала от имени системного пользователя qhb, поменяем владельца для каталога данных Postgres на 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

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

rm -rf /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 /data

Выполнение проверки возможности миграции базы с Postgres на 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 при миграции из Postgres в 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=/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=/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 могут быть расположены несколько кластеров баз данных. Вернем исходные права доступа для верхних каталогов и вернем прежнего владельца для каталога с данными Postgres /var/lib/pgsql/12/data. Это может понадобиться в случае отмены миграции и возврата к использованию баз Postgres.

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.cong, qhb_hba.conf и qhb_ident.conf).

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

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