Files
mtusi2026lab5/openspec/changes/archive/2026-10-02-bench-postgres/proposal.md
T
ricoromaandClaude Opus 5.5 04f859282d chore: port lab 4 solution into the lab 5 skeleton
Source: mtusi2026lab4-safronov, solution/bvt2301-safronov, 2546deb.
Contracts, public tests and evidence of lab 4 are not carried over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 03:09:12 +03:00

7.7 KiB
Raw Blame History

Proposal

Why

Уровень «4» требует обосновать индекс истории запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях и показать, что пагинация не просматривает всю историю на каждую страницу (README.md). Наполнить такую историю и снять план должен нагрузочный стенд bench/, но он перенесён из лабы 1 и на коде лабы 2 не работает:

  • run.py поднимает только контейнер API, без PostgreSQL, Valkey и миграций;
  • сценарии k6 ходят с X-User-Id, которого API больше не принимает;
  • inproc.py собирает приложение над удалённым MemoryStore.

Трек «5» №2 (track2-query-plans, track2-backup-restore) тоже стоит на этом стенде: сравнение индексов и стоимости записи — это метки make bench, а метки лабы 1 сюда не переносились. Поэтому сначала стенду нужны базовый замер на PostgreSQL и план запроса истории.

What Changes

  • Стенд на PostgreSQL. make bench поднимает свой проект compose mtusi-bench из того же docker-compose.yml с override:

    • PostgreSQL и Valkey с теми же пинами и конфигурацией, что у рабочего стенда, со своими лимитами CPU и памяти;
    • миграции до наполнения;
    • API с прежними лимитами (1 CPU, 2 ГБ без swap);
    • без портов на хосте, без .env и config.toml рабочего стенда.

    Каждый размер истории начинается со свежего стенда: новый volume Postgres, новые Valkey и API. Рабочий стенд, его база и кэш не затрагиваются.

  • Идентификация как в контракте. Сценарии k6 регистрируют пользователей с паролем, входят по Basic и шлют Bearer. Срок сессии стенда больше длительности размера.

  • Обслуживание БД перед замером. После наполнения — VACUUM (ANALYZE) и CHECKPOINT: статистика планировщика и состояние таблицы одинаковы у всех меток.

  • План запроса истории. На каждом размере стенд снимает EXPLAIN (ANALYZE, BUFFERS) того запроса страницы истории, который выполняет само приложение (auto_explain в Postgres стенда), для первой, средней и последней страницы. Для сравнения снимается тот же запрос без использованного индекса, в транзакции, которая откатывается. Планы лежат в каталоге метки, сводка — в summary.md.

  • Метрики хранилища. Новые столбцы в конце таблиц: CPU контейнера Postgres на прогон и порцию наполнения. На размер — объём таблицы и индексов messages и байты на сообщение. В паспорт идут образы, версии, лимиты и настройки Postgres и Valkey, а также окружение API без секретов. Пароли стенда генерируются на прогон и никуда не пишутся.

  • BREAKING (инструменты стенда): удаляются bench/inproc.py и цель make bench_inproc. Разложение времени внутри процесса было инструментом трека 1 лабы 1. На PostgreSQL время запроса уходит в основном в БД, и его объясняет план запроса. make bench_ab снимает только стенд.

  • make bench_compare проверяет методику по лимитам всех контейнеров, образам и настройкам Postgres и Valkey. Таблица памяти показывает байты на сообщение в БД.

  • Матрица короче, чем на лабе 1: размеры 10k, 100k и 500k вместо 1M, порция наполнения 25 000 вместо 50 000. Полный прогон — около 30 минут вместо 45. 500k ≥ 100k трека 2 и ≥ 10k уровня 4.

  • Базовый замер baseline полной матрицы на закоммиченном коде. По нему в REPORT.md пишутся раздел экспериментов и строка уровня 4 «индекс истории и EXPLAIN».

Capabilities

New Capabilities

Нет.

Modified Capabilities

  • load-benchmark:
    • изменённые требования:
      • стенд из API, PostgreSQL и Valkey с миграциями, лимитами и свежим volume на каждый размер;
      • матрица: наибольший размер 500 000 вместо 1 000 000;
      • идентификация Bearer в сценариях;
      • обслуживание БД после наполнения;
      • метрики Postgres;
      • паспорт со сведениями о хранилищах;
      • пометка прогона при падении хранилища;
      • проверка методики в сравнении меток;
      • прогоны «до/после» без разложения;
      • базовый замер на PostgreSQL;
    • новое требование: план запроса истории;
    • удалено требование: «Разложение стоимости запроса».

Impact

  • Код стенда:
    • bench/run.py — стенд через compose, обслуживание БД, план, метрики, паспорт;
    • новый bench/bench.compose.yml, новый bench/bench.env;
    • bench/k6/ — lib.js, prepare.js, сценарии, новый explain.js;
    • bench/compare.py, bench/ab.py;
    • удаляется bench/inproc.py.
  • Makefile: цели bench*, удаляется bench_inproc.
  • Код приложения (src/), миграции, контракт и тесты не меняются.
  • Документация:
    • .gitignore (строки evidence/profile);
    • .claude/rules/bench.md — раздел «Что доработать» закрывается, «Что не меняется между метками» пополняется параметрами хранилищ, раздел о диагностике удаляется;
    • AGENTS.md — команды, карта кода, переходное состояние;
    • REPORT.md — эксперименты, уровень 4, ограничения.
  • Доказательства: evidence/bench/baseline/, включая explain-<размер>.txt.
  • Время хоста: полная матрица на PostgreSQL — около 30 минут (оценка по скоростям make bench_quick). Запуск — только с согласия пользователя и после подготовки хоста (bench.md, «Результаты»).