#!/usr/bin/env python3 """EXPLAIN (ANALYZE, BUFFERS) of the history query on >= 10 000 messages (level 4). python scripts/explain_history.py --output evidence/explain-history.txt Creates (once, idempotent) a synthetic chat with 20 000 messages plus 30 000 messages in 30 other chats, then explains the EXACT statements of src/messenger/repo.py: 1. first page (HISTORY_FIRST) 2. late page via cursor (HISTORY_AFTER) — generic plan forced, as a prepared statement reused by the driver would get it 3. the rejected variant `($2 IS NULL OR (created_at, id) > ...)` — generic plan 4. the rejected OFFSET pagination for the same late page Runs psql inside the postgres container; no database port is published. """ from __future__ import annotations import argparse import subprocess import sys from pathlib import Path ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT / "src")) from messenger.repo import HISTORY_AFTER, HISTORY_FIRST # noqa: E402 (the app's real SQL) CHAT = "00000000-0000-4000-8000-00000000e002" USER = "00000000-0000-4000-8000-00000000e001" TARGET = 20_000 LATE = 19_950 # cursor position: the 50 newest messages remain SEED = f""" \\set ON_ERROR_STOP on BEGIN; INSERT INTO users (id, username, display_name, password_hash) VALUES ('{USER}', 'explain_seed', convert_to('Explain seed', 'UTF8'), 'not-a-login') ON CONFLICT DO NOTHING; INSERT INTO chats (id, title, created_by, created_at) SELECT ('00000000-0000-4000-8000-0000000' || lpad(to_hex(n), 5, '0'))::uuid, convert_to('explain ' || n, 'UTF8'), '{USER}', timestamptz '2026-01-01 00:00:00+00' FROM generate_series(57346::int, 57376::int) AS n -- e002 .. e020: target + 30 noise chats ON CONFLICT DO NOTHING; INSERT INTO chat_members (chat_id, user_id, position, chat_created_at) SELECT id, '{USER}', 0, created_at FROM chats WHERE created_by = '{USER}' ON CONFLICT DO NOTHING; INSERT INTO messages (id, chat_id, sender_id, text, created_at) SELECT gen_random_uuid(), '{CHAT}', '{USER}', convert_to('synthetic message ' || g, 'UTF8'), timestamptz '2026-01-01 00:00:00+00' + g * interval '1 second' FROM generate_series(1::int, {TARGET}::int) AS g WHERE NOT EXISTS (SELECT 1 FROM messages WHERE chat_id = '{CHAT}'); INSERT INTO messages (id, chat_id, sender_id, text, created_at) SELECT gen_random_uuid(), c.id, '{USER}', convert_to('noise ' || g, 'UTF8'), timestamptz '2026-01-01 00:00:00+00' + g * interval '1 second' FROM chats c CROSS JOIN generate_series(1::int, 1000::int) AS g WHERE c.created_by = '{USER}' AND c.id <> '{CHAT}' AND NOT EXISTS (SELECT 1 FROM messages m WHERE m.chat_id = c.id); COMMIT; ANALYZE messages; """ def pg(sql_param: str) -> str: """Turn psycopg %s placeholders into $1..$n for a PREPARE statement.""" parts = sql_param.split("%s") return "".join(p + (f"${i + 1}" if i < len(parts) - 1 else "") for i, p in enumerate(parts)) EXPLAIN = f""" \\set ON_ERROR_STOP on \\pset pager off SELECT count(*) AS messages_total, count(*) FILTER (WHERE chat_id = '{CHAT}') AS messages_in_target_chat FROM messages; SELECT created_at AS cur_ts, id AS cur_id FROM messages WHERE chat_id = '{CHAT}' ORDER BY created_at, id OFFSET {LATE - 1} LIMIT 1 \\gset SET plan_cache_mode = force_generic_plan; PREPARE first_page(uuid, int) AS {pg(HISTORY_FIRST)}; PREPARE after_page(uuid, timestamptz, uuid, int) AS {pg(HISTORY_AFTER)}; PREPARE or_page(uuid, timestamptz, uuid, int) AS SELECT id, sender_id, text, created_at FROM messages WHERE chat_id = $1 AND ($2 IS NULL OR (created_at, id) > ($2, $3)) ORDER BY created_at, id LIMIT $4; PREPARE offset_page(uuid, int, int) AS SELECT id, sender_id, text, created_at FROM messages WHERE chat_id = $1 ORDER BY created_at, id OFFSET $2 LIMIT $3; \\echo '=== 1. first page, app query HISTORY_FIRST, generic plan' EXPLAIN (ANALYZE, BUFFERS, SUMMARY ON) EXECUTE first_page('{CHAT}', 51); \\echo '=== 2. late page (cursor at {LATE}), app query HISTORY_AFTER, generic plan' EXPLAIN (ANALYZE, BUFFERS, SUMMARY ON) EXECUTE after_page('{CHAT}', :'cur_ts', :'cur_id', 51); \\echo '=== 3. REJECTED: one query with ($2 IS NULL OR ...), same late page, generic plan' EXPLAIN (ANALYZE, BUFFERS, SUMMARY ON) EXECUTE or_page('{CHAT}', :'cur_ts', :'cur_id', 51); \\echo '=== 4. REJECTED: OFFSET pagination, same late page' EXPLAIN (ANALYZE, BUFFERS, SUMMARY ON) EXECUTE offset_page('{CHAT}', {LATE}, 51); """ def psql(script: str) -> str: result = subprocess.run( ["docker", "compose", "exec", "-T", "postgres", "psql", "-U", "messenger", "-d", "messenger", "-X", "-q", "-f", "-"], cwd=ROOT, input=script, capture_output=True, text=True, encoding="utf-8", check=True) return result.stdout def run() -> str: psql(SEED) return psql(EXPLAIN) def main() -> int: parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser.add_argument("--output", default=None) args = parser.parse_args() text = run() print(text) if args.output: Path(args.output).write_text(text, encoding="utf-8", newline="\n") return 0 if __name__ == "__main__": sys.exit(main())