# 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