Replace the in-memory store with PostgreSQL 18.6: SQLAlchemy 2.1 async engine on asyncpg, alembic migrations with an async env.py, repos on AsyncSession and services that own the transaction. Username uniqueness is enforced by the database (ON CONFLICT), a chat and its members are created in one transaction, member order is kept in chat_members.position, and a composite foreign key makes the sender a member of the chat. History and chat lists use keyset pagination on (chat_id, created_at, id) and (user_id, created_at, chat_id). The compose stand runs postgres, a one-shot migrate service on the API image and the API. All Postgres addresses come from .env without literals; only the 127.0.0.1 publish address stays literal. make run_dev starts Postgres and applies migrations before the server, and make env_setup generates a random Postgres password. Unavailable PostgreSQL yields 503: get_db_session bounds the request with asyncio and classifies driver errors. BoundedCloseConnection limits asyncpg's graceful close, which otherwise waited without limit on a frozen server and held the request until it was resumed. Add scripts/restart.sh for make test-persistence and make test_isolated, which runs the image on a throwaway test database. Remove make run_no_compose. X-User-Id identification is unchanged until the session-auth change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
70 lines
3.7 KiB
Markdown
70 lines
3.7 KiB
Markdown
# Spec Delta
|
||
|
||
## Purpose
|
||
|
||
Как схема PostgreSQL появляется и меняется: версионируемые миграции,
|
||
применение с нуля и повторно без побочных эффектов, запуск миграций до
|
||
старта API в docker и в консоли.
|
||
|
||
## ADDED 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
|