Миграция на базу данных уровня промышленной эксплуатации¶

На этой странице описано, как перевести Glarus BI с использования встроенной базы данных приложения H2 на PostgreSQL, СУБД для промышленной эксплуатации. Для получения дополнительной информации о том, почему следует использовать Postgres в качестве базы данных приложения, см. Как запускать Glarus BI в рабочей среде (документация Metabase, англ.).

База данных приложения Glarus BI¶

Основное различие между локальной установкой и установкой для промышленной эксплуатации заключается в выборе базы данных приложения. База данных приложения хранит информацию обо всех ваших данных Glarus BI: запросах, дашбордах, коллекциях и т.д.

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

Вы можете в любое время перейти с базы данных H2 на Postgres или другую СУБД, но чем раньше произойдёт переход, тем лучше. Если вы продолжите запускать Glarus BI с базой данных H2 по умолчанию и не будете регулярно делать её резервные копии, база данных приложения может быть повреждена, и вы можете потерять все запросы, дашборды, коллекции и другие данные Glarus BI.

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

Предупреждение

Смена базы данных приложения (метаданных) может привести к проблемам с доступом к системе даже при выполнении всех инструкций. Перед выполнением подобных действий проконсультируйтесь в службе поддержки.

Избегайте одновременной миграции и обновления версии¶

Важно, чтобы версия Glarus BI, используемая в процессе миграции, была одинаковой. Это означает, что Glarus BI, которую вы используете для запуска команды миграции, должна быть той же самой, которая последний раз использовалась для создания или обновления файла H2, и это должна быть та же версия, которую вы будете использовать в промышленной эксплуатации. Только после завершения миграции следует рассматривать возможность обновления.

Поддерживаемые базы данных для хранения данных приложения Glarus BI¶

Мы рекомендуем использовать PostgreSQL для вашей базы данных приложения.

PostgreSQL. Минимальная версия: 12. PostgreSQL — предпочтительный выбор для базы данных приложения Glarus BI.
MySQL. Минимальная версия: 8.0.17. Требуемые настройки (которые являются настройками по умолчанию): сортировка utf8mb4_unicode_ci, набор символов utf8mb4 и innodb_large_prefix=ON.
MariaDB. Минимальная версия: 10.4.0. Требуемые настройки (которые являются настройками по умолчанию): сортировка utf8mb4_unicode_ci, набор символов utf8mb4 и innodb_large_prefix=ON.

JAR: Как мигрировать с H2 на вашу промышленную базу данных приложения¶

Предупреждение

Вы должны использовать одну и ту же версию Glarus BI на протяжении всего процесса миграции.

Glarus BI предоставляет набор команд для миграции на новую базу данных приложения. Необходимо сделать следующее:

1. Проверьте, что вы можете подключиться к целевой базе данных приложения
2. Выключите экземпляр Glarus BI
3. Сделайте резервную копию вашей базы данных приложения H2
4. Запустите команду миграции данных Glarus BI
5. Запустите Glarus BI

1. Проверьте, что вы можете подключиться к целевой базе данных приложения¶

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

2. Выключите экземпляр Glarus BI¶

Пока происходит миграция данных, необходимо ограничить пользователям возможность создавать новые метаданные. В идеале если вы запускаете JAR-файл Glarus BI в промышленной эксплуатации, ваш экземпляр запускается как служба.

3. Сделайте резервную копию вашей базы данных приложения H2¶

См. Резервное копирование данных приложения Glarus BI.

4. Запустите команду миграции данных Glarus BI¶

Запустите команду миграции load-from-h2, используя соответствующие переменные среды для целевой базы данных, в которую вы хотите выполнить миграцию.

Подробную информацию о настройке баз данных можно найти в разделе Настройка базы данных приложения.

Пример команды для миграции на базу данных Postgres:

export MB_DB_TYPE=postgres
export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>"
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar load-from-h2 /path/to/metabase.db # do not include .mv.db

Пример команды для миграции в базу данных MySQL с использованием параметра Java вместо переменных среды:

java -DMB_DB_TYPE=mysql -DMB_DB_CONNECTION_URI="jdbc:mysql://<host>:3306/metabase?user=<username>&password=<password>" -jar metabase.jar load-from-h2 metabase.db

Обратите внимание, что имя файла самой базы данных может быть /path/to/metabase.db.mv.db, но при запуске команды load-from-h2 вам нужно указать путь как /path/to/metabase.db, без двойного расширения в конце.

Glarus BI предполагает, что вы запустите команду для совершенно новой (пустой) базы данных; она создаст схему базы данных и мигрирует данные для вас.

5. Запустите Glarus BI¶

Запустите вашу Glarus BI (с информацией о подключении к базе данных, но без команды load-from-h2 и команды миграции файла H2), и всё должно работать. Например, если вы используете Postgres, ваша команда для запуска Glarus BI будет выглядеть примерно так:

export MB_DB_TYPE=postgres
export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>"
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

Однако вам следует сохранить ваш старый файл H2 на всякий случай.

