Files
mtusi2026lab6/openspec/specs/db-migrations/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
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>
2026-11-11 04:46:56 +03:00

14 KiB

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 скрипт завершается с ненулевым кодом до запуска новых реплик, а прежние реплики работают и обслуживают запросы