Модель данных и ER-диаграмма

Раздел модели данных связывает контракт API с базой данных. Он позволяет вывести полную реляционную модель из схем OpenAPI, сравнить её с существующей базой и поддерживать соответствие при изменении любой стороны. ER-диаграмма показывает общую картину.

Поддерживаются оба исходных случая:

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

Сопоставление на четырёх уровнях

Сопоставление (datamodel.reconcile) возвращает достоверные сведения на четырёх уровнях:

Уровень	Содержимое
Наблюдаемое	Таблицы базы без соответствия в модели, а также внешние ключи, существующие только в базе или закреплённые ограничениями
Смоделированное	Состояние каждой таблицы (missing, drift, matched, extra), пары столбцов модели и базы, различия полей, затронутые операции API и смоделированные связи
Предлагаемое	Упорядоченный план добавочной миграции с зависимостями blockedBy и SQL для каждого шага
Выведенное	Автоматически выведенные связующие таблицы для отношений многие-ко-многим, открытые вопросы и защитные проверки

Модель основывает каждую таблицу, столбец, связь и инструкцию на этом результате, а не выдумывает DDL.

Состояние таблицы

• Отсутствует (новая): следует из API, но отсутствует в базе;
• Расхождение: есть с обеих сторон, но столбцы или ограничения различаются;
• Совпадает: существует и соответствует модели;
• Дополнительная: существует в базе, но не следует из текущих API.

Связующие таблицы и индексы выводятся автоматически

Не нужно вручную моделировать таблицы связей. Если схемы предполагают отношение многие-ко-многим, например между ресурсами user и product, выведенный уровень создаёт описание связующей таблицы и нужных индексов, не ограничиваясь двумя базовыми таблицами. Вторичные индексы включаются в сгенерированный SQL.

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

ER-диаграмма

Представление ER показывает модель в виде графа, чтобы связи и внешние ключи были видны сразу, без изучения списка таблиц:

• Таблицы представлены узлами, которые располагаются автоматически для уменьшения пересечений связей;
• Внешние ключи показаны соединениями;
• Состояние узла отражает результат сопоставления: новая, расходящаяся, совпадающая или дополнительная таблица;
• Боковая панель перечисляет конкретные шаги миграции: create_table, alter_table и элементы для проверки, а также SQL выбранной таблицы.

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

Анализ влияния в обоих направлениях

Модель знает и операции API, и таблицы, поэтому последствия изменений видны с обеих сторон:

• При изменении API сопоставление определяет затронутые таблицы: существующие с расхождениями и новые, которые нужно добавить, вместе с соответствующим SQL;
• При изменении базы выделяются операции, обращающиеся к затронутым таблицам.

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

Скрипт развёртывания

Для новой базы datamodel.deploymentScript создаёт единый идемпотентный SQL-скрипт, выполняющий только прямые изменения:

• CREATE TABLE IF NOT EXISTS в порядке зависимостей внешних ключей;
• Вторичные индексы;
• Необязательные детерминированные строки примеров: от 0 до 50, по умолчанию 0; связующие таблицы данными не заполняются.

Для существующей базы используйте сопоставление: оно создаёт добавочные инструкции ALTER в виде упорядоченного плана миграции.

Подключения к базам

Подключения хранятся в виде профилей: ID, имя, диалект, хост, порт, пользователь и база. Пароли никогда не возвращаются. Поддерживаются MySQL, SQL Server и Oracle.

• database.runSelect выполняет только читающий запрос SELECT через сохранённый профиль и возвращает ограниченный, усечённый набор строк; запись и DDL блокируются;
• database.prefillConnection открывает окно нового подключения с заполненными переданными параметрами, чтобы вы вводили пароль сами, а не передавали его в запросе к модели.

SQL создаётся, но не выполняется автоматически

В этом разделе SQL создаётся для проверки, а не исполняется в вашей базе. Вы сами решаете, когда и как его применить; доступ только для чтения защищает существующие данные. Можно изучать и уточнять модель до внесения изменений в базу.

См. также: Протоколы, Рабочая область запросов, Настройки.