Docker: как мигрировать с H2 на промышленную базу данных приложения¶

Предупреждение

Вы должны использовать одну и ту же версию Glarus BI на протяжении всего процесса миграции.

Glarus BI предоставляет специальную команду миграции для перехода на новую базу данных приложения. Вот что вам нужно сделать:

1. Проверьте, что вы можете подключиться к целевой базе данных приложения
2. Сделайте резервную копию вашей базы данных приложения H2
3. Остановите существующий контейнер Glarus BI
4. Загрузите JAR
5. Запустите команду миграции
6. Запустите новый контейнер Docker, использующий новую базу данных приложения
7. Удалите старый контейнер, который использовал базу данных H2

1. Проверьте, что вы можете подключиться к целевой базе данных приложения¶

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

2. Сделайте резервную копию вашей базы данных приложения H2¶

См. Резервное копирование данных приложения Glarus BI.

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

3. Остановите существующий контейнер Glarus BI¶

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

4. Загрузите JAR¶

В каталоге, где вы сохранили ваш файл H2 (то есть вне контейнера), загрузите JAR для вашей текущей версии.

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

5. Запустите команду миграции¶

Создайте ещё одну копию вашего файла H2, который вы извлекли из контейнера при резервном копировании базы данных приложения (шаг 2).

Из каталога с вашим файлом H2 и JAR-файлом Glarus BI запустите команду миграции, load-from-h2. Используйте соответствующую строку подключения или переменные среды для целевой базы данных, в которую вы хотите выполнить миграцию. Команда будет выглядеть примерно так:

export MB_DB_TYPE=postgres
export MB_DB_CONNECTION_URI="jdbc:postgresql://<host>:5432/metabase?user=<username>&password=<password>"
java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar load-from-h2 /path/to/metabase.db # do not include .mv.db

Glarus BI запустится, выполнит миграцию (то есть возьмёт данные из файла H2 и поместит их в вашу новую базу данных приложения, в данном случае, базу данных Postgres), а затем завершит работу.

См. Настройка базы данных приложения.

6. Запустите новый контейнер Docker, использующий новую базу данных приложения¶

С вашей новой базой данных приложения, заполненной данными Glarus BI, вы можете запустить новый контейнер и указать Glarus BI в контейнере подключиться к базе данных приложения. Команда будет выглядеть примерно так:

docker run -d -p 3000:3000 \
  -e "MB_DB_TYPE=postgres" \
  -e "MB_DB_DBNAME=<your-postgres-db-name>" \
  -e "MB_DB_PORT=5432" \
  -e "MB_DB_USER=<db-username>" \
  -e "MB_DB_PASS=<db-password>" \
  -e "MB_DB_HOST=<your-database-host>" \
  --name glarusbi metabase/metabase

7. Удалите старый контейнер, который использовал базу данных H2¶

Если у вас есть резервная копия файла H2, сохранённая в безопасном месте, можете удалить старый контейнер. См. документацию Docker (англ.) по удалению контейнеров.

Ручной запуск миграций базы данных приложения Glarus BI¶

При запуске Glarus BI обычно пытается определить, требуются ли какие-либо изменения в базе данных приложения, и, если да, автоматически выполняет эти изменения. Если по какой-то причине вы хотите увидеть, что это за изменения, и запустить их вручную в вашей базе данных, есть способ.

Определите следующую переменную окружения перед запуском Glarus BI:

export MB_DB_AUTOMIGRATE=false

Когда приложение запустится, если необходимы изменения в базе данных, вы получите сообщение, которое укажет, что приложение не может продолжить запуск, пока не будут сделаны указанные обновления:

    2015-12-01 12:45:45,805 [INFO ] metabase.db :: Database Upgrade Required

    NOTICE: Your database requires updates to work with this version of Metabase.  Please execute the following sql commands on your database before proceeding.

    -- *********************************************************************
    -- Update Database Script
    -- *********************************************************************
    -- Change Log: migrations/liquibase.yaml
    -- Ran at: 12/1/15 12:45 PM
    -- Against: @jdbc:h2:file:/Users/agilliland/workspace/metabase/metabase/metabase.db
    -- Liquibase version: 3.4.1
    -- *********************************************************************

    -- Create Database Lock Table
    CREATE TABLE PUBLIC.DATABASECHANGELOGLOCK (ID INT NOT NULL, LOCKED BOOLEAN NOT NULL, LOCKGRANTED TIMESTAMP, LOCKEDBY VARCHAR(255), CONSTRAINT PK_DATABASECHANGELOGLOCK PRIMARY KEY (ID));

    ...

    Once your database is updated try running the application again.

    2015-12-01 12:46:39,489 [INFO ] metabase.core :: Metabase Shutting Down ...

Затем вы можете взять предложенный SQL-скрипт и применить его к вашей базе данных вручную. После этого просто перезапустите Glarus BI. Миграция завершена.

Устранение проблем с миграцией¶

Ознакомьтесь с этим руководством по устранению неполадок.