Files
mtusi2026lab2/openspec/changes/track2-query-plans/design.md
T
2026-10-02 04:24:59 +03:00

24 KiB
Raw Blame History

Design

Context

Зачем — proposal.md, требования — дельта load-benchmark. Что есть сейчас (archived change bench-postgres):

  • bench/run.py на каждый размер поднимает свежий проект compose mtusi-bench. Затем:
    • prepare.js: 11 пользователей, читаемый чат и чат записи;
    • prefill.js: N сообщений в читаемый чат порциями по prefill_chunk, 32 клиента;
    • VACUUM (ANALYZE) и CHECKPOINT;
    • cursors.js: пул курсоров читаемого чата;
    • этап плана: explain.js читает три страницы, auto_explain пишет их планы в журнал Postgres. Средняя страница повторяется в psql с индексом и без него, DROP INDEX — в откатываемой транзакции;
    • матрица read / write, затем уборка стенда.
  • Методика — поля Profile, целиком пишутся в meta.json. make bench_compare отказывает, если profile.* различается.
  • Запрос страницы (src/core/repos/message.py) — сравнение кортежей (created_at, id) > ($2, $3) по индексу ix_messages_chat_id_created_at_id. Длина текста по контракту — до 4000 символов (MESSAGE_TEXT_MAX_LENGTH).
  • Проба на закреплённом образе Postgres 18.6 (postgres:18.6-trixie):
    • 210 000 строк: один чат на 200 000 и 1 000 чатов по 10;
    • CHECKPOINT внутри транзакции выполняется;
    • EXPLAIN (ANALYZE, WAL) для INSERT … SELECT даёт записи WAL, байты и полные образы страниц (FPI);
    • условие курсора через OR — Index Scan с Filter: 96 198 строк отброшено, 2 634 буфера на середине большого чата;
    • покрывающий индекс с INCLUDE (sender_id, text) — 32 МБ против 12 МБ у текущего. Текст из 4000 несжимаемых символов CJK (≈12 КБ) при нём не вставляется: index row requires 12072 bytes, maximum size is 8191. При текущем индексе — вставляется.

Goals / Non-Goals

Goals:

  • Один прогон make bench даёт всё, что нужно треку 2 по плану запроса: набор ≥100 000 сообщений в чатах разного размера, планы приложения по уровням чатов, варианты индекса и запроса на тех же данных и стоимость записи по вариантам.
  • Варианты сравниваются на одних и тех же данных в одном состоянии стенда, поэтому шум между запусками стенда на сравнение не влияет.

Non-Goals:

  • Менять индекс приложения в этом change. Если по правилу выбора (решение 7) вариант окажется лучше, его внедрение — отдельный change с миграцией и make bench_ab. По пробе такого не ожидается.
  • make bench_ab и A/A-метка: код приложения не меняется, сравнивать нечего. Варианты сравниваются внутри одной метки.
  • Backup и восстановление — change track2-backup-restore.
  • Настройка Postgres (shared_buffers, random_page_cost и т.п.).
  • Неравномерная нагрузка чтения по чатам в матрице. Сценарий read по-прежнему читает читаемый чат. Как стоят страницы маленьких чатов, показывают планы.

Decisions

1. Фоновые чаты — уровни в профиле

Новое поле Profile.background — кортеж пар «число чатов, сообщений в чате»:

Профиль Уровни Сообщений
full 10 × 5 000, 100 × 400, 1 000 × 10 100 000
quick 2 × 1 000, 10 × 100, 50 × 10 3 500

Вместе с читаемым чатом на 10k / 100k / 500k в таблице 110 000 / 200 000 / 600 000 сообщений. Размеры чатов различаются от 10 до 500 000, в 50 000 раз.

Почему уровни, а не распределение Ципфа:

  • у каждого уровня есть понятный представитель для плана;
  • проверка распределения — точное сравнение чисел;
  • результат читается как «маленький, средний, большой и огромный чат».

Ципф дал бы тот же разброс, но без очевидных точек для планов.

Фоновые чаты создаёт prepare.js. В каждом все 11 пользователей, как в читаемом чате. Фикстура получает список bgChats: id и размер в порядке уровней. Создание 1 110 чатов через HTTP занимает секунды и в замер не входит.

2. Наполнение по расписанию

