Files
mtusi2026lab3/openspec/specs/db-migrations/spec.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- 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>
2026-10-08 19:42:36 +03:00

90 lines
5.0 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