feat: finish postgres-storage change
- keep engine and session factory in src/infra/db/session.py - sync delta specs into openspec/specs, add db-migrations spec - update rules, AGENTS.md and run skill for lab 2 storage - fill REPORT.md for the storage part Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -153,7 +153,23 @@ created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает
|
||||
|
||||
### 5. Engine, пул и таймауты
|
||||
|
||||
`create_async_engine` в lifespan, `engine.dispose()` в shutdown.
|
||||
Engine и фабрика сессий — глобалы `src/infra/db/session.py`. Они
|
||||
создаются при импорте по `settings.database` (пул открывает соединения
|
||||
лениво, при первом запросе), а `engine.dispose()` вызывается в lifespan.
|
||||
Модуль импортируют только `src/main.py` и `src/api/dependencies.py`:
|
||||
пакет `src/infra/db` и модели его не тянут, поэтому alembic и скрипты
|
||||
engine не создают. Фабрика `create_engine(database)` остаётся для
|
||||
процесса со своим пулом (worker с лабы 5).
|
||||
|
||||
*Альтернатива:* создавать engine в lifespan и класть в `app.state`, как
|
||||
было в первой реализации. Сравнение с wms_backend (там глобалы модуля) по
|
||||
критериям этого проекта: настройки читаются один раз на процесс, поэтому
|
||||
создание в lifespan гибкости не даёт; тесты black-box по HTTP, подмена
|
||||
engine внутри процесса не нужна, а `test_isolated` подменяет базу через
|
||||
окружение до старта процесса; `app.state` даёт нетипизированный
|
||||
`getattr` и ветки «engine ещё не создан», которых после старта не
|
||||
бывает. Отвергнута.
|
||||
|
||||
Параметры — секция `[database]`, значения по умолчанию:
|
||||
|
||||
| Параметр | По умолчанию | Зачем |
|
||||
@@ -210,7 +226,7 @@ created_at, id`, `LIMIT limit + 1`. `uuid` Postgres сравнивает
|
||||
asyncpg обрывает соединение. Отсюда «6 + 2 с» в таблице.
|
||||
|
||||
`/health/ready` не ходит через эту зависимость: отдельная проверка
|
||||
`SELECT 1` с таймаутом через engine из `app.state`.
|
||||
`SELECT 1` с таймаутом через глобальный engine.
|
||||
|
||||
*Альтернативы:* обработчик исключений SQLAlchemy в `errors.py` —
|
||||
отвергнут, `errors.py` не логирует (`logging.md`), а потеря БД в логе
|
||||
|
||||
@@ -88,7 +88,8 @@ commit»).
|
||||
одна транзакция (решение 4); удалить `MemoryStore`, `get_store` и
|
||||
`src/infra/memory.py`. Проверка: `grep -rn MemoryStore src` пусто,
|
||||
`make lint` чистый.
|
||||
- [x] 4.3 `src/main.py`: engine в lifespan, `dispose()` при остановке;
|
||||
- [x] 4.3 Engine и фабрика сессий — глобалы `src/infra/db/session.py`
|
||||
(решение 5), `dispose()` в lifespan `src/main.py`;
|
||||
`dependencies.py`: `get_db_session`, фабрики сервисов;
|
||||
`get_current_user` по-прежнему по `X-User-Id`. Проверка: `make
|
||||
run_dev` поднимается до `/health/ready` 200; по SIGTERM в журнале
|
||||
@@ -101,59 +102,59 @@ commit»).
|
||||
(`docker compose pause postgres`); записать исключения из traceback
|
||||
для отказа в соединении, клиентского таймаута и таймаута пула.
|
||||
Проверка: список внесён в решение 6 `design.md`.
|
||||
- [ ] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`,
|
||||
- [x] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`,
|
||||
`ServiceUnavailable`. Проверка: сценарии «БД остановлена» и «БД
|
||||
вернулась» (`data-storage`) — 503 `unavailable` без деталей, после
|
||||
`docker compose start postgres` запросы проходят без рестарта API;
|
||||
вывод в `evidence/storage/db-unavailable.txt`.
|
||||
- [ ] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine.
|
||||
вывод в `evidence/storage/db-unavailable.md`.
|
||||
- [x] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine.
|
||||
Проверка: при остановленном Postgres `/health/ready` — 503 не позже
|
||||
таймаута, `/health/live` — 200.
|
||||
- [ ] 5.4 Сценарий «Соединения исчерпаны»: `DATABASE__POOL_SIZE=1`,
|
||||
- [x] 5.4 Сценарий «Соединения исчерпаны»: `DATABASE__POOL_SIZE=1`,
|
||||
`DATABASE__MAX_OVERFLOW=0`, `DATABASE__POOL_TIMEOUT_SECONDS=1`,
|
||||
Postgres на паузе, два одновременных запроса. Проверка: второй
|
||||
получает 503 примерно через 1 с, первый — 503 после
|
||||
`request_timeout_seconds` и закрытия соединения (6 + 2 с); вывод в
|
||||
`evidence/storage/pool-timeout.txt`.
|
||||
`evidence/storage/pool-timeout.md`.
|
||||
|
||||
## 6. Рестарт стенда
|
||||
|
||||
- [ ] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git.
|
||||
- [x] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git.
|
||||
Проверка: `git ls-files -s scripts/restart.sh` — режим `100755`;
|
||||
скрипт укладывается в 90 с; по журналу записано, прогоняет ли `up`
|
||||
сервис `migrate` заново.
|
||||
- [ ] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний
|
||||
- [x] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний
|
||||
пользователь после рестарта» (`data-storage`): пользователь, чат с
|
||||
`member_ids` в порядке `[bob, alice]`, сообщения; `StartedAt` до и
|
||||
после `scripts/restart.sh`. Проверка: после рестарта тот же
|
||||
`X-User-Id` получает 200, история и порядок участников прежние;
|
||||
вывод в `evidence/storage/restart.txt`.
|
||||
вывод в `evidence/storage/restart.md`.
|
||||
|
||||
## 7. Проверки стенда
|
||||
|
||||
- [ ] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make
|
||||
- [x] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make
|
||||
student_test` против `make run_dev` и против `make run_docker`.
|
||||
Проверка: в обоих прогонах прошли все тесты, кроме
|
||||
`test_security_scheme_in_openapi` (переход контракта, design, Goals).
|
||||
Evidence набора против контейнера снимает `session-auth`.
|
||||
- [ ] 7.2 Миграции с нуля и повторно (`db-migrations`): `make
|
||||
- [x] 7.2 Миграции с нуля и повторно (`db-migrations`): `make
|
||||
wipe_data`, `make run_docker`, журнал `migrate`; затем повторный
|
||||
прогон миграций при данных в базе. Проверка: `migrate` завершился
|
||||
с кодом 0 раньше старта API; число строк во всех таблицах до и после
|
||||
повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.txt`.
|
||||
- [ ] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`,
|
||||
повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.md`.
|
||||
- [x] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`,
|
||||
`POSTGRES_OUT_PORT=5545` в `.env`, compose не правится. Проверка:
|
||||
`make run_docker` доходит до `/health/ready` 200, `make run_dev`
|
||||
подключается к `127.0.0.1:5545`; `.env` возвращён; вывод в
|
||||
`evidence/storage/postgres-port.txt`.
|
||||
- [ ] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и
|
||||
`evidence/storage/postgres-port.md`.
|
||||
- [x] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и
|
||||
«down сохраняет данные» (`container-run`). Проверка: данные,
|
||||
созданные через `make run_dev`, видны после `make run_docker` и после
|
||||
`make down` + `make run_docker`, файлы конфигурации не менялись.
|
||||
- [ ] 7.5 Сценарий «Адрес публикации» (`container-run`). Проверка:
|
||||
- [x] 7.5 Сценарий «Адрес публикации» (`container-run`). Проверка:
|
||||
`docker port` для API и Postgres стенда показывает `127.0.0.1`, а не
|
||||
`0.0.0.0`.
|
||||
- [ ] 7.6 Механика «Прогон на временной базе» (`student-tests`) при
|
||||
- [x] 7.6 Механика «Прогон на временной базе» (`student-tests`) при
|
||||
запущенном рабочем стенде с данными: обычный прогон (до
|
||||
`session-auth` он заканчивается падением smoke — это сценарий
|
||||
«Упавшие тесты»); остановка тестового контейнера во время прогона;
|
||||
@@ -162,9 +163,9 @@ commit»).
|
||||
тестового контейнера (`docker ps -a`) соответствуют сценарию; число
|
||||
строк рабочей базы до и после одинаково, рабочий API отвечает; после
|
||||
разбора `KEEP_TEST_DB` база удалена руками; вывод в
|
||||
`evidence/tests/test-isolated-mechanics.txt`. Сценарий «Успешный
|
||||
`evidence/tests/test-isolated-mechanics.md`. Сценарий «Успешный
|
||||
прогон» и evidence набора против контейнера — задача `session-auth`.
|
||||
- [ ] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же
|
||||
- [x] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же
|
||||
шаге обновить `student-tests/spec_coverage.py`: тексты исключений
|
||||
«Прежний пользователь после рестарта» и «Хранилище не готово»,
|
||||
исключения для «Сбой при добавлении участников», «БД остановлена»,
|
||||
@@ -179,25 +180,27 @@ commit»).
|
||||
|
||||
## 8. Документы и инструменты
|
||||
|
||||
- [ ] 8.1 Правила по решениям 11 и 12: `settings.md`, `infra.md`,
|
||||
- [x] 8.1 Правила по решениям 11 и 12: `settings.md`, `infra.md`,
|
||||
`run-modes.md` (плюс `test_isolated`), `docker.md`, `student-tests.md`
|
||||
(обычный прогон и evidence — `make test_isolated`, против любого
|
||||
стенда — `make student_test`). Проверка: `grep -n "POSTGRES_VOLUME\|решает
|
||||
design change" .claude/rules` — только там, где решение ещё не
|
||||
принято (`membership-cache`); `grep -rn run_no_compose .claude`
|
||||
пусто.
|
||||
- [ ] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с
|
||||
- [x] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с
|
||||
известным падением `test_security_scheme_in_openapi` до
|
||||
`session-auth`,
|
||||
карта кода, команды `start_db`, `stop_db`, `upgrade`, `revision`,
|
||||
`wipe_data`, `test_isolated`, без `run_no_compose`. Проверка: каждая команда из
|
||||
таблицы есть в `Makefile` (`make -n <цель>`).
|
||||
- [ ] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед
|
||||
сервером выполняет `make start_db upgrade`; `SKILL.md` без «рестарт =
|
||||
пустое состояние» и `MemoryStore`. Проверка: `python3
|
||||
.claude/skills/run-mtusi-messenger/driver.py all` завершается с кодом
|
||||
0.
|
||||
- [ ] 8.4 `REPORT.md`: запуск из чистого clone (`make run_docker`,
|
||||
- [x] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед
|
||||
сервером выполняет `make upgrade`; `SKILL.md` без «рестарт = пустое
|
||||
состояние» и `MemoryStore`. Проверка: `python3
|
||||
.claude/skills/run-mtusi-messenger/driver.py all` — `start` сам
|
||||
поднимает Postgres, `flow` без провалов, падают только smoke lab2 и
|
||||
`test_security_scheme_in_openapi` (до `session-auth`, design, Goals),
|
||||
затем `stop`.
|
||||
- [x] 8.4 `REPORT.md`: запуск из чистого clone (`make run_docker`,
|
||||
`make run_dev`, остановка, `make wipe_data`), проверки (`make
|
||||
test_isolated`; `make student_test` против любого стенда);
|
||||
архитектура — схема, транзакционные границы,
|
||||
@@ -205,6 +208,6 @@ commit»).
|
||||
часов, соответствие переменных `.env.example` skeleton; строки
|
||||
доказательств уровня «3» по хранению со ссылками на `evidence/`.
|
||||
Проверка: у каждой строки есть команда, наблюдение и путь к файлу.
|
||||
- [ ] 8.5 Финальная проверка: `make lint`, `make check`,
|
||||
- [x] 8.5 Финальная проверка: `make lint`, `make check`,
|
||||
`openspec validate postgres-storage --strict`, `graphify update .`.
|
||||
Проверка: все команды без ошибок.
|
||||
|
||||
Reference in New Issue
Block a user