Оркестратор строит расписание: какой чат получает n-е сообщение наполнения. Длина расписания — N + сумма уровней.

  • Чат с s сообщениями получает позиции (k + 0,5) / s, k = 0…s−1.
  • Все позиции сортируются (при равенстве — по номеру чата).

Это stride scheduling: сообщения каждого чата равномерно размазаны по всему наполнению, а порядок детерминирован.

.work/schedule.json — массив номеров чатов: 0 — читаемый, дальше фоновые в порядке фикстуры. prefill.js читает его через SharedArray и шлёт сообщение n в чат schedule[n]. Порции, OFFSET, отправители по кругу и столбцы prefill.csv остаются прежними. Только messages_before / messages_after теперь считают всю таблицу, а порций больше: (N + 100 000) / 25 000.

Альтернативы:

  • Сначала фоновые чаты, потом читаемый: сообщения маленьких чатов лежали бы в начале таблицы, а читаемый чат — в конце, отдельно. Это нереалистично, и на соседство страниц в куче влиял бы порядок шагов.
  • Случайный выбор чата на каждое сообщение: точное число сообщений в чате не гарантировано, нужен был бы добор.

После обслуживания БД оркестратор проверяет распределение:

  • SELECT chat_id, count(*) FROM messages GROUP BY chat_id;
  • в читаемом чате ровно N, у каждого фонового — его размер;
  • всего строк N + фон.

Иначе — BenchError с размером, стенд убирается.

3. Страницы плана по уровням

  • Читаемый чат. Как раньше: первая, средняя и последняя страница из пула курсоров.

  • Фоновые уровни. Для первого чата каждого уровня новый plan_cursors.js проходит историю страницами по walk_limit и сохраняет позиции. Выбор — как у пула, только позиции с ≥page_limit сообщениями после них:

    • средняя — позиция из середины этого списка;
    • последняя — его конец.

    У чата без таких позиций (10 сообщений; 100 в quick) — только первая страница.

Проход идёт до включения auto_explain, так что в журнал не попадает. Попутно он прогревает страницы чата, как cursors.js прогревает читаемый.

Оркестратор пишет .work/plan_pages.json: чат, уровень, страница, позиция, курсор и ожидаемое число строк. explain.js читает файл и запрашивает страницы по порядку. У каждой проверяется 200 и ожидаемое число строк: полная страница или весь маленький чат. Записей auto_explain по messages должно быть ровно столько, сколько страниц. Сопоставление — по порядку, как раньше.

4. Варианты — в psql, в откатываемой транзакции

Для страницы сравнения каждого чата одна сессия psql, SQL — через stdin:

SET lock_timeout = '5s';
SET plan_cache_mode = force_custom_plan;
BEGIN;
PREPARE page AS <Query Text приложения>;
-- app: тот же запрос, тот же индекс
EXPLAIN (ANALYZE, BUFFERS) EXECUTE page(...);   -- прогрев
EXPLAIN (ANALYZE, BUFFERS) EXECUTE page(...);
SET LOCAL plan_cache_mode = force_generic_plan;
-- generic
EXPLAIN … EXECUTE page(...); EXPLAIN … EXECUTE page(...);
SET LOCAL plan_cache_mode = force_custom_plan;
PREPARE page_or AS <тот же текст, условие курсора через OR>;
-- or-cursor (только если у страницы есть курсор)
EXPLAIN … EXECUTE page_or(...); EXPLAIN … EXECUTE page_or(...);
DROP INDEX <индекс плана приложения>;
-- no-index
EXPLAIN … EXECUTE page(...); EXPLAIN … EXECUTE page(...);
CREATE INDEX bench_variant_<имя> ON messages <столбцы варианта>;
-- <имя варианта>
EXPLAIN … EXECUTE page(...); EXPLAIN … EXECUTE page(...);
DROP INDEX bench_variant_<имя>;
-- … следующий вариант
ROLLBACK;
  • Каждый вариант выполняется дважды, в результат идёт второй. Только что построенный индекс ещё не в shared_buffers (большая сборка пишет мимо них), и первое выполнение читало бы его с диска. Индекс приложения при этом прогрет. Без повтора сравнение было бы нечестным.

  • Варианты индекса — поле Profile.index_variants: пары «имя, столбцы». Тексты DDL пишутся в паспорт:

    • chat_only — (chat_id);
    • covering — (chat_id, created_at, id) INCLUDE (sender_id, text).

    DROP INDEX индекса приложения идёт до вариантов: иначе планировщик выбрал бы его, а не вариант.

  • Форма с OR получается из текста приложения регулярной заменой (messages.created_at, messages.id) > ($2…, $3…) на (messages.created_at > $2… OR (messages.created_at = $2… AND messages.id > $3…)). Список столбцов, ORDER BY и LIMIT остаются как в запросе приложения. Если шаблон не найден (приложение изменило запрос) — BenchError, а не тихая копия запроса.

  • Generic plan — force_generic_plan для того же prepared statement. Это проверка из ограничений baseline: какой план получит приложение после пяти выполнений.

  • После ROLLBACK оркестратор сравнивает список индексов messages (pg_indexes) с тем, что был до этапа. При различии — BenchError.

