From b3dae2855f92de07add13c67635665a924b65098 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D0=B0=D0=BC=D0=BE=D1=85=D0=B2=D0=B0=D0=BB=D0=BE?= =?UTF-8?q?=D0=B2=20=D0=90=D0=BD=D0=B4=D1=80=D0=B5=D0=B9=20=D0=A0=D0=B5?= =?UTF-8?q?=D0=BC=D0=BE=D0=B2=D0=B8=D1=87?= Date: Fri, 2 Oct 2026 12:58:21 +0300 Subject: [PATCH] feat: prove query tradeoffs and fresh-volume restore --- Dockerfile | 1 + REPORT.md | 31 ++++++-- compose.restore.yaml | 43 ++++++++++++ evidence/query-comparison.csv | 31 ++++++++ evidence/query-plans.txt | 11 +++ evidence/restore-check.txt | 19 +++++ scripts/backup_restore.sh | 60 ++++++++++++++++ scripts/track2_experiment.py | 128 ++++++++++++++++++++++++++++++++++ student-tests/test_restore.py | 116 ++++++++++++++++++++++++++++++ 9 files changed, 436 insertions(+), 4 deletions(-) create mode 100644 compose.restore.yaml create mode 100644 evidence/query-comparison.csv create mode 100644 evidence/query-plans.txt create mode 100644 evidence/restore-check.txt create mode 100755 scripts/backup_restore.sh create mode 100644 scripts/track2_experiment.py create mode 100644 student-tests/test_restore.py diff --git a/Dockerfile b/Dockerfile index cda9cd4d..b0645eb1 100644 --- a/Dockerfile +++ b/Dockerfile @@ -7,6 +7,7 @@ RUN pip install --no-cache-dir -r requirements.txt && useradd --system --uid 100 COPY --chown=app:app src/ src/ COPY --chown=app:app migrations/ migrations/ COPY --chown=app:app scripts/migrate.py scripts/migrate.py +COPY --chown=app:app student-tests/test_restore.py student-tests/test_restore.py USER app EXPOSE 8080 CMD ["sh", "-c", "python scripts/migrate.py && exec python -m src.server"] diff --git a/REPORT.md b/REPORT.md index 94b306ed..2353f822 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,7 +1,7 @@ # Отчёт — лабораторная 2 - Автор, группа: Самохвалов Андрей Ремович, БПИ-2302. -- Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Уровень 4 проверен; исследование трека 2 выполняется следующим блоком. +- Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Уровни 3 и 4 и выбранный трек 5 проверены на локальном стенде. - Ветка: `solution/bpi2302-samohvalov`; commit/PR указываются после публикации. - Источники: `README.md`, `COURSE.md`, `contracts/README.md`, `contracts/openapi.json`, публичные тесты и примеры этого репозитория; FastAPI, psycopg, PostgreSQL и Argon2id. Код и инструкции подготовлены с помощью ИИ Codex и проверяются запуском команд ниже. @@ -30,6 +30,9 @@ docker compose --env-file .env up -d --build --wait make check make test make test-persistence ACTION_SCRIPT=scripts/restart.sh +make test-level4 +docker compose --env-file .env exec -T api python - < scripts/track2_experiment.py > evidence/query-comparison.csv 2> evidence/query-plans.txt +bash scripts/backup_restore.sh > evidence/restore-check.txt ``` На каждом старте API выполняет `scripts/migrate.py` под advisory lock: миграции `001` и `002` применяются только один раз и завершаются до приёма запросов. `docker compose --env-file .env exec -T api python scripts/migrate.py` безопасно повторить вручную. `GET /health/ready` требует доступную БД. `docker compose --env-file .env down` останавливает стенд с сохранением именованного volume. Только для намеренного уничтожения учебных данных: `docker compose --env-file .env down -v`. @@ -57,7 +60,8 @@ make test-persistence ACTION_SCRIPT=scripts/restart.sh | Кэш и отказы уровня 4 | `docker compose exec -T api python - < student-tests/test_cache_failures.py`; отказ Valkey/БД | Два интеграционных теста PASS; SQL 2/1/2 на miss/hit/reload; Valkey hit/miss 1/2; smoke проходит без кэша; при отказе БД 503, отозванный токен после рестарта кэша 401 | `evidence/cache-2026-10-02.txt` | | Негативные, конкурентные проверки уровня 4 | `make test-level4` | 10 тестов PASS: короткий TTL 2 с и неизменный expiry после рестарта API, logout/повторный logout, одинаковая ошибка неверных credentials, гонка username 201/409, откат чата после ошибки второй membership, обход отказавшего Valkey, ограниченный 503 при отказе БД и 401 после перезапуска Valkey. Оба списка отвечают 400 на limit из 4301 цифры | `evidence/level4-tests.txt` | | Индекс истории уровня 4 | `docker compose --env-file .env exec -T api python - --count 10000 --deep-offset 8000 < scripts/seed_history.py` | 10 000 сообщений в одном чате; первая и глубокая страницы по 51 строке, порядок и отсутствие повторов проверены. Обе страницы используют `messages_history_idx` | `evidence/history-explain.txt` | -| Трек 5 | Выполняется после уровня 4 | Пока не заявлен как проверенный | — | +| Трек 5: ≥100 000 сообщений и два индекса | `scripts/track2_experiment.py` в API-контейнере | Чаты 80 000/15 000/5 000; по пять измерений первой и глубокой страниц и вставки 500 строк; индекс приложения восстановлен после опыта | `evidence/query-comparison.csv`, `evidence/query-plans.txt` | +| Трек 5: backup/restore | `bash scripts/backup_restore.sh` | Дамп 3 441 039 байт восстановлен в новый volume; все пять таблиц совпали по count и SHA-256 строк; при остановленной исходной БД восстановленный API вернул 200 с действующим токеном и 401 с истёкшим | `evidence/restore-check.txt` | У `api`, `postgres` и `valkey` изменились времена `StartedAt` при сохранении именованного volume; точные значения приведены в evidence. Это подтверждает фактический перезапуск трёх контейнеров. Проверка `make validate` локально пока не завершена: DNS до `files.pythonhosted.org` не позволил установить `openapi-spec-validator==0.7.2`; отдельный CI workflow устанавливает зависимости из `requirements-dev.txt` для проверки контракта. @@ -67,7 +71,26 @@ make test-persistence ACTION_SCRIPT=scripts/restart.sh Для SQL-плана `scripts/seed_history.py` создаёт отдельный синтетический чат с 10 000 сообщениями, выполняет `ANALYZE messages` и проверяет 51 упорядоченную строку на первой и странице после курсора 8000-й записи. Команда и полный `EXPLAIN (ANALYZE, BUFFERS)` сохранены в `evidence/history-explain.txt`. PostgreSQL 17.6 выбрал `Index Scan using messages_history_idx` с условием `chat_id` для первой страницы и `(chat_id, (created_at,id) > cursor)` для глубокой. Обе прочли лишь 3 и 4 буфера из cache, выполнились за 0,010 и 0,014 мс в этом прогоне; это время SQL на прогретых страницах, не HTTP latency и не прогноз для других размеров истории. В запросах приложения также используется keyset `(created_at,id)` с индексом `(chat_id,created_at,id)`, поэтому глубокая страница не пропускает заново первые 8000 строк. -Сравнение на ≥100 000 сообщениях и восстановление в новое хранилище выполняются в блоке трека 5. +### Трек 5: план запроса и стоимость записи + +**Гипотеза.** Покрывающий индекс `(chat_id,created_at,id) INCLUDE (sender_id,text)` уберёт обращения к heap на прогретых страницах истории, но займёт больше места и не обязан дать выигрыш по времени при короткой странице. Сохраняемый индекс приложения — `(chat_id,created_at,id)`; эксперимент временно заменяет его на покрывающий и в `finally` восстанавливает исходный. + +**Метод.** На исходном commit `e50ba0f` и Colima-стенде (arm64, 2 CPU, 2 054 840 320 байт RAM; PostgreSQL 17.6) скрипт создаёт три синтетических чата 80 000/15 000/5 000 сообщений с равномерным временем внутри каждого чата. `VACUUM (ANALYZE)` выполнен перед каждым вариантом. Для каждого индекса одна и та же проекция из пяти полей читается первой страницей и по keyset-курсору после 72 000-й записи горячего чата; размер ответа — 51 строка. Три прогрева и пять повторов `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` дают время SQL, план и cache buffers. Отдельно пять раз вставляются и подтверждаются по 500 синтетических строк в четвёртый чат под каждым индексом; измерено время клиента на `INSERT ... SELECT` вместе с COMMIT. Итоговая БД содержит ещё 5 000 строк этого теста, поэтому фактический размер при backup — 115 026 сообщений с учётом данных прежних проверок. Значения CSV содержат каждый повтор; запросы и DDL — в `scripts/track2_experiment.py`. + +| Вариант | Первая страница: медиана SQL, shared hit | Глубокая: медиана SQL, shared hit | INSERT 500 + COMMIT: медиана / диапазон | Размер индекса после опыта | +| --- | --- | --- | --- | --- | +| A: обычный btree | 0,009 мс, 6 | 0,011 мс, 6 | 2,632 мс / 2,467–3,997 | 6 799 360 байт | +| B: covering btree | 0,011 мс, 5 | 0,010 мс, 4 | 2,638 мс / 2,382–12,557 | 11 935 744 байт | + +Вариант B дал `Index Only Scan` и ноль `Heap Fetches` в сохранённых планах; A дал `Index Scan`. Во всех повторениях `shared_read=0`: измерялся тёплый cache. Разница медиан SQL в пределах тысячных долей миллисекунды и не доказывает ускорение B. Медленная вставка B в одном повторе показывает нестабильность, но пяти повторов недостаточно, чтобы приписать её именно индексу. Размер B больше примерно на 76%; поэтому оставлен исходный A. Сравнение последовательное A→B, записи второго варианта идут после записей первого, и опыт не включает параллельную нагрузку, холодный cache, HTTP и долговременную запись WAL. Команда из чистого clone требует поднятого Compose и локальных `.env`/secrets по разделу запуска; эксперимент добавляет синтетические строки только в учебную БД. + +### Трек 5: восстановление + +`scripts/backup_restore.sh` создаёт private `pg_dump -Fc` в системном временном каталоге, поднимает второй `postgres:17.6-bookworm` с **новым именованным volume**, применяет `pg_restore --exit-on-error`, запускает отдельный API с URL второй БД, затем останавливает исходный PostgreSQL на время проверки. Он не копирует исходный volume. Источник после проверки снова запущен; временные контейнеры и файлы с URL/токенами удалены, успешный новый volume оставлен для проверки. Сценарий не объявляет успех, если dump, restore, сверка или HTTP-сценарий завершились ошибкой. + +При замере 2026-10-02 09:51 UTC новый volume `mtusi2026lab2_restore_20261002125101_21469` содержал 110 users, 26 chats, 41 memberships, 115 026 messages и 49 sessions. Для каждой таблицы совпали количество и SHA-256 потока всех строк в порядке ключа; у трёх выбранных сообщений совпали ID и SHA-256 текста. Через восстановленный API при недоступном источнике действующий токен прочитал первую страницу (200), а токен, истёкший ещё до backup, получил 401. Полный путь «старт нового PostgreSQL → restore → API ready» занял 10 с по секундным отметкам; отдельные dump/restore уложились в разрешение 1 с этой грубой шкалы. `evidence/restore-check.txt` содержит результат без токенов и raw dump. + +Граница восстановления — согласованный снимок `pg_dump`: подтверждённые записи после момента снимка этим резервным файлом не возвращаются. Архивации WAL и непрерывного PITR здесь нет, поэтому RPO зависит от частоты backup, а измеренные 10 с не включают поиск и передачу файла с другой машины. Тест выполнялся без внешних писателей между подготовкой fingerprint и dump. Для реальной эксплуатации потребуются расписание backup и регулярная проверка restore. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | @@ -79,4 +102,4 @@ make test-persistence ACTION_SCRIPT=scripts/restart.sh ## Ограничения и следующие шаги -Подтверждён рестарт одного API, одного PostgreSQL и Valkey с сохранением volume БД. Это не высокая доступность: отказ БД временно делает API недоступным, а заполненный кэш не может заменить проверку сессии. Локальный HTTP не предназначен для удалённой передачи паролей без TLS. Сравнение ≥100 000 сообщений и восстановление в новое хранилище ещё должны быть добавлены; их результаты нельзя выводить из smoke, persistence или 10 000 строк одного чата. +Подтверждён рестарт одного API, одного PostgreSQL и Valkey с сохранением volume БД и отдельное восстановление во второй PostgreSQL. Это не высокая доступность: отказ рабочей БД временно делает API недоступным, а заполненный кэш не может заменить проверку сессии. Локальный HTTP не предназначен для удалённой передачи паролей без TLS. Результаты трека 5 описывают один локальный стенд и тёплый cache; для выбора индекса под иным распределением данных опыт надо повторить. diff --git a/compose.restore.yaml b/compose.restore.yaml new file mode 100644 index 00000000..310f9b97 --- /dev/null +++ b/compose.restore.yaml @@ -0,0 +1,43 @@ +services: + postgres_restore: + image: postgres:17.6-bookworm + environment: + POSTGRES_DB: messenger + POSTGRES_USER: messenger + POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password + secrets: + - postgres_password + volumes: + - restore_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U messenger -d messenger"] + interval: 2s + timeout: 2s + retries: 20 + + api_restore: + build: . + environment: + APP_HOST: 0.0.0.0 + APP_PORT: 8080 + DATABASE_URL_FILE: /run/secrets/database_url_restore + VALKEY_URL: redis://valkey:6379/0 + secrets: + - database_url_restore + depends_on: + postgres_restore: + condition: service_healthy + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).close()"] + interval: 2s + timeout: 3s + retries: 20 + start_period: 5s + +secrets: + database_url_restore: + file: ${RESTORE_DATABASE_URL_FILE:?Set by scripts/backup_restore.sh} + +volumes: + restore_data: + name: ${RESTORE_VOLUME_NAME:?Set by scripts/backup_restore.sh} diff --git a/evidence/query-comparison.csv b/evidence/query-comparison.csv new file mode 100644 index 00000000..4fb69168 --- /dev/null +++ b/evidence/query-comparison.csv @@ -0,0 +1,31 @@ +variant,index,operation,trial,dataset_rows,execution_ms,shared_hit,shared_read,shared_dirtied,plan,rows_inserted +A,messages_history_idx,first,1,100000,0.008,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,first,2,100000,0.015,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,first,3,100000,0.011,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,first,4,100000,0.009,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,first,5,100000,0.009,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,deep,1,100000,0.009,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,deep,2,100000,0.017,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,deep,3,100000,0.011,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,deep,4,100000,0.022,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,deep,5,100000,0.009,6,0,0,Limit > messages_history_idx,0 +A,messages_history_idx,write500,1,100000,3.997,,,,INSERT 500 + COMMIT,500 +A,messages_history_idx,write500,2,100000,3.276,,,,INSERT 500 + COMMIT,500 +A,messages_history_idx,write500,3,100000,2.616,,,,INSERT 500 + COMMIT,500 +A,messages_history_idx,write500,4,100000,2.632,,,,INSERT 500 + COMMIT,500 +A,messages_history_idx,write500,5,100000,2.467,,,,INSERT 500 + COMMIT,500 +B,messages_history_covering_idx,first,1,100000,0.009,5,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,first,2,100000,0.011,5,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,first,3,100000,0.013,5,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,first,4,100000,0.01,5,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,first,5,100000,0.016,5,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,deep,1,100000,0.009,4,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,deep,2,100000,0.009,4,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,deep,3,100000,0.011,4,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,deep,4,100000,0.012,4,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,deep,5,100000,0.01,4,0,0,Limit > messages_history_covering_idx,0 +B,messages_history_covering_idx,write500,1,100000,2.638,,,,INSERT 500 + COMMIT,500 +B,messages_history_covering_idx,write500,2,100000,12.557,,,,INSERT 500 + COMMIT,500 +B,messages_history_covering_idx,write500,3,100000,2.7,,,,INSERT 500 + COMMIT,500 +B,messages_history_covering_idx,write500,4,100000,2.382,,,,INSERT 500 + COMMIT,500 +B,messages_history_covering_idx,write500,5,100000,2.439,,,,INSERT 500 + COMMIT,500 diff --git a/evidence/query-plans.txt b/evidence/query-plans.txt new file mode 100644 index 00000000..6560f2f1 --- /dev/null +++ b/evidence/query-plans.txt @@ -0,0 +1,11 @@ +UTC: 2026-10-02T09:42:09.839961+00:00 +PostgreSQL: 17.6 (Debian 17.6-2.pgdg12+1) +Synthetic chat sizes: hot=80000, medium=15000, cold=5000; fixed 51-row pages; deep cursor=72000 +Variant A: messages_history_idx +{"variant": "A", "operation": "first", "plan": {"Node Type": "Limit", "Parallel Aware": false, "Async Capable": false, "Startup Cost": 0.42, "Total Cost": 7.65, "Plan Rows": 51, "Plan Width": 75, "Actual Startup Time": 0.001, "Actual Total Time": 0.006, "Actual Rows": 51, "Actual Loops": 1, "Shared Hit Blocks": 6, "Shared Read Blocks": 0, "Shared Dirtied Blocks": 0, "Shared Written Blocks": 0, "Local Hit Blocks": 0, "Local Read Blocks": 0, "Local Dirtied Blocks": 0, "Local Written Blocks": 0, "Temp Read Blocks": 0, "Temp Written Blocks": 0, "Plans": [{"Node Type": "Index Scan", "Parent Relationship": "Outer", "Parallel Aware": false, "Async Capable": false, "Scan Direction": "Forward", "Index Name": "messages_history_idx", "Relation Name": "messages", "Alias": "messages", "Startup Cost": 0.42, "Total Cost": 11340.4, "Plan Rows": 80004, "Plan Width": 75, "Actual Startup Time": 0.001, "Actual Total Time": 0.004, "Actual Rows": 51, "Actual Loops": 1, "Index Cond": "(chat_id = 'a9024646-24db-4984-b912-1030eea3ed60'::uuid)", "Rows Removed by Index Recheck": 0, "Shared Hit Blocks": 6, "Shared Read Blocks": 0, "Shared Dirtied Blocks": 0, "Shared Written Blocks": 0, "Local Hit Blocks": 0, "Local Read Blocks": 0, "Local Dirtied Blocks": 0, "Local Written Blocks": 0, "Temp Read Blocks": 0, "Temp Written Blocks": 0}]}} +{"variant": "A", "operation": "deep", "plan": {"Node Type": "Limit", "Parallel Aware": false, "Async Capable": false, "Startup Cost": 0.42, "Total Cost": 53.72, "Plan Rows": 51, "Plan Width": 75, "Actual Startup Time": 0.002, "Actual Total Time": 0.006, "Actual Rows": 51, "Actual Loops": 1, "Shared Hit Blocks": 6, "Shared Read Blocks": 0, "Shared Dirtied Blocks": 0, "Shared Written Blocks": 0, "Local Hit Blocks": 0, "Local Read Blocks": 0, "Local Dirtied Blocks": 0, "Local Written Blocks": 0, "Temp Read Blocks": 0, "Temp Written Blocks": 0, "Plans": [{"Node Type": "Index Scan", "Parent Relationship": "Outer", "Parallel Aware": false, "Async Capable": false, "Scan Direction": "Forward", "Index Name": "messages_history_idx", "Relation Name": "messages", "Alias": "messages", "Startup Cost": 0.42, "Total Cost": 6225.66, "Plan Rows": 5956, "Plan Width": 75, "Actual Startup Time": 0.001, "Actual Total Time": 0.004, "Actual Rows": 51, "Actual Loops": 1, "Index Cond": "((chat_id = 'a9024646-24db-4984-b912-1030eea3ed60'::uuid) AND (ROW(created_at, id) > ROW('2026-10-02 09:42:09.355081+00'::timestamp with time zone, '3101b2d4-b2be-4696-9cf8-ea625d0e9d29'::uuid)))", "Rows Removed by Index Recheck": 0, "Shared Hit Blocks": 6, "Shared Read Blocks": 0, "Shared Dirtied Blocks": 0, "Shared Written Blocks": 0, "Local Hit Blocks": 0, "Local Read Blocks": 0, "Local Dirtied Blocks": 0, "Local Written Blocks": 0, "Temp Read Blocks": 0, "Temp Written Blocks": 0}]}} +Variant B: messages_history_covering_idx +{"variant": "B", "operation": "first", "plan": {"Node Type": "Limit", "Parallel Aware": false, "Async Capable": false, "Startup Cost": 0.42, "Total Cost": 3.89, "Plan Rows": 51, "Plan Width": 75, "Actual Startup Time": 0.002, "Actual Total Time": 0.006, "Actual Rows": 51, "Actual Loops": 1, "Shared Hit Blocks": 5, "Shared Read Blocks": 0, "Shared Dirtied Blocks": 0, "Shared Written Blocks": 0, "Local Hit Blocks": 0, "Local Read Blocks": 0, "Local Dirtied Blocks": 0, "Local Written Blocks": 0, "Temp Read Blocks": 0, "Temp Written Blocks": 0, "Plans": [{"Node Type": "Index Only Scan", "Parent Relationship": "Outer", "Parallel Aware": false, "Async Capable": false, "Scan Direction": "Forward", "Index Name": "messages_history_covering_idx", "Relation Name": "messages", "Alias": "messages", "Startup Cost": 0.42, "Total Cost": 5458.29, "Plan Rows": 80107, "Plan Width": 75, "Actual Startup Time": 0.002, "Actual Total Time": 0.005, "Actual Rows": 51, "Actual Loops": 1, "Index Cond": "(chat_id = 'a9024646-24db-4984-b912-1030eea3ed60'::uuid)", "Rows Removed by Index Recheck": 0, "Heap Fetches": 0, "Shared Hit Blocks": 5, "Shared Read Blocks": 0, "Shared Dirtied Blocks": 0, "Shared Written Blocks": 0, "Local Hit Blocks": 0, "Local Read Blocks": 0, "Local Dirtied Blocks": 0, "Local Written Blocks": 0, "Temp Read Blocks": 0, "Temp Written Blocks": 0}]}} +{"variant": "B", "operation": "deep", "plan": {"Node Type": "Limit", "Parallel Aware": false, "Async Capable": false, "Startup Cost": 0.42, "Total Cost": 4.04, "Plan Rows": 51, "Plan Width": 75, "Actual Startup Time": 0.002, "Actual Total Time": 0.006, "Actual Rows": 51, "Actual Loops": 1, "Shared Hit Blocks": 4, "Shared Read Blocks": 0, "Shared Dirtied Blocks": 0, "Shared Written Blocks": 0, "Local Hit Blocks": 0, "Local Read Blocks": 0, "Local Dirtied Blocks": 0, "Local Written Blocks": 0, "Temp Read Blocks": 0, "Temp Written Blocks": 0, "Plans": [{"Node Type": "Index Only Scan", "Parent Relationship": "Outer", "Parallel Aware": false, "Async Capable": false, "Scan Direction": "Forward", "Index Name": "messages_history_covering_idx", "Relation Name": "messages", "Alias": "messages", "Startup Cost": 0.42, "Total Cost": 523.64, "Plan Rows": 7361, "Plan Width": 75, "Actual Startup Time": 0.002, "Actual Total Time": 0.004, "Actual Rows": 51, "Actual Loops": 1, "Index Cond": "((chat_id = 'a9024646-24db-4984-b912-1030eea3ed60'::uuid) AND (ROW(created_at, id) > ROW('2026-10-02 09:42:09.355081+00'::timestamp with time zone, '3101b2d4-b2be-4696-9cf8-ea625d0e9d29'::uuid)))", "Rows Removed by Index Recheck": 0, "Heap Fetches": 0, "Shared Hit Blocks": 4, "Shared Read Blocks": 0, "Shared Dirtied Blocks": 0, "Shared Written Blocks": 0, "Local Hit Blocks": 0, "Local Read Blocks": 0, "Local Dirtied Blocks": 0, "Local Written Blocks": 0, "Temp Read Blocks": 0, "Temp Written Blocks": 0}]}} +Original history index restored; committed write rows=5000 +Index size after benchmark, original A=6799360 bytes, covering B=11935744 bytes; B dropped after measurement diff --git a/evidence/restore-check.txt b/evidence/restore-check.txt new file mode 100644 index 00000000..30057f78 --- /dev/null +++ b/evidence/restore-check.txt @@ -0,0 +1,19 @@ +UTC start: 2026-10-02T09:51:09Z +Source: mtusi2026lab2_postgres_data; new volume: mtusi2026lab2_restore_20261002125101_21469 +pg_dump custom-format backup: 3441039 bytes, 0 seconds +pg_restore into fresh volume: 0 seconds +New PostgreSQL + pg_restore + restored API ready: 10 seconds +Source PostgreSQL stopped; verification uses only postgres_restore and api_restore +Restore fingerprint PASS (all rows, ordered by primary key): + users: count=110 sha256=84e13a36176df82d787eeb17cf160e722adb27b354efc63cb0b071b60cb3d0dc + chats: count=26 sha256=53597c37349eeb1dd2dcc4b844ebd0daf609ec94b0f0b761c49f2494d8d5f283 + memberships: count=41 sha256=04f4aa2eda1dac52d50043574125826e294c572f9e1ca38e9ae871ad12ac3897 + messages: count=115026 sha256=f59985688652b2c9a4217847a4c4967ab7763714913fc59980e6e905bb43aa9d + sessions: count=49 sha256=81c9bd6d920343331e8855ffccf7122f21f02778decedd3f4cc3bb76c8f62147 +Selected synthetic messages PASS (id, text SHA-256): + c00beec9-c124-44c5-8a91-0629359b0fbc 535c5b38862ae8ece532e63f3f4003ed180a8d072364909e203a07c0e586f564 + ebe3793f-8a8e-4ea7-b440-b4d6b98758cb 0bef8c417a079915200fb7168a9ccd09a91f72761098499885c55c762c98e125 + 7d0b0c48-437f-45d0-98ab-05d80ee615a6 160bf34ba510916e90b48de2484fd9e055fdff06a103da43c94488ca43736fd0 +Restored API PASS: readiness 200, active token reads first message 200, expired token 401 +UTC verified: 2026-10-02T09:51:20Z +Recovery point: pg_dump snapshot; writes committed afterward are outside this backup diff --git a/scripts/backup_restore.sh b/scripts/backup_restore.sh new file mode 100755 index 00000000..8162d658 --- /dev/null +++ b/scripts/backup_restore.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")/.." + +RESTORE_VOLUME_NAME="mtusi2026lab2_restore_$(date +%Y%m%d%H%M%S)_$$" +export RESTORE_VOLUME_NAME +work="$(mktemp -d)" +RESTORE_DATABASE_URL_FILE="$PWD/secrets/database_url_restore_${RESTORE_VOLUME_NAME}" +export RESTORE_DATABASE_URL_FILE +source_stopped=0 +cleanup() { + if [ "$source_stopped" -eq 1 ]; then + docker compose --env-file .env start postgres >/dev/null + fi + docker compose --env-file .env -f compose.yaml -f compose.restore.yaml stop api_restore postgres_restore >/dev/null 2>&1 || true + docker compose --env-file .env -f compose.yaml -f compose.restore.yaml rm -sf api_restore postgres_restore >/dev/null 2>&1 || true + rm -f "$RESTORE_DATABASE_URL_FILE" + rm -rf "$work" +} +trap cleanup EXIT + +# Derive a private URL for the new service without printing the password. +python3 - "$RESTORE_DATABASE_URL_FILE" <<'PY' +from pathlib import Path +import sys +from urllib.parse import urlsplit, urlunsplit + +url = urlsplit(Path('secrets/database_url').read_text().strip()) +assert url.hostname == 'postgres', 'expected source hostname postgres' +host = url.netloc.replace('@postgres:', '@postgres_restore:') +assert host != url.netloc +Path(sys.argv[1]).write_text(urlunsplit(url._replace(netloc=host))) +PY +chmod 600 "$RESTORE_DATABASE_URL_FILE" + +compose=(docker compose --env-file .env -f compose.yaml -f compose.restore.yaml) +docker compose --env-file .env up -d --build --wait api >/dev/null +docker compose --env-file .env exec -T -e PYTHONPATH=/app api python student-tests/test_restore.py prepare > "$work/expected.json" +chmod 600 "$work/expected.json" +echo "UTC start: $(date -u +%Y-%m-%dT%H:%M:%SZ)" +echo "Source: mtusi2026lab2_postgres_data; new volume: $RESTORE_VOLUME_NAME" +backup_start=$(date +%s) +docker compose --env-file .env exec -T postgres pg_dump -Fc -U messenger -d messenger > "$work/backup.dump" +backup_end=$(date +%s) +echo "pg_dump custom-format backup: $(wc -c < "$work/backup.dump") bytes, $((backup_end-backup_start)) seconds" +recovery_start=$(date +%s) +"${compose[@]}" up -d --wait postgres_restore >/dev/null +restore_start=$(date +%s) +"${compose[@]}" exec -T postgres_restore pg_restore --exit-on-error -U messenger -d messenger --no-owner --no-acl < "$work/backup.dump" +restore_end=$(date +%s) +echo "pg_restore into fresh volume: $((restore_end-restore_start)) seconds" +"${compose[@]}" up -d --build --wait api_restore >/dev/null +recovery_end=$(date +%s) +echo "New PostgreSQL + pg_restore + restored API ready: $((recovery_end-recovery_start)) seconds" +docker compose --env-file .env stop postgres >/dev/null +source_stopped=1 +echo "Source PostgreSQL stopped; verification uses only postgres_restore and api_restore" +"${compose[@]}" exec -T -e PYTHONPATH=/app api_restore python student-tests/test_restore.py verify < "$work/expected.json" +echo "UTC verified: $(date -u +%Y-%m-%dT%H:%M:%SZ)" +echo "Recovery point: pg_dump snapshot; writes committed afterward are outside this backup" diff --git a/scripts/track2_experiment.py b/scripts/track2_experiment.py new file mode 100644 index 00000000..8804dac1 --- /dev/null +++ b/scripts/track2_experiment.py @@ -0,0 +1,128 @@ +"""Reproducible 100k-row history-index and insert-cost experiment.""" + +import csv +import json +import secrets +import sys +from datetime import datetime, timezone +from time import perf_counter +from uuid import uuid4 + +import psycopg +from psycopg.rows import dict_row + +from src.db import database_url +from src.store import Store + + +HISTORY = "CREATE INDEX messages_history_idx ON messages (chat_id, created_at, id)" +COVERING = ( + "CREATE INDEX messages_history_covering_idx ON messages " + "(chat_id, created_at, id) INCLUDE (sender_id, text)" +) +PROJECTION = "SELECT id,chat_id,sender_id,text,created_at FROM messages WHERE chat_id=%s" + + +def explain(conn, query, params): + result = conn.execute("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) " + query, params).fetchone()["QUERY PLAN"][0] + plan = result["Plan"] + names = [] + + def visit(node): + names.append(node.get("Index Name", node["Node Type"])) + for child in node.get("Plans", []): + visit(child) + + visit(plan) + return result, " > ".join(names) + + +def main(): + store = Store() + user = store.register("track2_" + uuid4().hex[:16], "Synthetic benchmark", secrets.token_urlsafe(18)) + sizes = (("hot", 80_000), ("medium", 15_000), ("cold", 5_000)) + chats = [(name, size, store.create_chat(user["id"], "Track 2 " + name, [user["id"]])["id"]) + for name, size in sizes] + write_chat = store.create_chat(user["id"], "Track 2 writes", [user["id"]])["id"] + with psycopg.connect(database_url(), autocommit=True, row_factory=dict_row) as conn: + conn.execute("SET statement_timeout=0") + base = datetime.now(timezone.utc) + for name, size, chat_id in chats: + conn.execute( + "INSERT INTO messages (id,chat_id,sender_id,text,created_at) " + "SELECT gen_random_uuid(),%s,%s,%s || n,%s::timestamptz + n * interval '1 microsecond' " + "FROM generate_series(1,%s) n", + (chat_id, user["id"], name + "-synthetic-", base, size), + ) + conn.execute("VACUUM (ANALYZE) messages") + total = sum(conn.execute("SELECT count(*) AS n FROM messages WHERE chat_id=%s", (chat_id,)) + .fetchone()["n"] for _, _, chat_id in chats) + assert total == 100_000 + hot_id = chats[0][2] + cursor = conn.execute( + "SELECT created_at,id FROM messages WHERE chat_id=%s " + "ORDER BY created_at,id OFFSET 71999 LIMIT 1", (hot_id,) + ).fetchone() + queries = ( + ("first", PROJECTION + " ORDER BY created_at,id LIMIT 51", (hot_id,)), + ("deep", PROJECTION + " AND (created_at,id)>(%s,%s) " + "ORDER BY created_at,id LIMIT 51", (hot_id, cursor["created_at"], cursor["id"])), + ) + writer = csv.writer(sys.stdout, lineterminator="\n") + writer.writerow(("variant", "index", "operation", "trial", "dataset_rows", "execution_ms", + "shared_hit", "shared_read", "shared_dirtied", "plan", "rows_inserted")) + print(f"UTC: {datetime.now(timezone.utc).isoformat()}", file=sys.stderr) + print(f"PostgreSQL: {conn.execute('SHOW server_version').fetchone()['server_version']}", file=sys.stderr) + print("Synthetic chat sizes: hot=80000, medium=15000, cold=5000; fixed 51-row pages; deep cursor=72000", file=sys.stderr) + try: + conn.execute("DROP INDEX IF EXISTS messages_history_covering_idx") + conn.execute(HISTORY.replace("CREATE INDEX", "CREATE INDEX IF NOT EXISTS", 1)) + for variant, index in (("A", "messages_history_idx"), + ("B", "messages_history_covering_idx")): + if variant == "B": + conn.execute("DROP INDEX messages_history_idx") + conn.execute(COVERING) + conn.execute("VACUUM (ANALYZE) messages") + print(f"Variant {variant}: {index}", file=sys.stderr) + for label, query, params in queries: + expected = [row["id"] for row in conn.execute(query, params).fetchall()] + assert len(expected) == 51 + for _ in range(3): + explain(conn, query, params) + for trial in range(1, 6): + result, plan = explain(conn, query, params) + actual = [row["id"] for row in conn.execute(query, params).fetchall()] + assert actual == expected + node = result["Plan"] + writer.writerow((variant, index, label, trial, total, result["Execution Time"], + node.get("Shared Hit Blocks", 0), node.get("Shared Read Blocks", 0), + node.get("Shared Dirtied Blocks", 0), plan, 0)) + if trial == 1: + print(json.dumps({"variant": variant, "operation": label, "plan": node}, + default=str), file=sys.stderr) + # Same 500-row write statement on a separate synthetic chat under each index. + # Five committed repetitions include index maintenance and commit time. + for trial in range(1, 6): + start = perf_counter() + with conn.transaction(): + conn.execute( + "INSERT INTO messages (id,chat_id,sender_id,text,created_at) " + "SELECT gen_random_uuid(),%s,%s,'write-synthetic-' || n," + "clock_timestamp() + n * interval '1 microsecond' " + "FROM generate_series(1,500) n", + (write_chat, user["id"]), + ) + elapsed = (perf_counter() - start) * 1000 + writer.writerow((variant, index, "write500", trial, total, round(elapsed, 3), + "", "", "", "INSERT 500 + COMMIT", 500)) + finally: + conn.execute("DROP INDEX IF EXISTS messages_history_covering_idx") + conn.execute(HISTORY.replace("CREATE INDEX", "CREATE INDEX IF NOT EXISTS", 1)) + assert conn.execute( + "SELECT count(*) AS n FROM messages WHERE chat_id=%s", (write_chat,) + ).fetchone()["n"] == 5000 + print("Original history index restored; committed write rows=5000", file=sys.stderr) + + +if __name__ == "__main__": + main() diff --git a/student-tests/test_restore.py b/student-tests/test_restore.py new file mode 100644 index 00000000..4312aae5 --- /dev/null +++ b/student-tests/test_restore.py @@ -0,0 +1,116 @@ +"""Prepare a private fingerprint, then verify a restored DB and API without source DB.""" + +import hashlib +import json +import secrets +import sys +import urllib.error +import urllib.request +from uuid import UUID + +import psycopg +from psycopg.rows import dict_row + +from src.auth import token_hash +from src.db import database_url + + +TABLES = { + "users": "id", + "chats": "id", + "memberships": "chat_id,user_id", + "messages": "id", + "sessions": "token_hash", +} + + +def fingerprints(conn): + result = {} + for table, order in TABLES.items(): + digest = hashlib.sha256() + count = 0 + with conn.cursor(name="fingerprint_" + table) as cursor: + cursor.execute(f"SELECT * FROM {table} ORDER BY {order}") + for row in cursor: + digest.update(repr(tuple(row.values())).encode("utf-8")) + digest.update(b"\n") + count += 1 + result[table] = {"count": count, "sha256": digest.hexdigest()} + return result + + +def samples(conn, chat_id): + found = [] + for offset in (0, 39_999, 79_999): + row = conn.execute( + "SELECT id,text FROM messages WHERE chat_id=%s " + "ORDER BY created_at,id OFFSET %s LIMIT 1", (UUID(chat_id), offset) + ).fetchone() + assert row is not None, "benchmark chat must contain 80000 messages" + found.append({"id": str(row["id"]), "text_sha256": hashlib.sha256(row["text"].encode()).hexdigest()}) + return found + + +def request(url, token=None): + headers = {"Authorization": "Bearer " + token} if token else {} + try: + with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=10) as response: + return response.status, json.load(response) + except urllib.error.HTTPError as error: + return error.code, None + + +def prepare(): + with psycopg.connect(database_url(), row_factory=dict_row) as conn: + chat = conn.execute( + "SELECT c.id,m.user_id FROM chats c JOIN memberships m ON m.chat_id=c.id " + "WHERE c.title='Track 2 hot' ORDER BY c.created_at DESC LIMIT 1" + ).fetchone() + assert chat is not None + active = secrets.token_urlsafe(32) + expired = secrets.token_urlsafe(32) + conn.execute( + "INSERT INTO sessions(token_hash,user_id,expires_at) " + "VALUES (%s,%s,clock_timestamp()+interval '1 hour')," + "(%s,%s,clock_timestamp()-interval '1 second')", + (token_hash(active), chat["user_id"], token_hash(expired), chat["user_id"]), + ) + conn.commit() + expected = { + "chat_id": str(chat["id"]), "active_token": active, "expired_token": expired, + "tables": fingerprints(conn), "samples": samples(conn, str(chat["id"])), + } + print(json.dumps(expected)) # Redirect only into a temporary chmod-600 file. + + +def verify(): + expected = json.load(sys.stdin) + with psycopg.connect(database_url(), row_factory=dict_row) as conn: + actual_tables = fingerprints(conn) + actual_samples = samples(conn, expected["chat_id"]) + assert actual_tables == expected["tables"], "restored table count/content mismatch" + assert actual_samples == expected["samples"], "restored selected message mismatch" + base = "http://127.0.0.1:8080" + assert request(base + "/health/ready")[0] == 200 + status, page = request(base + "/api/v1/chats/" + expected["chat_id"] + "/messages?limit=50", + expected["active_token"]) + assert status == 200 + assert expected["samples"][0]["id"] in {item["id"] for item in page["items"]} + assert request(base + "/api/v1/chats/" + expected["chat_id"] + "/messages?limit=50", + expected["expired_token"])[0] == 401 + print("Restore fingerprint PASS (all rows, ordered by primary key):") + for table, value in actual_tables.items(): + print(f" {table}: count={value['count']} sha256={value['sha256']}") + print("Selected synthetic messages PASS (id, text SHA-256):") + for sample in actual_samples: + print(f" {sample['id']} {sample['text_sha256']}") + print("Restored API PASS: readiness 200, active token reads first message 200, expired token 401") + + +if __name__ == "__main__": + if sys.argv[1:] == ["prepare"]: + prepare() + elif sys.argv[1:] == ["verify"]: + verify() + else: + raise SystemExit("usage: test_restore.py prepare|verify")