feat: prove query tradeoffs and fresh-volume restore
Application / smoke (pull_request) Failing after 36s
Skeleton contracts / contracts (pull_request) Failing after 40s

This commit is contained in:
Самохвалов Андрей Ремович
2026-10-02 12:58:21 +03:00
parent e50ba0f8d2
commit b3dae2855f
9 changed files with 436 additions and 4 deletions
+1
View File
@@ -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 src/ src/
COPY --chown=app:app migrations/ migrations/ COPY --chown=app:app migrations/ migrations/
COPY --chown=app:app scripts/migrate.py scripts/migrate.py 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 USER app
EXPOSE 8080 EXPOSE 8080
CMD ["sh", "-c", "python scripts/migrate.py && exec python -m src.server"] CMD ["sh", "-c", "python scripts/migrate.py && exec python -m src.server"]
+27 -4
View File
@@ -1,7 +1,7 @@
# Отчёт — лабораторная 2 # Отчёт — лабораторная 2
- Автор, группа: Самохвалов Андрей Ремович, БПИ-2302. - Автор, группа: Самохвалов Андрей Ремович, БПИ-2302.
- Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Уровень 4 проверен; исследование трека 2 выполняется следующим блоком. - Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Уровни 3 и 4 и выбранный трек 5 проверены на локальном стенде.
- Ветка: `solution/bpi2302-samohvalov`; commit/PR указываются после публикации. - Ветка: `solution/bpi2302-samohvalov`; commit/PR указываются после публикации.
- Источники: `README.md`, `COURSE.md`, `contracts/README.md`, `contracts/openapi.json`, публичные тесты и примеры этого репозитория; FastAPI, psycopg, PostgreSQL и Argon2id. Код и инструкции подготовлены с помощью ИИ Codex и проверяются запуском команд ниже. - Источники: `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 check
make test make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh 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`. На каждом старте 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 | `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 | `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` | | Индекс истории уровня 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` для проверки контракта. У `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 строк. Для 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; для выбора индекса под иным распределением данных опыт надо повторить.
+43
View File
@@ -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}
+31
View File
@@ -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
1 variant index operation trial dataset_rows execution_ms shared_hit shared_read shared_dirtied plan rows_inserted
2 A messages_history_idx first 1 100000 0.008 6 0 0 Limit > messages_history_idx 0
3 A messages_history_idx first 2 100000 0.015 6 0 0 Limit > messages_history_idx 0
4 A messages_history_idx first 3 100000 0.011 6 0 0 Limit > messages_history_idx 0
5 A messages_history_idx first 4 100000 0.009 6 0 0 Limit > messages_history_idx 0
6 A messages_history_idx first 5 100000 0.009 6 0 0 Limit > messages_history_idx 0
7 A messages_history_idx deep 1 100000 0.009 6 0 0 Limit > messages_history_idx 0
8 A messages_history_idx deep 2 100000 0.017 6 0 0 Limit > messages_history_idx 0
9 A messages_history_idx deep 3 100000 0.011 6 0 0 Limit > messages_history_idx 0
10 A messages_history_idx deep 4 100000 0.022 6 0 0 Limit > messages_history_idx 0
11 A messages_history_idx deep 5 100000 0.009 6 0 0 Limit > messages_history_idx 0
12 A messages_history_idx write500 1 100000 3.997 INSERT 500 + COMMIT 500
13 A messages_history_idx write500 2 100000 3.276 INSERT 500 + COMMIT 500
14 A messages_history_idx write500 3 100000 2.616 INSERT 500 + COMMIT 500
15 A messages_history_idx write500 4 100000 2.632 INSERT 500 + COMMIT 500
16 A messages_history_idx write500 5 100000 2.467 INSERT 500 + COMMIT 500
17 B messages_history_covering_idx first 1 100000 0.009 5 0 0 Limit > messages_history_covering_idx 0
18 B messages_history_covering_idx first 2 100000 0.011 5 0 0 Limit > messages_history_covering_idx 0
19 B messages_history_covering_idx first 3 100000 0.013 5 0 0 Limit > messages_history_covering_idx 0
20 B messages_history_covering_idx first 4 100000 0.01 5 0 0 Limit > messages_history_covering_idx 0
21 B messages_history_covering_idx first 5 100000 0.016 5 0 0 Limit > messages_history_covering_idx 0
22 B messages_history_covering_idx deep 1 100000 0.009 4 0 0 Limit > messages_history_covering_idx 0
23 B messages_history_covering_idx deep 2 100000 0.009 4 0 0 Limit > messages_history_covering_idx 0
24 B messages_history_covering_idx deep 3 100000 0.011 4 0 0 Limit > messages_history_covering_idx 0
25 B messages_history_covering_idx deep 4 100000 0.012 4 0 0 Limit > messages_history_covering_idx 0
26 B messages_history_covering_idx deep 5 100000 0.01 4 0 0 Limit > messages_history_covering_idx 0
27 B messages_history_covering_idx write500 1 100000 2.638 INSERT 500 + COMMIT 500
28 B messages_history_covering_idx write500 2 100000 12.557 INSERT 500 + COMMIT 500
29 B messages_history_covering_idx write500 3 100000 2.7 INSERT 500 + COMMIT 500
30 B messages_history_covering_idx write500 4 100000 2.382 INSERT 500 + COMMIT 500
31 B messages_history_covering_idx write500 5 100000 2.439 INSERT 500 + COMMIT 500
+11
View File
@@ -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
+19
View File
@@ -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
+60
View File
@@ -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"
+128
View File
@@ -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()
+116
View File
@@ -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")