Почему в psql, а не миграциями и make bench_ab:

  • варианты сравниваются на одних данных и в одном состоянии кэша;
  • нужна одна метка (~35 мин), а не по метке на вариант (по ~35 мин и A/A для шума);
  • HTTP-уровень у этого стенда упирается в CPU API (H3 baseline): 0,05 мс БД из ~1,3 мс CPU на чтение, и разница индексов в RPS утонула бы в шуме.

Минус: psql делает custom plan с литералами, а приложение — prepared statement asyncpg. Это закрыто сравнением app (psql) с планом auto_explain той же страницы и вариантом generic.

5. Стоимость записи — откатываемые вставки в конце размера

После матрицы размера и до уборки стенда для каждой конфигурации — app (индекс приложения, построенный заново), каждого варианта из профиля и none — write_probe_repeats раз (3):

BEGIN;
CREATE TEMP TABLE probe_src ON COMMIT DROP AS
  SELECT chat_id, sender_id, row_number() OVER (ORDER BY created_at, id) AS g
  FROM (SELECT chat_id, sender_id, created_at, id FROM messages
        ORDER BY created_at, id LIMIT <write_probe_rows>) s;
DROP INDEX <индекс приложения>;
CREATE INDEX bench_probe ON messages <столбцы конфигурации>;  -- кроме none
SELECT pg_relation_size('bench_probe'), count(*) FROM messages;
CHECKPOINT;
EXPLAIN (ANALYZE, BUFFERS, WAL) INSERT INTO messages
  SELECT gen_random_uuid(), chat_id, sender_id, rpad('probe-' || g, <text_length>, 'x'),
         now() + g * interval '1 microsecond' FROM probe_src;
DO $$ BEGIN INSERT … <4000 несжимаемых символов>; RAISE NOTICE 'long-text: ok';
EXCEPTION WHEN others THEN RAISE NOTICE 'long-text: %', SQLERRM; END $$;
ROLLBACK;
VACUUM messages;
  • Источник чатов — первые write_probe_rows сообщений в порядке наполнения: 20 000 в full, 5 000 в quick, где на размере 1k в таблице всего 4 500 строк. Чаты в той же пропорции и в том же перемешанном порядке, что у наполнения. Отправитель — тот же, он участник чата. created_at — после всех сообщений, вставка в конец диапазона каждого чата, как у новых сообщений. Временная таблица WAL не пишет.

  • Индекс приложения строится заново (DROP + CREATE по pg_get_indexdef), как и варианты. Иначе текущий индекс с разделёнными после наполнения и прошлых проб страницами сравнивался бы со свежими компактными.

  • CHECKPOINT перед вставкой: полные образы страниц пишутся при первом изменении страницы после контрольной точки. Без неё их число зависело бы от того, когда сработал фоновый checkpoint.

  • VACUUM messages после каждой пробы убирает строки откаченной вставки. Порядок конфигураций сдвигается на каждом повторе: индекс первичного ключа (случайный UUID) общий для всех и мог бы давать преимущество тем, кто идёт позже.

  • Сообщение максимальной длины — 4000 символов CJK из md5 номера символа. Текст детерминирован и не сжимается, около 12 КБ UTF-8. Ошибка ловится в DO, NOTICE берётся из stderr psql.

  • После всех проб число строк и список индексов messages должны совпасть с тем, что было до них.

  • Метрики конфигурации — медиана и min–max повторов:

    • время вставки на сообщение (Execution Time / строк);
    • WAL байт на сообщение, FPI на 1 000 сообщений;
    • размер индекса и байты индекса на сообщение;
    • результат длинного сообщения.

    Пишутся в meta.sizes[].write_cost и в раздел сводки.

