Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
202 lines
14 KiB
Markdown
202 lines
14 KiB
Markdown
# db-migrations Specification
|
||
|
||
## Purpose
|
||
|
||
Как схема PostgreSQL появляется и меняется: версионируемые миграции,
|
||
применение с нуля и повторно без побочных эффектов, запуск миграций до
|
||
старта API в docker и в консоли.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Схема версионируется миграциями
|
||
|
||
Таблицы, ограничения и индексы SHALL создаваться только миграциями из
|
||
репозитория. Сервис MUST NOT создавать или менять схему при старте.
|
||
Применённая миграция MUST NOT редактироваться: изменение схемы — новая
|
||
миграция поверх.
|
||
|
||
#### Scenario: Схема с нуля
|
||
|
||
- **WHEN** миграции применяются к пустой базе на новом volume
|
||
- **THEN** создаются все таблицы, ограничения и индексы, и сервис
|
||
обслуживает обязательные запросы без ручных шагов
|
||
|
||
### Requirement: Повторный запуск миграций
|
||
|
||
Повторное применение миграций к актуальной схеме SHALL завершаться
|
||
успешно и MUST NOT менять схему или данные. Миграции MUST NOT
|
||
создавать пользовательские данные.
|
||
|
||
#### Scenario: Второй прогон
|
||
|
||
- **WHEN** миграции применены, в базе есть пользователи, чаты и
|
||
сообщения, и миграции применяются ещё раз
|
||
- **THEN** команда завершается с кодом 0, а число строк во всех таблицах
|
||
не меняется
|
||
|
||
### Requirement: Миграции до старта API в docker
|
||
|
||
В стенде compose миграции SHALL применяться отдельным одноразовым
|
||
сервисом на образе приложения после готовности PostgreSQL. API SHALL
|
||
стартовать только после успешного завершения миграций. Если миграции
|
||
завершились ошибкой, API MUST NOT стартовать.
|
||
|
||
#### Scenario: Порядок запуска
|
||
|
||
- **WHEN** стенд поднимается командой `make run_docker`
|
||
- **THEN** сервис миграций завершается с кодом 0 раньше, чем стартует
|
||
API, а `/health/ready` отвечает 200
|
||
|
||
#### Scenario: Ошибка миграции
|
||
|
||
- **WHEN** применение миграций завершается ошибкой
|
||
- **THEN** контейнер API не запускается, а ошибка видна в журнале
|
||
сервиса миграций
|
||
|
||
### Requirement: Миграции до старта API в консоли
|
||
|
||
`make run_dev` SHALL одной командой поднимать PostgreSQL из compose,
|
||
дожидаться его готовности, применять миграции и запускать сервис на
|
||
хосте. Отдельно миграции SHALL применяться командой `make upgrade`,
|
||
новая ревизия SHALL создаваться командой `make revision` на базе с
|
||
актуальной схемой.
|
||
|
||
#### Scenario: Консольный запуск с нуля
|
||
|
||
- **WHEN** в свежем clone после `make env_setup` выполняется
|
||
`make run_dev`
|
||
- **THEN** Postgres запущен, миграции применены, сервис отвечает на
|
||
`http://127.0.0.1:8080/health/ready` кодом 200
|
||
|
||
### Requirement: Миграция, удаляющая данные
|
||
|
||
Миграция MUST NOT удалять данные, которые можно привести к новой схеме.
|
||
Миграция, которая удаляет данные, SHALL записывать в журнал сервиса миграций,
|
||
сколько строк удалено, а её повторный запуск MUST NOT ничего удалять.
|
||
Об удалении SHALL предупреждать `REPORT.md`.
|
||
|
||
#### Scenario: Пользователи без пароля
|
||
|
||
- **WHEN** миграция, которая делает хэш пароля обязательным, применяется
|
||
к базе с пользователями лабы 1
|
||
- **THEN** пользователи, их чаты, участники и сообщения удалены, в
|
||
журнале `migrate` есть число удалённых пользователей, а схема требует
|
||
хэш пароля у каждого пользователя
|
||
|
||
#### Scenario: Пустая база
|
||
|
||
- **WHEN** та же миграция применяется к пустой базе или повторно
|
||
- **THEN** ничего не удаляется, и команда завершается с кодом 0
|
||
|
||
### Requirement: Совместимость миграции с работающей версией
|
||
|
||
Миграция SHALL только расширять схему:
|
||
- новая таблица со своими ограничениями и внешними ключами;
|
||
- новая колонка, допускающая NULL или со значением по умолчанию;
|
||
- новый индекс; на таблице, в которую идёт запись, — без блокировки записи на время
|
||
сборки;
|
||
- ослабление ограничения: новое условие пропускает всё, что пропускало
|
||
прежнее, поэтому прежняя версия не пишет значений, которые новое
|
||
условие запретит.
|
||
|
||
Ослабленное ограничение SHALL добавляться без проверки существующих
|
||
строк под эксклюзивной блокировкой таблицы: эти строки уже
|
||
удовлетворяли более строгому условию. Новое ограничение на новые колонки
|
||
существующей таблицы SHALL добавляться так же: прежняя версия эти колонки не
|
||
пишет, а значения прежних строк ему удовлетворяют.
|
||
|
||
Удаление и переименование таблицы, колонки или ограничения (кроме
|
||
замены ограничения ослабленным), а также новое ограничение, которое
|
||
нарушит запись прежней версии, MUST NOT входить в ту же поставку, что и
|
||
код, которому они нужны. Такое изменение выполняется отдельной миграцией
|
||
после того, как реплик прежней версии не осталось (expand/contract).
|
||
Если так сделать нельзя, ограничение SHALL описываться в `REPORT.md`.
|
||
|
||
Реплики прежнего образа SHALL обслуживать обязательные запросы на
|
||
схеме после новой миграции. Откат кода к прежнему образу MUST NOT
|
||
требовать отката схемы. Новые значения статуса вложения прежний образ
|
||
прочитать не может; это ограничение смешанных версий при переходе 4 → 5 SHALL
|
||
быть в `REPORT.md`.
|
||
|
||
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
|
||
Долгая транзакция приложения не должна заставить миграцию держать
|
||
очередь за собой и остановить запись остальных реплик. Срок SHALL быть
|
||
меньше срока запроса приложения к БД (`statement_timeout`): запросы,
|
||
вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а
|
||
не завершаются ошибкой вместе с ним. По истечении срока миграция SHALL
|
||
завершаться ошибкой без изменения схемы, а её повторный запуск SHALL
|
||
проходить.
|
||
|
||
#### Scenario: Старый образ на новой схеме
|
||
|
||
- **WHEN** стенд работает на образе прежнего commit, и миграции нового
|
||
образа применены, а реплики не заменены
|
||
- **THEN** проверки, которые прежний образ проходил на прежней схеме,
|
||
проходят и на новой: запись сообщений через прежние реплики — 201,
|
||
история — 200, ответов 5xx нет (замер замены реплик —
|
||
`evidence/rollout/pipeline-reliability/summary.md`)
|
||
- **AND** проверки, которых прежний образ не проходил и на прежней схеме
|
||
(новые требования контракта, например вложения лабы 4 для образа лабы
|
||
4 до `attachments`), совместимостью схемы не считаются
|
||
|
||
#### Scenario: Запись прежней версии
|
||
|
||
- **WHEN** после новой миграции сообщение отправлено через реплику
|
||
прежнего образа
|
||
- **THEN** ответ 201, а сообщение видно в истории через реплику любого
|
||
образа
|
||
|
||
#### Scenario: Блокировка не получена
|
||
|
||
- **WHEN** таблицу, которую меняет миграция, держит открытая
|
||
транзакция дольше срока ожидания блокировки
|
||
- **THEN** миграция завершается ошибкой, схема не меняется, запросы
|
||
других клиентов, ждавшие за миграцией, получают успешный ответ, а
|
||
после окончания транзакции повторный запуск применяет миграцию
|
||
|
||
#### Scenario: Ослабленное ограничение
|
||
|
||
- **WHEN** миграция вложений заменяет ограничение длины текста
|
||
сообщения (было 1–4000, стало 0–4000) на таблице с сообщениями, а
|
||
запись идёт через реплики прежнего образа
|
||
- **THEN** миграция не проверяет существующие строки, записи прежних
|
||
реплик во время и после неё — 201, а после замены реплик сообщение с
|
||
пустым текстом и вложением — 201
|
||
|
||
#### Scenario: Новые состояния вложения
|
||
|
||
- **WHEN** миграция обработки вложений применена к базе с вложениями `pending`
|
||
и `ready`, а реплики прежнего образа ещё работают
|
||
- **THEN** миграция не проверяет существующие строки под эксклюзивной
|
||
блокировкой, их `status` прежний, загрузка через прежнюю реплику проходит,
|
||
как раньше, а повторный запуск миграций ничего не меняет
|
||
|
||
#### Scenario: Поля надёжности обработки
|
||
|
||
- **WHEN** миграции этого уровня применены к базе с заданиями всех состояний, а реплики и
|
||
worker прежнего образа ещё работают
|
||
- **THEN** индексы построены без блокировки записи, задание прежнего образа вставляется без
|
||
новых колонок, прежние строки не меняются, а повторный запуск миграций ничего не меняет
|
||
|
||
### Requirement: Однократные миграции при замене реплик
|
||
|
||
Поочерёдная замена реплик (`load-balancing`) SHALL применять миграции
|
||
один раз за запуск: отдельным одноразовым контейнером на новом образе,
|
||
после сборки образа и до запуска первой новой реплики. Реплики MUST
|
||
NOT запускать миграции сами. Если миграция завершилась ошибкой, замена
|
||
MUST NOT начинаться: работающие реплики не трогаются, скрипт
|
||
завершается с ненулевым кодом.
|
||
|
||
#### Scenario: Одна миграция на замену
|
||
|
||
- **WHEN** выполнен `make rolling_update` для двух реплик
|
||
- **THEN** в журнале замены одна миграция до первой новой реплики, в
|
||
журналах реплик записей alembic нет, а ревизия схемы после замены —
|
||
последняя
|
||
|
||
#### Scenario: Миграция упала
|
||
|
||
- **WHEN** миграция при замене завершается ошибкой
|
||
- **THEN** скрипт завершается с ненулевым кодом до запуска новых
|
||
реплик, а прежние реплики работают и обслуживают запросы
|