KLIP 42 — инструмент для переноса схем

Автор: Серхио Пенья (@spena) | Целевая версия: 0.17.0; 6.2.0 | Статус: объединён | Обсуждение: https://github.com/confluentinc/ksql/pull/6721

Краткое описание: Новый инструмент, который предоставляет пользователям ksqlDB возможность простого и автоматизированного переноса схем в их средах ksqlDB. Это позволяет пользователям контролировать версии схемы ksqlDB, воссоздавать схему с нуля и переносить текущую схему на более новые версии.

Мотивация и предпосылки

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

Существуют инструменты для выполнения переноса схем для любой базы данных (MySQL, Postgres, Oracle и т. д.). Эти инструменты позволяют пользователям контролировать версию схемы базы данных, а затем автоматизировать процесс, чтобы легко обновить схему до более новой версии. Если схема содержит ошибки, пользователи могут вернуться к предыдущей версии схемы. Ещё одна причина использования этих инструментов — интеграция с любой системой CI/CD, что позволяет пользователям тестировать и проверять, будет ли обновление схемы работать должным образом.

Вы можете узнать больше об этих существующих инструментах:

Flyway (https://flywaydb.org/)
Liquibase (https://www.liquibase.org/)
DBGeni (http://dbgeni.appsintheopen.com/index.html)

ksqlDB требует такой же интеграции с системами CI/CD и автоматизации для развёртывания изменений схемы ksqlDB в любой среде. Некоторые инструменты, такие как Flyway, поддерживают плагины для интеграции переноса схем с другой неподдерживаемой базой данных. Однако наш синтаксис предназначен исключительно для ksqlDB; инструменты требуют поддержки JDBC; и у инструментов есть несколько функций, которые мы не можем поддерживать (например, транзакции и базы данных), поэтому эта интеграция становится сложной или неподдерживаемой. По этой причине ksqlDB должен иметь собственный инструмент переноса схем, чтобы предоставить те же преимущества переноса схем пользователям, которые хотят легко развёртывать и автоматизировать изменения схемы ksqlDB во всех своих средах ksqlDB.

Эти преимущества включают:

Контроль версий сред схемы ksqlDB
Интеграция изменений схемы ksqlDB с средами CI/CD
Упрощение эволюции схемы в разных средах

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

В рамках проекта

Обсуждение деталей конструкции нового инструмента, предоставляющего поддержку переноса схем для ksqlDB

Основные функции для поддержки:

Новый CLI, который может легко интегрироваться с средами CI/CD
Применение переносов в любых средах ksqlDB
Операции пробного запуска для проверки того, какие переносы будут применены без изменения кластера
Контроль версий схемы ksqlDB

Вне рамок проекта

Некоторые функции, имеющиеся в существующих инструментах переноса, не будут поддерживаться
- Выполнение всего переноса в одной транзакции
  
  ksqlDB поддерживает транзакционный метастор. Однако это ограничено DDL-операторами, которые сохраняются в теме Command. Но DML-операторы, такие как INSERT, записываются непосредственно в тему и не работают с транзакциями. Это не позволяет нашему инструменту обеспечить поддержку транзакций для всего процесса переноса. Кроме того, DDL-операторы могут создавать или удалять темы, что выходит за рамки нетранзакционного процесса.
- Поддержка имитационных запусков
  
  Имитация требует, чтобы инструмент знал текущее состояние схемы ksqlDB перед попыткой проверить новые сценарии переноса. Для этого требуется работающий инструмент экспорта метастора ksqlDB. Также, чтобы сделать эту имитацию на 100% безопасной, инструменту требуется фиктивная среда Kafka и SR, которая может проверять проблемы с именами тем и субъектов SR, а также ограничения безопасности. Другие функции, такие как повторяющиеся миграции и обратные вызовы

Для базовой миграции не требуются.

Проведите анализ производительности миграций. В других базах данных есть операции, выполнение которых занимает слишком много времени. Так обстоит дело с операторами ALTER, которые могут добавлять или удалять столбцы, что может занять много времени для выполнения на больших таблицах. Операции ksqlDB выполняются быстро, если только проблема с окружением ksqlDB не влияет на эти выполнения.
Объедините несколько файлов миграции в один. Это очень важная функция, которую пользователи могут захотеть использовать. Со временем у пользователей может накопиться несколько небольших файлов миграции, которые можно объединить в один файл. Однако эта функция выходит за рамки инструмента миграции. Проще написать инструмент метахранилища ksqlDB, который экспортирует метаданные кластера в файл SQL, а затем использовать этот файл SQL в качестве замены пользовательских сценариев миграции.
Новый Java API для разработчиков Java. Эта функция кажется важной. Тем не менее, рассматривается вопрос о необходимости поддержки Java API.

Будущая работа

Отмена миграции схем до предыдущих версий. ksqlDB имеет несколько операторов, поддерживающих отмену, и некоторые из них ограничены. Первая версия для миграций не будет поддерживать эту функцию. Подробная информация об отмене описана в документе для дальнейшего использования. Также необходимо подготовить метаданные схемы (см. Метаданные схемы) для будущих операций отмены.
Команда baseline для экспорта существующих потоков, таблиц, запросов и пользовательских типов в файл миграции. Это относится к инструменту «экспортёр метаданных», который мы хотели бы добавить отдельно от инструмента миграции. Инструмент позволит пользователям экспортировать текущее состояние своего кластера ksqlDB в виде серии операторов SQL, которые можно запустить, чтобы привести новый кластер в соответствие с текущим. Команда migrations baseline будет использовать ту же функциональность экспорта для создания файла миграции.

Ценность/Возврат

Пользователи смогут интегрировать тестирование обновлений ksqlDB с любыми средами CI/CD по своему выбору. Это огромное преимущество для пользователей, которые хотят автоматизировать обновления ksqlDB вместе с жизненным циклом приложения.

Кроме того, новый инструмент позволит пользователям легко автоматизировать эволюцию схемы и изменения миграции. Они смогут развёртывать новые изменения схемы во всех своих окружениях (Prod, QA, Devel и т. д.).

Публичные API

Никаких изменений в текущих публичных API.
Новый инструмент командной строки для миграции.

Дизайн

Я собираюсь использовать синтаксис и поведение инструментов Flyway и DBGeni для разработки инструмента миграции ksqlDB. Пользователи будут определять новую миграцию в сценарии SQL. Этот новый сценарий SQL описывает изменения, необходимые для перехода кластера из состояния A в состояние B. Затем запустите миграцию из командной строки, чтобы применить новое состояние в кластере ksqlDB. Пользователи также могут запускать эту миграцию автоматически как часть процесса сборки и/или тестирования в среде CI/CD.

Например, следующий пример создаёт новый файл, который устанавливает начальное состояние кластера.

V000001__Initial_setup.sql

CREATE STREAM pageviews (
    user_id INTEGER KEY, 
    url STRING, 
    status INTEGER
) WITH (
    KAFKA_TOPIC='pageviews', 
    VALUE_FORMAT='JSON'    
);

CREATE TABLE pageviews_metrics AS
 SELECT url, COUNT(*) AS num_views
  FROM pageviews
  GROUP BY url
  EMIT CHANGES;

Пользователь запускает инструмент миграции на конкретном кластере ksqlDB. Инструмент обновляет кластер, выполняя операторы SQL из приведённого выше файла. Затем устанавливает состояние кластера на версию 1.

$ ksql-migrations apply
Current version of schema: << Empty Schema >>
Migrating schema to version 1 - Initial setup

Позже пользователю потребуются новые изменения в кластере. Все предыдущие файлы миграции являются неизменными. Поэтому любые изменения в кластере требуют нового файла миграции (или сценария SQL). Давайте создадим один для создания таблицы users.

V000002__Add_users.sql

CREATE TABLE users (
   ID BIGINT PRIMARY KEY, 
   STRING NAME, 
   ADDRESS ADDRESS_TYPE
 ) WITH (
   KAFKA_TOPIC='users', 
   VALUE_FORMAT='JSON' 
 );

Пользователь снова запускает инструмент миграции в том же кластере. Процесс миграции может быть одним из следующих: «Ожидает», «Выполняется», «Мигрировано», «Ошибка», «Отменено».

Столбец «checksum» содержит контрольную сумму MD5 файла миграции. Она используется для проверки соответствия схемы локальных файлов миграций.

В столбце «started_on» указана дата и время начала миграции.

В столбец «completed_on» записывается дата и время завершения миграции.

Столбец «previous» содержит предыдущую версию, которая была применена.

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

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

Это оператор CREATE для таблицы SCHEMA_VERSION:

CREATE TABLE schema_version /* имя будет настраиваемым */
  WITH (
    KAFKA_TOPIC='default_ksql_schema_version', /* тема будет настраиваемой */
  )
  AS SELECT 
    version_key, 
    latest_by_offset(version) as version, 
    latest_by_offset(name) AS name, 
    latest_by_offset(state) AS state,     
    latest_by_offset(checksum) AS checksum, 
    latest_by_offset(started_on) AS started_on, 
    latest_by_offset(completed_on) AS completed_on, 
    latest_by_offset(previous) AS previous
  FROM migration_events 
  GROUP BY version_key;

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

Вывод потока MIGRATION_EVENTS:

+-------------+---------+---------------+----------+------------+---------------------+---------------------+----------+
| version_key | version | name          | state    | checksum   | started_on          | completed_on        | previous |
+-------------+---------+---------------+----------+------------+---------------------+---------------------+----------+
| 1           | 1       | Initial setup | Running  | <MD5-сумма> | 2020-01-12 03:48:00 | null                | null     |
| CURRENT     | 1       | Initial setup | Running  | <MD5-сумма> | 2020-01-12 03:48:00 | null                | null     |
| 1           | 1       | Initial setup | Migrated | <MD5-сумма> | 2020-01-12 03:48:00 | 2020-01-12 03:48:05 | null     |
| CURRENT     | 1       | Initial setup | Migrated | <MD5-сумма> | 2020-01-12 03:48:00 | 2020-01-12 03:48:05 | null     |
| 2           | 2       | Add users     | Running  | <MD5-сумма> | 2020-03-12 10:34:30 | null                | 1        |
| CURRENT     | 2       | Add users     | Running  | <MD5-сумма> | 2020-03-12 10:34:30 | null                | 1        |
| 2           | 2       | Add users     | Migrated | <MD5-сумма> | 2020-03-12 10:34:30 | 2020-03-12 10:34:34 | 1        |
| CURRENT     | 2       | Add users     | Migrated | <MD5-сумма> | 2020-03-12 10:34:30 | 2020-03-12 10:34:34 | 1        |
+-------------+---------+---------------+----------+------------+---------------------+---------------------+----------+

Вывод таблицы SCHEMA_VERSION:

+-------------+---------+---------------+----------+------------+---------------------+---------------------+----------+
| version_key | version | name          | state    | checksum   | started_on          | completed_on        | previous |
+-------------+---------+---------------+----------+------------+---------------------+---------------------+----------+
| 1           | 1       | Initial setup | Migrated | <MD5-сумма> | 2020-01-12 03:48:00 | 2020-01-12 03:48:05 | null     |
| 2           | 2       | Add users     | Undone   | <MD5-сумма> | 2020-03-12 10:34:30 | 2020-03-12 10:34:34 | 1        |
| CURRENT     | 2       | Add users     | Undone   | <MD5-сумма> | 2020-03-12 10:34:30 | 2020-03-12 10:34:34 | 1        | **Инструмент будет использовать запросы на извлечение для определения текущего состояния системы:**

```sql
SELECT version, state, previous FROM SCHEMA_VERSION WHERE version_key = 'CURRENT';

Правила именования

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

Файлы миграции следуют тому же соглашению об именах Flyway. (Префикс)(Версия)__(Описание).sql

Префикс указывает, является ли файл новым файлом миграции (V) или, когда поддержка в конечном итоге будет добавлена, файлом отмены (U).
Версия — это номер версии, используемый для схемы. Версии не будут поддерживать десятичные версии. Используются целые числа с 6 цифрами.
Описание — это имя или описание новой миграции. В описании используются символы подчёркивания (автоматически заменяемые пробелами во время выполнения) или пробелы, разделяющие слова.

Например:

- V000001__Initial_setup.sql    # новая версия для миграции (v1) с именем «Начальная настройка»
- V000002__Add_users.sql        # новая версия для миграции (v2) с именем «Добавить пользователей»

Пробные запуски

Пробный запуск миграций ksqlDB только проверит, какие миграции будут применены в кластере. Он не будет пытаться выполнить или смоделировать какое-либо оператор миграции, найденный в файлах. Эта функция позволит пользователям проверить, что файлы миграции имеют правильные номера версий и описания, а также узнать, какие миграции будут применяться в определённом кластере.

Структура каталогов

Инструмент миграции будет использовать следующую структуру каталогов:

| |- ksql-migrations.properties |- migrations/

Когда инструмент миграции будет запущен, он будет искать файлы SQL миграции в каталоге migrations (по умолчанию), чтобы выполнить их. Этот каталог можно изменить в файле конфигурации или параметрах командной строки.

Если файл ksql-migrations.properties существует в корневом каталоге, то он будет использовать конфигурацию, предоставленную файлом.

Синтаксис команды

Наконец, давайте рассмотрим остальные параметры команды, которые будут существовать для облегчения миграции схем.

Использование:
  ksql-migrations [параметры] команды
  
Команды
  new <путь проекта> Создаёт новый проект миграции, структуру каталогов и файл конфигурации.
  
  initialize
   
                 Инициализирует метаданные схемы (поток и таблица).   
  
  create [-v <версия>] <описание> 
  
                 Создаёт пару файлов миграции с <описанием> в качестве описания.
                 Необязательно: используйте <версию>, чтобы указать версию для использования.
   
                 Это создаст пару пустых файлов миграции на основе
                 следующей версии схемы.
               
                 Например:                  
                   $ ksql-migrations create add_users 
                   Создано V000002__Add_users.sql

  apply ( all | next | until <цель> )
  
              Мигрирует схему к новым доступным версиям схемы (по умолчанию: все)
              
              Если указано «all», то мигрируются все более новые доступные версии
              Если указано «next», то мигрируется только следующая доступная версия
              Если указано «until <цель>», то мигрируются все доступные версии до и включая <цель>
  
  info Отображает информацию о текущих и доступных миграциях
  
  clean Очищает объекты метаданных схемы
  
  validate Проверяет применённые миграции по локальным файлам
  
              Сравнивает контрольную сумму локальных файлов с текущей контрольной суммой метаданных, чтобы проверить наличие файлов миграции, которые изменились.
              Это сообщает пользователю, что его схема может быть недействительной по сравнению с его локальными файлами.
 
  abort Прерывает текущую транзакцию. См. «Переходы состояний миграции и потенциальные гонки». **План тестирования**

* Проверить положительные и отрицательные прямые миграции.
* Проверить интеграцию с Github и Jenkins.
* Запустить инструмент миграций в поддерживаемых защищённых средах.

**Основные этапы и контрольные точки поставки**

Контрольные точки:
* Инструмент со всеми поддерживаемыми командами готов.
* Настройка безопасности (аутентификация + SSL) завершена.
* Проверка общих сценариев использования (например, CI/CD и т. д.) завершена.
* Руководство по быстрому старту и пользовательская документация готовы.

**Обновления документации**

* Новое руководство по быстрому старту для миграций схемы ksqlDB.
* Новая подробная документация о командах и конфигурациях миграций.

**Последствия для совместимости**

Никаких последствий для совместимости.

**Последствия с точки зрения безопасности**

Этот инструмент требует такой же настройки безопасности, как и любой другой клиент ksqlDB, включая аутентификацию пользователя и SSL-соединение с сервером ksqlDB.

OSCHINA-MIRROR/mirrors-KSQL

KLIP 42 — инструмент для переноса схем

Мотивация и предпосылки

В рамках проекта

Вне рамок проекта

Будущая работа

Ценность/Возврат

Публичные API

Дизайн

Правила именования

Пробные запуски

Структура каталогов

Синтаксис команды

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/mirrors-KSQL .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

KLIP 42 — инструмент для переноса схем

Мотивация и предпосылки

В рамках проекта

Вне рамок проекта

Будущая работа

Ценность/Возврат

Публичные API

Дизайн

Правила именования

Пробные запуски

Структура каталогов

Синтаксис команды

Опубликовать ( 0 )

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/mirrors-KSQL