Почему вставка в БД, а не HTTP-прогон write на каждый вариант:

  • HTTP-запись ограничена CPU API и fsync коммита каждого сообщения: ~1 мс на запрос;
  • стоимость индекса — десятки микросекунд на строку. Её видно только без этих слагаемых.

HTTP-запись с индексом приложения по-прежнему меряет сценарий write. Обе цифры в отчёте рядом.

6. Граница чёрного ящика

Исключения для PostgreSQL стенда (bench.md, «Как писать») пополняются:

  • подсчёт сообщений по чатам;
  • варианты индекса и формы запроса в откатываемой транзакции;
  • пробные вставки в откатываемой транзакции с VACUUM после.

Приложение в эти моменты не нагружено. Данные и схема для него после этапа те же: это проверяется (решения 4 и 5). Приложение по-прежнему видит только HTTP от k6.

7. Гипотезы и правило выбора

Гипотезы записываются в REPORT.md до полной матрицы, по make bench_quick и пробе (Context):

  • P1. Индекс приложения со сравнением кортежей: страница любого чата на любой глубине стоит ограниченно — до ~60 буферов и долей миллисекунды. От размера чата и таблицы это не зависит.
  • P2. chat_only: маленький чат стоит как с индексом приложения, плюс сортировка ≤400 строк. Огромный чат читает весь чат и сортирует. Время растёт с размером чата: ×≥20 от 10k к 500k.
  • P3. Курсор через OR при индексе приложения: буферы растут с числом сообщений до курсора. На середине 500k их в ≥100 раз больше, чем у сравнения кортежей.
  • P4. covering:
    • Index Only Scan без чтения кучи, буферов средней страницы в ≥5 раз меньше;
    • индекс в ≥2 раза больше, WAL на сообщение в ≥1,5 раза больше;
    • сообщение из 4000 символов не вставляется.
  • P5. Generic plan индекса приложения — тот же Index Scan на всех уровнях.
  • P6. Стоимость записи (WAL и время на сообщение) растёт в порядке none < chat_only < app < covering.

Правило выбора записывается вместе с гипотезами. Вариант заменяет индекс приложения, только если выполнены все три условия:

  1. сообщение максимальной длины вставляется;
  2. буферы страницы сравнения на каждом уровне — не больше половины, чем у app;
  3. время вставки и WAL на сообщение — не больше ×1,5 от app.

Форма запроса меняется, только если вариант с OR читает меньше буферов на всех уровнях. Иначе приложение не меняется, и отчёт так и пишет.

Risks / Trade-offs

  • [Время EXPLAIN одного выполнения на долях миллисекунды шумит] → основная метрика — буферы, они детерминированы. Время — второе. Варианты — второе выполнение из двух, на прогретых страницах.
  • [Generic plan под force_generic_plan — не обязательно тот, что выберет auto] → это верхняя граница риска: в auto Postgres берёт generic, только если тот не дороже custom. Так и записывается в отчёт.
  • [Вставка INSERT … SELECT одной транзакцией дешевле, чем 20 000 коммитов] → сравниваются варианты между собой при одинаковой процедуре. Абсолютная стоимость HTTP-записи — сценарий write. Ограничение — в отчёте.
  • [Индекс первичного ключа на случайном UUID разделяет страницы при каждой пробе, и порядок даёт смещение] → VACUUM между пробами, сдвиг порядка на каждом повторе, медиана и разброс.
  • [Сборка покрывающего индекса на 600k строк — секунды, повторяется на каждой странице сравнения и пробе] → +2–3 минуты на матрицу. Это записано в оценке времени.
  • [Расписание на 600 000 номеров в .work/] → ~3,5 МБ JSON, удаляется вместе с .work/. В k6 — SharedArray, одна копия на все VU.
  • [Чат записи пуст при проверке распределения] → он ожидается с 0 сообщений и проверяется так же.
  • [Методика меняется, baseline и track2 несравнимы] → make bench_compare отказывает по profile.background. Отчёт сравнивает их только описательно, с этой оговоркой.

Migration Plan

Развёртывания нет: меняются только bench/, документация и отчёт. Порядок — tasks.md:

  1. код стенда и make bench_quick;
  2. коммит кода;
  3. гипотезы и правило выбора в REPORT.md, коммит;
  4. подготовка хоста и make bench BENCH_LABEL=track2;
  5. коммит доказательств;
  6. отчёт.

Откат — git revert коммитов change. Рабочий стенд не затрагивается.