Files
mtusi2026lab4/openspec/specs/db-migrations/spec.md
T
ricoromaandClaude Opus 5.5 dba40bc325 fix: address attachments verify findings
- keep one upload body in memory: BytesIO + getvalue() without copy,
  fixed glibc mmap threshold in the image (no realloc copy on growth)
- stop PNG inflate at expected size + 1 byte
- reject filename that is not valid UTF-8 after percent-decoding (400)
- failure stand: env limit variables do not change attachment limits;
  history with attachment_ids while S3 is stopped
- drop dead constants; restate "old image on new schema" scenario

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 02:16:49 +03:00

182 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 добавляться без проверки существующих
строк под эксклюзивной блокировкой таблицы: эти строки уже
удовлетворяли более строгому условию.
Удаление и переименование таблицы, колонки или ограничения (кроме
замены ограничения ослабленным), а также новое ограничение, которое
нарушит запись прежней версии, MUST NOT входить в ту же поставку, что и
код, которому они нужны. Такое изменение выполняется отдельной миграцией
после того, как реплик прежней версии не осталось (expand/contract).
Если так сделать нельзя, ограничение SHALL описываться в `REPORT.md`.
Реплики прежнего образа SHALL обслуживать обязательные запросы на
схеме после новой миграции. Откат кода к прежнему образу MUST NOT
требовать отката схемы.
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
Долгая транзакция приложения не должна заставить миграцию держать
очередь за собой и остановить запись остальных реплик. Срок SHALL быть
меньше срока запроса приложения к БД (`statement_timeout`): запросы,
вставшие в очередь за миграцией, дожидаются её отказа и выполняются, а
не завершаются ошибкой вместе с ним. По истечении срока миграция SHALL
завершаться ошибкой без изменения схемы, а её повторный запуск SHALL
проходить.
#### Scenario: Старый образ на новой схеме
- **WHEN** стенд работает на образе прежнего commit, и миграции нового
образа применены, а реплики не заменены
- **THEN** проверки, которые прежний образ проходил на прежней схеме,
проходят и на новой: запись сообщений через прежние реплики — 201,
история — 200, ответов 5xx нет (замер замены реплик —
`evidence/rollout/attachments/summary.md`)
- **AND** проверки, которых прежний образ не проходил и на прежней схеме
(новые требования контракта, например вложения лабы 4 для образа лабы
4 до `attachments`), совместимостью схемы не считаются
#### Scenario: Запись прежней версии
- **WHEN** после новой миграции сообщение отправлено через реплику
прежнего образа
- **THEN** ответ 201, а сообщение видно в истории через реплику любого
образа
#### Scenario: Блокировка не получена
- **WHEN** таблицу, которую меняет миграция, держит открытая
транзакция дольше срока ожидания блокировки
- **THEN** миграция завершается ошибкой, схема не меняется, запросы
других клиентов, ждавшие за миграцией, получают успешный ответ, а
после окончания транзакции повторный запуск применяет миграцию
#### Scenario: Ослабленное ограничение
- **WHEN** миграция вложений заменяет ограничение длины текста
сообщения (было 1–4000, стало 0–4000) на таблице с сообщениями, а
запись идёт через реплики прежнего образа
- **THEN** миграция не проверяет существующие строки, записи прежних
реплик во время и после неё — 201, а после замены реплик сообщение с
пустым текстом и вложением — 201
### Requirement: Однократные миграции при замене реплик
Поочерёдная замена реплик (`load-balancing`) SHALL применять миграции
один раз за запуск: отдельным одноразовым контейнером на новом образе,
после сборки образа и до запуска первой новой реплики. Реплики MUST
NOT запускать миграции сами. Если миграция завершилась ошибкой, замена
MUST NOT начинаться: работающие реплики не трогаются, скрипт
завершается с ненулевым кодом.
#### Scenario: Одна миграция на замену
- **WHEN** выполнен `make rolling_update` для двух реплик
- **THEN** в журнале замены одна миграция до первой новой реплики, в
журналах реплик записей alembic нет, а ревизия схемы после замены —
последняя
#### Scenario: Миграция упала
- **WHEN** миграция при замене завершается ошибкой
- **THEN** скрипт завершается с ненулевым кодом до запуска новых
реплик, а прежние реплики работают и обслуживают запросы