- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
90 lines
5.0 KiB
Markdown
90 lines
5.0 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
|