Files
mtusi2026lab2/openspec/specs/db-migrations/spec.md
T
ricoromaandClaude Opus 5.5 ae4154eaf5 feat: add password login and bearer sessions
- Argon2id password hashes, KDF in a thread with its own limit
- POST /auth/sessions with Basic, DELETE /auth/sessions/current
- Bearer sessions in PostgreSQL, X-User-Id ignored
- migration drops lab 1 data without passwords
- student-tests on tokens, sessions spec and synced specs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 18:50:42 +03:00

5.0 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