feat: add backup and restore stage to bench

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-02 05:17:41 +03:00
co-authored by Claude Opus 5.5
parent 860bdac4f3
commit 8bc42720d7
11 changed files with 1210 additions and 35 deletions
+19 -3
View File
@@ -19,7 +19,8 @@ paths:
На лабе 2 стенд нужен для двух вещей: план запроса истории
`EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях (уровень 4) и
сравнение индексов и запросов со стоимостью записи на чатах разного
размера для трека «5» №2 (`README.md`). Варианты сравниваются внутри
размера, а также backup и восстановление со сверкой для трека «5» №2
(`README.md`). Варианты сравниваются внутри
одной метки, на одних данных; «до» и «после» через `make bench_ab` нужны,
только когда меняется код приложения. Метки лабы 1 сюда не
переносились: другое хранилище — другая методика, сравнивать их с
@@ -31,11 +32,12 @@ paths:
хранилищ `run.py` генерирует на прогон и никуда не пишет. Каждый размер —
свежий стенд: `down -v`, Postgres и Valkey, миграции, API.
В `bench/` три инструмента:
В `bench/` четыре инструмента:
| Файл | Команда | Что делает |
|---|---|---|
| `run.py`, `k6/`, `bench.compose.yml`, `bench.env` | `make bench`, `make bench_quick` | стенд: меряет пропускную способность, задержки, CPU API и Postgres, память, снимает планы запроса истории |
| `run.py` (профили `restore`, `restore_quick`), `k6/after_backup.js`, `k6/restore_check.js` | `make bench_restore`, `make bench_restore_quick` | тот же стенд без матрицы прогонов: backup под записью, восстановление в новое хранилище, сверка, RTO и потеря, кэш до и после `FLUSHALL` |
| `compare.py` | `make bench_compare` | дельта двух меток стенда, эффект или шум |
| `ab.py` | `make bench_ab` | стенд «до» и «после» одного изменения подряд, в одной сессии хоста |
@@ -70,6 +72,12 @@ paths:
- **варианты и пробы:** варианты индекса истории — `Profile.index_variants`,
проба записи — `write_probe_rows` строк, `write_probe_repeats`
повторов со сдвигом порядка конфигураций;
- **восстановление** (профили `restore*`): `pg_dump -Fc` во время
записи `restore_write_load` сообщений `restore_write_vus` клиентами,
`pg_restore -j restore_jobs` в контейнер того же образа и с лимитами
Postgres стенда на новом volume, `ANALYZE`, переключение API через
`POSTGRES_HOST`. Файл backup живёт только в `.work/`: в нём хэши
паролей и токенов;
- **генератор:** `grafana/k6` той же версии и digest, в той же
docker-сети, без лимита CPU;
- **профиль `full`:** размеры, конкуренция, повторы, прогрев и
@@ -103,7 +111,15 @@ paths:
курсором через `OR`, generic plan) в транзакции, которая
откатывается;
- пробы записи по вариантам индекса в транзакции, которая
откатывается, и `VACUUM messages` после каждой.
откатывается, и `VACUUM messages` после каждой;
- `pg_dump` исходной базы, второе хранилище (`docker run`, имя
`mtusi-bench-postgres-restore`, volume `mtusi-bench_restore`, метка
проекта), `pg_restore` и `ANALYZE` в нём, построчная сверка обеих
баз;
- `FLUSHALL` Valkey стенда и пересоздание API с адресом
восстановленной базы — только на этапе восстановления, в конце
размера. Второе хранилище и его volume `Stand.stop()` удаляет до
`compose down`.
Данных и схемы, видимых приложению, он не меняет: список индексов и
число строк `messages` до и после этапа сверяются, при различии —
+5 -3
View File
@@ -255,6 +255,8 @@ change `track2-query-plans`. Этот файл и `.claude/rules/` описыв
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~45 с) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; стенд и его volume удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) |
| `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт |
| `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` |
| `make bench_restore_quick` | то же на 1k / 5k / 10k (~1,5 мин), метка `quick-restore-<время>`, в git не идёт; сценарий защиты трека 2 |
| `make bench_ab BEFORE=... AFTER=... REAPPLY=<commit>` | «до» и «после» одного изменения подряд (два прогона `bench`): `bench` для `BEFORE`, commit доказательств, `git revert` commit отката `REAPPLY`, `bench` для `AFTER`. Нужно чистое рабочее дерево; сама делает два коммита |
| `make bench_compare BEFORE=... AFTER=... [AA=...]` | дельта двух меток `make bench` по ячейкам матрицы; метки с разной методикой не сравнивает; с `AA` (метка того же кода, что `BEFORE`) отделяет эффект от шума. Результат в `evidence/compare/<до>__<после>.md` |
@@ -315,10 +317,10 @@ student-tests/ # black-box тесты по HTTP (уровень 4)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause, кэш, триггер сбоя участников (stdlib)
failures.compose.yml # override стенда отказов: без публикации портов
bench/ # нагрузочный стенд на API + Postgres + Valkey: make bench / make bench_quick
run.py # оркестратор: стенд compose, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, метрики, runs.csv / summary.md / meta.json
run.py # оркестратор: стенд compose, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, метрики, runs.csv / summary.md / meta.json
bench.compose.yml # override стенда mtusi-bench: имена, лимиты BENCH_*, без портов и config.toml, auto_explain
bench.env # подстановки compose стенда вместо .env рабочего стенда (без паролей)
k6/ # сценарии k6: prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write; lib.js — Bearer и хелперы
k6/ # сценарии k6: prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления); lib.js — Bearer и хелперы
compare.py # make bench_compare: дельта двух меток, уровень шума, эффект или шум
ab.py # make bench_ab: прогоны «до» и «после» одного изменения подряд
migrations/, alembic.ini # ревизии alembic, async env.py; применяет одноразовый сервис compose
@@ -334,7 +336,7 @@ evidence/migrations/ # миграции с нуля и повторно,
evidence/auth/ # пароли и токены в БД, срок сессии, TTL из конфига
evidence/cache/ # попадания в кэш, отказ Valkey, FLUSHALL и рестарт
evidence/tests/ # выводы make test_isolated, make student_test и make failure_checks для REPORT.md
evidence/bench/<метка>/ # результаты make bench: паспорт, прогоны, наполнение, сводка, планы explain-<размер>.txt, сырые итоги k6
evidence/bench/<метка>/ # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6
evidence/compare/ # таблицы make bench_compare: <до>__<после>.md
KNOWN_ISSUES.md # найденные попутно дефекты, не исправленные без просьбы
```
+16
View File
@@ -153,6 +153,22 @@ bench:
bench_quick:
uv run python bench/run.py --profile quick --label quick-$(shell date -u +%Y%m%dT%H%M%SZ)
RESTORE_LABEL ?= restore
# трек 2: backup под записью, восстановление в новое хранилище, сверка БД и
# через HTTP, кэш до и после FLUSHALL — на 10k / 100k / 500k с фоновыми
# чатами, без матрицы прогонов, ~20 мин; результат —
# evidence/bench/$(RESTORE_LABEL)/
.PHONY: bench_restore
bench_restore:
uv run python bench/run.py --profile restore --label $(RESTORE_LABEL)
# то же на малых размерах (самопроверка, сценарий защиты), ~2 мин; в git
# не идёт
.PHONY: bench_restore_quick
bench_restore_quick:
uv run python bench/run.py --profile restore_quick --label quick-restore-$(shell date -u +%Y%m%dT%H%M%SZ)
# дельта двух меток по ячейкам матрицы: BEFORE и AFTER обязательны, AA —
# метка того же кода, что BEFORE, для уровня шума; результат —
# evidence/compare/$(BEFORE)__$(AFTER).md
+42
View File
@@ -0,0 +1,42 @@
// Активность после backup (трек 2, восстановление): новый пользователь
// с паролем входит по Basic, создаёт чат с читателем и пишет в него одно
// сообщение. После восстановления из backup всего этого в базе быть не
// должно, а карточка чата остаётся в кэше. Итог — after.json в рабочем
// каталоге (токен только там, оркестратор удаляет его в конце прогона).
import http from "k6/http";
import { fail } from "k6";
import { API, WORK_DIR, authHeaders, createChat, register } from "./lib.js";
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "60s",
};
export function setup() {
const stamp = Date.now().toString(36);
const late = register(`b${stamp}_late`, "Bench after backup");
const chatId = createChat(
late.token,
"bench after backup",
[late.id, fixture.readerId],
);
const res = http.post(
`${API}/chats/${chatId}/messages`,
JSON.stringify({ text: "written after backup" }),
{ headers: authHeaders(late.token) },
);
if (res.status !== 201) {
fail(`message after backup: ${res.status} ${res.body}`);
}
return { userId: late.id, token: late.token, chatId };
}
export default function () {}
export function handleSummary(data) {
return { [`${WORK_DIR}/after.json`]: JSON.stringify(data.setup_data) };
}
+78
View File
@@ -0,0 +1,78 @@
// Проверки восстановления через HTTP (трек 2), фаза — PHASE:
// - source: исходная база до восстановления;
// - stale: API на восстановленной базе, кэш ещё не очищен;
// - restored: после FLUSHALL.
// Во всех фазах — страницы этапа плана (plan_pages.json) и /users/me
// читателя; в stale и restored — ещё чат и пользователь «после backup».
// Ответы не проверяются здесь: статусы и элементы страниц пишутся в
// check-<фаза>.json, сверяет оркестратор. Токенов в итоге нет.
import http from "k6/http";
import { API, PAGE_LIMIT, WORK_DIR, authHeaders } from "./lib.js";
const PHASE = __ENV.PHASE;
const fixture = JSON.parse(open(`${WORK_DIR}/fixture.json`));
const pages = JSON.parse(open(`${WORK_DIR}/plan_pages.json`));
// after.json появляется только после активности «после backup»
const after = PHASE === "source"
? null
: JSON.parse(open(`${WORK_DIR}/after.json`));
export const options = {
vus: 1,
iterations: 1,
setupTimeout: "5m",
};
function status(res) {
return res.status;
}
export function setup() {
const reader = { headers: authHeaders(fixture.tokens[fixture.readerId]) };
const result = {
phase: PHASE,
reader_me: status(http.get(`${API}/users/me`, reader)),
pages: pages.map((page) => {
const query = page.cursor === null
? `?limit=${PAGE_LIMIT}`
: `?limit=${PAGE_LIMIT}&cursor=${encodeURIComponent(page.cursor)}`;
const res = http.get(
`${API}/chats/${page.chat_id}/messages${query}`,
reader,
);
return {
chat: page.chat,
page: page.page,
status: res.status,
items: res.status === 200 ? res.json("items") : null,
};
}),
};
if (after !== null) {
const late = { headers: authHeaders(after.token) };
result.late_me = status(http.get(`${API}/users/me`, late));
result.after_chat_get = status(
http.get(`${API}/chats/${after.chatId}`, reader),
);
}
if (PHASE === "stale") {
// запись в чат, которого нет в восстановленной базе, а карточка — в кэше
result.after_chat_post = status(
http.post(
`${API}/chats/${after.chatId}/messages`,
JSON.stringify({ text: "written to a stale chat" }),
reader,
),
);
}
return result;
}
export default function () {}
export function handleSummary(data) {
return {
[`${WORK_DIR}/check-${PHASE}.json`]: JSON.stringify(data.setup_data),
};
}
+499 -29
View File
@@ -42,6 +42,13 @@ APP = "mtusi-bench-api"
DB = "mtusi-bench-postgres"
CACHE = "mtusi-bench-valkey"
K6 = "mtusi-bench-k6"
# второе хранилище этапа восстановления: контейнер, volume и имя в сети
# стенда (по нему API переключается на восстановленную базу)
RESTORE_DB = "mtusi-bench-postgres-restore"
RESTORE_VOLUME = "mtusi-bench_restore"
RESTORE_HOST = "postgres-restore"
# таблицы данных приложения: сверка числа строк после восстановления
DATA_TABLES = ("users", "chats", "chat_members", "sessions", "messages")
# контейнеры стенда по ролям: лимиты, состояние, паспорт
CONTAINERS = {"api": APP, "postgres": DB, "valkey": CACHE}
COMPOSE_FILES = (
@@ -222,6 +229,13 @@ class Profile:
)
write_probe_rows: int = 20_000
write_probe_repeats: int = 3
# трек 2, часть 2: backup и восстановление в новое хранилище в конце
# размера; pg_restore -j, запись через HTTP во время backup. Решение 1
# design change track2-backup-restore
restore: bool = False
restore_jobs: int = 4
restore_write_load: int = 5_000
restore_write_vus: int = 10
@property
def background_total(self) -> int:
@@ -255,6 +269,33 @@ PROFILES = {
background=((2, 1_000), (10, 100), (50, 10)),
write_probe_rows=5_000,
),
# backup и восстановление на данных полной матрицы, без прогонов
"restore": Profile(
name="restore",
sizes=(10_000, 100_000, 500_000),
concurrency=(),
repeats=0,
read_warmup_s=0,
read_measure_s=0,
write_warmup=0,
write_measure=0,
background=((10, 5_000), (100, 400), (1_000, 10)),
restore=True,
),
"restore_quick": Profile(
name="restore_quick",
sizes=(1_000, 5_000, 10_000),
concurrency=(),
repeats=0,
read_warmup_s=0,
read_measure_s=0,
write_warmup=0,
write_measure=0,
background=((2, 1_000), (10, 100), (50, 10)),
write_probe_rows=5_000,
restore=True,
restore_write_load=1_000,
),
}
@@ -739,17 +780,98 @@ class Stand:
def stop(self) -> bool:
"""k6, контейнеры, сеть и volume стенда; True — ничего не осталось.
k6 — первым: подключённый к сети чужой контейнер не дал бы compose
удалить сеть.
k6 и хранилище восстановления — первыми: подключённый к сети
контейнер не из compose не дал бы compose удалить сеть. Volume
восстановления compose не знает, он удаляется отдельно.
"""
subprocess.run(
["docker", "rm", "-f", K6],
["docker", "rm", "-f", K6, RESTORE_DB],
capture_output=True,
check=False,
)
self.compose("down", "-v", "--remove-orphans", check=False)
subprocess.run(
["docker", "volume", "rm", RESTORE_VOLUME],
capture_output=True,
check=False,
)
return not any(leftovers().values())
def start_restore(self) -> None:
"""Новое хранилище: контейнер PostgreSQL на новом volume.
Образ — тот же, что у исходного контейнера (пин без копии в коде),
лимиты — как у Postgres стенда, пароль — `--env` без значения из
окружения процесса. Метка проекта — чтобы `leftovers()` видел
остатки (решение 3 design change `track2-backup-restore`).
"""
image = sh("docker", "inspect", "-f", "{{.Config.Image}}", DB)
env = dict(
item.split("=", 1)
for item in json.loads(
sh("docker", "inspect", "-f", "{{json .Config.Env}}", DB),
)
)
label = f"com.docker.compose.project={PROJECT}"
sh("docker", "volume", "create", "--label", label, RESTORE_VOLUME)
proc = subprocess.run(
[
"docker",
"run",
"-d",
"--name",
RESTORE_DB,
"--label",
label,
"--network",
NETWORK,
"--network-alias",
RESTORE_HOST,
"--env",
"POSTGRES_PASSWORD",
"-e",
f"POSTGRES_USER={env['POSTGRES_USER']}",
"-e",
f"POSTGRES_DB={env['POSTGRES_DB']}",
"--cpus",
self.profile.db_cpus,
"--memory",
self.profile.db_memory,
"--memory-swap",
self.profile.db_memory,
"-v",
f"{RESTORE_VOLUME}:/var/lib/postgresql",
image,
],
capture_output=True,
text=True,
env=self.env,
check=False,
)
if proc.returncode != 0:
raise BenchError(f"restore storage did not start: {proc.stderr}")
# по TCP, как healthcheck compose: при инициализации образ
# поднимает временный сервер только на сокете
deadline = time.monotonic() + 60
while time.monotonic() < deadline:
ready = subprocess.run(
[
"docker",
"exec",
RESTORE_DB,
"sh",
"-c",
'pg_isready -q -h 127.0.0.1 -U "$POSTGRES_USER" '
'-d "$POSTGRES_DB"',
],
capture_output=True,
check=False,
)
if ready.returncode == 0:
return
time.sleep(0.25)
raise BenchError(f"{RESTORE_DB} not ready in 60s")
def limits(self) -> dict[str, Any]:
"""Лимиты контейнеров стенда, прочитанные у запущенных контейнеров."""
limits = {}
@@ -790,10 +912,19 @@ class Stand:
down.append(name)
return down
def psql(self, sql: str, *, check: bool = True) -> str:
"""SQL в базе стенда через stdin: пользователь контейнера, без пароля."""
def psql(
self,
sql: str,
*,
check: bool = True,
container: str = DB,
) -> str:
"""SQL в базе стенда через stdin: пользователь контейнера, без пароля.
`container` — исходное хранилище или хранилище восстановления.
"""
proc = subprocess.run(
["docker", "exec", "-i", DB, "sh", "-c", PSQL],
["docker", "exec", "-i", container, "sh", "-c", PSQL],
input=sql,
capture_output=True,
text=True,
@@ -839,11 +970,12 @@ class Stand:
for chat, count in (line.split("|") for line in rows.splitlines())
}
def indexes(self) -> list[str]:
def indexes(self, container: str = DB) -> list[str]:
"""Определения индексов messages: до и после этапов с вариантами."""
return self.psql(
"SELECT indexdef FROM pg_indexes WHERE tablename = 'messages' "
"ORDER BY indexname;\n",
container=container,
).splitlines()
def message_count(self) -> int:
@@ -1038,13 +1170,8 @@ class Stand:
"db_usec": number(r"^usage_usec (\d+)$", db),
}
def k6(
self,
script: str,
env: dict[str, Any],
*,
check: bool = True,
) -> subprocess.CompletedProcess[str]:
def k6_args(self, script: str, env: dict[str, Any]) -> list[str]:
"""Команда `k6 run` сценария в контейнере k6 стенда."""
common = {
"TEXT_LENGTH": self.profile.text_length,
"PAGE_LIMIT": self.profile.page_limit,
@@ -1054,20 +1181,29 @@ class Stand:
for key, value in {**common, **env}.items()
for item in ("-e", f"{key}={value}")
]
return [
"docker",
"exec",
K6,
"k6",
"run",
"--quiet",
"--no-color",
"--log-format",
"raw",
*flags,
f"/scripts/{script}",
]
def k6(
self,
script: str,
env: dict[str, Any],
*,
check: bool = True,
) -> subprocess.CompletedProcess[str]:
proc = subprocess.run(
[
"docker",
"exec",
K6,
"k6",
"run",
"--quiet",
"--no-color",
"--log-format",
"raw",
*flags,
f"/scripts/{script}",
],
self.k6_args(script, env),
capture_output=True,
text=True,
check=False,
@@ -1076,6 +1212,99 @@ class Stand:
raise BenchError(k6_failure(script, proc))
return proc
def k6_start(self, script: str, env: dict[str, Any]) -> subprocess.Popen:
"""Сценарий k6 в фоне: запись во время backup."""
return subprocess.Popen(
self.k6_args(script, env),
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
)
def pg_dump(self, path: Path) -> None:
"""Логический backup исходной базы (формат custom) в файл хоста."""
with path.open("wb") as file:
proc = subprocess.run(
[
"docker",
"exec",
DB,
"sh",
"-c",
'exec pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc',
],
stdout=file,
stderr=subprocess.PIPE,
check=False,
)
if proc.returncode != 0:
raise BenchError(f"pg_dump: exit {proc.returncode}\n{proc.stderr}")
def pg_restore(self, path: Path) -> tuple[float, float]:
"""Backup в хранилище восстановления: копия файла и pg_restore -j.
Возвращает секунды копирования и восстановления.
"""
started = time.monotonic()
sh("docker", "cp", str(path), f"{RESTORE_DB}:/tmp/backup.dump")
copied = time.monotonic()
proc = subprocess.run(
[
"docker",
"exec",
RESTORE_DB,
"sh",
"-c",
'exec pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" '
f"-j {self.profile.restore_jobs} --no-owner --no-privileges "
"--exit-on-error /tmp/backup.dump",
],
capture_output=True,
text=True,
check=False,
)
if proc.returncode != 0:
raise BenchError(
f"pg_restore: exit {proc.returncode}\n{proc.stderr}",
)
return copied - started, time.monotonic() - copied
def switch_api(self, host: str) -> None:
"""API заново, с адресом базы `host`: `POSTGRES_HOST` перекрывает
значение из `bench/bench.env` для `x-app-env`."""
env = self.env
self.env = {**env, "POSTGRES_HOST": host}
try:
self.compose("up", "-d", "--no-deps", "--force-recreate", "api")
finally:
self.env = env
self.wait_ready()
def table_counts(self, container: str = DB) -> dict[str, int]:
"""Число строк таблиц данных (сверка восстановления)."""
sql = " UNION ALL ".join(
f"SELECT '{table}', count(*) FROM {table}" for table in DATA_TABLES
)
rows = self.psql(f"{sql};\n", container=container)
return {
table: int(count)
for table, count in (line.split("|") for line in rows.splitlines())
}
def message_rows(self, container: str = DB) -> dict[str, tuple[str, str]]:
"""Сообщения базы: id → (chat_id, md5 всех полей)."""
rows = self.psql(
"SELECT id, chat_id, md5(concat_ws('|', chat_id, sender_id, "
"text, created_at)) FROM messages;\n",
container=container,
)
return {
message: (chat, digest)
for message, chat, digest in (
line.split("|") for line in rows.splitlines()
)
}
def work_json(self, name: str) -> Any:
return json.loads((self.work_dir / name).read_text(encoding="utf-8"))
@@ -1588,6 +1817,46 @@ def build_summary(
f"{cell(row['fpi_per_1000'], 1)} | {row['long_text']} |",
)
lines.append("")
restores = [info for info in sizes if info.get("restore")]
if restores:
lines += [
"## Backup и восстановление",
"",
"`pg_dump -Fc` исходной базы во время записи через HTTP, "
"затем активность после backup (пользователь, сессия, чат, "
"сообщение), `pg_restore -j` в новый контейнер PostgreSQL "
"на новом volume, `ANALYZE`, сверка обеих баз (число строк, "
"md5 каждого сообщения, индексы, ревизия схемы), "
"переключение API и проверки через HTTP до и после "
"`FLUSHALL`. RTO — от запуска нового хранилища до "
"готовности API, без сверки. Сверка прошла на каждом "
"размере: иначе команда завершилась бы ошибкой.",
"",
"| Размер | До backup | Исходная в конце | Восстановлено | "
"Потеряно | Записей во время backup (в backup) | Backup, МиБ | "
"Байт backup на сообщение | dump, с | restore, с | "
"ANALYZE, с | API, с | RTO, с | Сверка, с | Чат после "
"backup: GET / POST до FLUSHALL, GET после | Сессия после "
"backup |",
"|---|---|---|---|---|---|---|---|---|---|---|---|---|---|"
"---|---|",
]
for info in restores:
r = info["restore"]
lines.append(
f"| {human(info['size'])} | {r['messages_before_backup']} "
f"| {r['messages_source_end']} | {r['messages_restored']} "
f"| {r['messages_lost']} | {r['load_written']} "
f"({r['load_in_backup']}) | "
f"{mib_bytes(r['backup_bytes'])} | "
f"{r['backup_bytes_per_message']} | {r['dump_seconds']} | "
f"{r['restore_seconds']} | {r['analyze_seconds']} | "
f"{r['api_ready_seconds']} | {r['rto_seconds']} | "
f"{r['verify_seconds']} | {r['stale_chat_get']} / "
f"{r['stale_chat_post']}, {r['flushed_chat_get']} | "
f"{r['late_session']} |",
)
lines.append("")
if prefill:
largest = max(r["size"] for r in prefill)
curve = [r for r in prefill if r["size"] == largest]
@@ -1662,8 +1931,9 @@ class Bench:
current = index == self.done_sizes
if index < self.done_sizes:
continue
# пробы записи в конце размера: сборка индексов и вставки
left += 60
# пробы записи в конце размера: сборка индексов и вставки;
# backup, восстановление и сверка
left += 60 + (30 if p.restore else 0)
if current and self.prepared:
continue
filled = self.prefilled if current else 0
@@ -1828,6 +2098,11 @@ class Bench:
self.progress()
info["write_cost"] = self.write_cost(size)
self.results.write_meta()
if self.profile.restore:
self.stage = f"size {name}: backup and restore"
self.progress()
info["restore"] = self.backup_restore(size, fixture, store)
self.results.write_meta()
if not stand.stop():
raise BenchError(f"stand of size {name} was not removed")
@@ -2206,6 +2481,201 @@ class Bench:
)
return result
def backup_restore(
self,
size: int,
fixture: dict[str, Any],
store: int,
) -> dict[str, Any]:
"""Backup под записью, восстановление в новое хранилище, сверка.
Порядок и проверки — решения 2–5 design change
`track2-backup-restore`. Расхождение — BenchError с размером;
хранилище восстановления убирает `Stand.stop()`.
"""
stand = self.stand
p = self.profile
name = human(size)
rows_before = stand.message_rows()
counts_before = stand.table_counts()
# запись через HTTP во время backup: dump начинается, когда она идёт
load = stand.k6_start(
"write.js",
{
"VUS": p.restore_write_vus,
"COUNT": p.restore_write_load,
"OFFSET": store,
},
)
dump = stand.work_dir / "backup.dump"
try:
deadline = time.monotonic() + 30
while stand.message_count() <= counts_before["messages"]:
if load.poll() is not None or time.monotonic() > deadline:
raise BenchError(
f"size {name}: write load did not start before backup",
)
time.sleep(0.05)
started = time.monotonic()
stand.pg_dump(dump)
dump_seconds = time.monotonic() - started
at_dump_end = stand.message_count()
finally:
out, err = load.communicate()
if load.returncode != 0:
raise BenchError(
k6_failure(
"write.js",
subprocess.CompletedProcess([], load.returncode, out, err),
),
)
written = parse_summary(stand.work_dir / "last.json")
dump_bytes = dump.stat().st_size
counts_loaded = stand.table_counts()
self.say(
f"size {name}: backup {mib_bytes(dump_bytes)} MiB in "
f"{dump_seconds:.2f}s during {written['requests_ok']} writes "
f"({written['requests_failed']} failed)",
)
stand.k6("restore_check.js", {"PHASE": "source"})
source_check = stand.work_json("check-source.json")
stand.k6("after_backup.js", {})
after = stand.work_json("after.json")
rows_source = stand.message_rows()
# восстановление: RTO — от запуска нового хранилища до готовности API
started = time.monotonic()
stand.start_restore()
storage_seconds = time.monotonic() - started
copy_seconds, restore_seconds = stand.pg_restore(dump)
mark = time.monotonic()
stand.psql("ANALYZE;\n", container=RESTORE_DB)
analyze_seconds = time.monotonic() - mark
db_seconds = time.monotonic() - started
mark = time.monotonic()
rows_restored = stand.message_rows(container=RESTORE_DB)
counts_restored = stand.table_counts(container=RESTORE_DB)
problems = []
mismatched = sum(
1
for message, row in rows_restored.items()
if rows_source.get(message) != row
)
if mismatched:
problems.append(f"{mismatched} restored messages differ")
missing_before = len(rows_before.keys() - rows_restored.keys())
if missing_before:
problems.append(
f"{missing_before} messages from before backup lost",
)
lost = rows_source.keys() - rows_restored.keys()
allowed = {fixture["writeChatId"], after["chatId"]}
foreign = sum(1 for m in lost if rows_source[m][0] not in allowed)
if foreign:
problems.append(f"{foreign} lost messages outside written chats")
for table in DATA_TABLES[:-1]:
if counts_restored[table] != counts_loaded[table]:
problems.append(
f"{table}: {counts_restored[table]} restored, "
f"{counts_loaded[table]} at backup",
)
if stand.indexes(container=RESTORE_DB) != stand.indexes():
problems.append("messages indexes differ")
version = "SELECT version_num FROM alembic_version;\n"
if stand.psql(version, container=RESTORE_DB) != stand.psql(version):
problems.append("alembic revision differs")
verify_seconds = time.monotonic() - mark
mark = time.monotonic()
stand.switch_api(RESTORE_HOST)
api_seconds = time.monotonic() - mark
stand.k6("restore_check.js", {"PHASE": "stale"})
stale = stand.work_json("check-stale.json")
sh(
"docker",
"exec",
CACHE,
"sh",
"-c",
'exec valkey-cli -p "$VALKEY_PORT" FLUSHALL',
)
stand.k6("restore_check.js", {"PHASE": "restored"})
restored = stand.work_json("check-restored.json")
for phase, check in (
("source", source_check),
("stale", stale),
("restored", restored),
):
if check["reader_me"] != 200:
problems.append(
f"{phase}: reader session {check['reader_me']}",
)
if stale["late_me"] != 401:
problems.append(f"session after backup: {stale['late_me']}")
if restored["after_chat_get"] != 404:
problems.append(
f"chat after backup after FLUSHALL: {restored['after_chat_get']}",
)
for phase, check in (("stale", stale), ("restored", restored)):
differ = [
f"{a['chat']} {a['page']}"
for a, b in zip(
check["pages"],
source_check["pages"],
strict=True,
)
if a["status"] != 200 or a["items"] != b["items"]
]
if differ:
problems.append(f"{phase}: pages differ: {', '.join(differ)}")
if problems:
raise BenchError(
f"size {name}: restore check failed: {'; '.join(problems)}",
)
result = {
"messages_before_backup": counts_before["messages"],
"messages_at_dump_end": at_dump_end,
"messages_source_end": len(rows_source),
"messages_restored": len(rows_restored),
"messages_lost": len(lost),
"lost_after_backup_chat": sum(
1 for m in lost if rows_source[m][0] == after["chatId"]
),
"load_written": written["requests_ok"],
"load_failed": written["requests_failed"],
"load_in_backup": len(rows_restored) - counts_before["messages"],
"tables_restored": counts_restored,
"backup_bytes": dump_bytes,
"backup_bytes_per_message": round(
dump_bytes / len(rows_restored),
1,
),
"dump_seconds": round(dump_seconds, 2),
"storage_seconds": round(storage_seconds, 2),
"copy_seconds": round(copy_seconds, 2),
"restore_seconds": round(restore_seconds, 2),
"analyze_seconds": round(analyze_seconds, 2),
"verify_seconds": round(verify_seconds, 2),
"api_ready_seconds": round(api_seconds, 2),
"rto_seconds": round(db_seconds + api_seconds, 2),
"pages_checked": len(source_check["pages"]),
"stale_chat_get": stale["after_chat_get"],
"stale_chat_post": stale["after_chat_post"],
"flushed_chat_get": restored["after_chat_get"],
"late_session": stale["late_me"],
}
self.say(
f"size {name}: restored {len(rows_restored)} of "
f"{len(rows_source)} messages ({len(lost)} lost after the "
f"snapshot), restore {restore_seconds:.2f}s, ANALYZE "
f"{analyze_seconds:.2f}s, API {api_seconds:.2f}s, RTO "
f"{result['rto_seconds']}s; stale chat GET "
f"{result['stale_chat_get']} POST {result['stale_chat_post']}, "
f"after FLUSHALL {result['flushed_chat_get']}",
)
return result
def run_prefill(self, size: int, total: int) -> float:
"""Наполнение всех чатов размера по расписанию, порциями."""
chunk_size = self.profile.prefill_chunk
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-02
@@ -0,0 +1,269 @@
# Design
## Context
Зачем — `proposal.md`, требования — дельта `load-benchmark`. Что есть
сейчас (archived changes `bench-postgres`, `track2-query-plans`):
- `bench/run.py` на каждый размер поднимает свежий проект compose
`mtusi-bench`: Postgres, Valkey, миграции, API, k6 в той же сети.
Наполнение — читаемый чат N и 1 110 фоновых чатов, ≥110 000 сообщений.
Дальше:
- обслуживание БД;
- планы;
- матрица `read` / `write`;
- пробы записи;
- уборка.
- Методика — поля `Profile`. Профили — `full` и `quick`.
- API берёт адрес базы из `DATABASE__HOST: ${POSTGRES_HOST:-postgres}`
(`docker-compose.yml`, якорь `x-app-env`). `POSTGRES_HOST` для стенда
задаёт `bench/bench.env`, а окружение процесса `docker compose` его
перекрывает.
- Valkey хранит карточки чатов без инвалидации (`chat-cache`).
Карточка нового чата пишется после commit.
- Пароль Postgres стенда генерирует `compose_env()` на прогон, он живёт
только в окружении процесса `docker compose`.
- Проба на закреплённом образе `postgres:18.6-trixie`, 600 000 строк с
индексом `(chat_id, created_at, id)`:
- `pg_dump -Fc` — 0,95 с и 19,9 МБ;
- `docker cp` в новый контейнер с новым volume;
- `pg_restore -j 4 --no-owner --no-privileges --exit-on-error` —
1,15 с, индексы восстановлены;
- `docker run --env POSTGRES_PASSWORD` без значения берёт пароль из
окружения процесса docker CLI, в командную строку он не попадает.
## Goals / Non-Goals
**Goals:**
- Одна команда даёт всё для второй части трека 2 на тех же данных, что
первая: backup, восстановление в новое хранилище, сверку, время по
размерам, границу потери и поведение кэша.
- Сверка доказывает, что восстановленная база — точная копия исходной
на момент снимка. Это проверяется построчно, а не только числом строк.
**Non-Goals:**
- Физический backup (`pg_basebackup`) и PITR с архивацией WAL. Они
обсуждаются в отчёте как способ сузить RPO, но не реализуются.
- Процедура восстановления рабочего стенда (`mtusi-lab2`) отдельными
целями Makefile. Стенд `bench` выполняет те же команды на
синтетических данных. Рабочий стенд не трогается.
- Изменения `src/`: сервис не знает о восстановлении, а очистка кэша —
шаг процедуры.
- Матрица прогонов на восстановленной базе.
## Decisions
### 1. Профили `restore` и `restore_quick`
Новые поля `Profile`:
| Поле | По умолчанию | Зачем |
|---|---|---|
| `restore` | `False` | этап backup и восстановления в конце размера |
| `restore_jobs` | 4 | `pg_restore -j`: параллельная загрузка и сборка индексов, у Postgres стенда 4 CPU |
| `restore_write_load` | 5 000 | сообщений через HTTP во время backup |
| `restore_write_vus` | 10 | клиентов этой записи |
- `restore` — размеры 10k / 100k / 500k и фоновые чаты, как у `full`;
`concurrency=()`, поэтому матрицы прогонов нет. Планы и пробы записи
идут как обычно: одна функция `run_size`, без новых ветвлений. Это
~1 минута на размер.
- `restore_quick` — размеры и фон `quick`, `restore_write_load` = 1 000.
Поля пишутся в `meta.json`. Метки `restore` и `full` несравнимы:
`make bench_compare` откажет по профилю, и так и должно быть.
Цели `Makefile`:
- `bench_restore` — `--profile restore --label $(RESTORE_LABEL)`,
`RESTORE_LABEL ?= restore`;
- `bench_restore_quick` — метка `quick-restore-<время>`, она попадает
под `.gitignore` `quick-*`.
**Альтернатива** — отдельный скрипт со своим наполнением. Тогда
пришлось бы дублировать стенд, наполнение по расписанию и проверку
распределения. Этап внутри `run.py` получает их даром и те же данные,
что у части 1.
### 2. Backup под нагрузкой и активность после него
Порядок в конце размера, после проб записи:
1. `ids_before` — все `id` сообщений и число строк каждой таблицы
исходной базы.
2. Запись: `k6 write.js` (`VUS=restore_write_vus`,
`COUNT=restore_write_load`) запускается в фоне (`subprocess.Popen`).
Оркестратор ждёт, пока число сообщений вырастет: запись идёт до
начала dump, а не после.
3. `pg_dump -U … -d … -Fc` в контейнере исходного Postgres. stdout
пишется в `.work/backup.dump`, время и размер замеряются.
4. Ожидание записи. k6 должен завершиться с кодом 0, без ошибок, с
`requests_ok = COUNT`: backup не мешает писать.
5. Число строк таблиц исходной базы после нагрузки.
6. `restore_check.js` `PHASE=source`: выбранные страницы истории
исходной базы через HTTP — это страницы этапа плана
(`plan_pages.json`) и `/users/me` читателя.
7. `after_backup.js`:
- регистрация пользователя и вход по Basic;
- чат «после backup» из этого пользователя и читателя;
- одно сообщение в нём.
В `.work/after.json` — id пользователя, его токен, id чата.
`pg_dump` берёт снимок на старте. Сообщения, закоммиченные после
снимка, в backup не попадают — это и есть граница потери.
### 3. Восстановление в новое хранилище
`Stand.start_restore()` запускает контейнер `docker run`, а не сервисом
compose:
- образ — `Config.Image` исходного контейнера: тот же пин без копии в
коде;
- `--network mtusi-bench`, `--network-alias postgres-restore`;
- `POSTGRES_USER` и `POSTGRES_DB` — из окружения исходного контейнера,
`--env POSTGRES_PASSWORD` — из окружения процесса, без значения в
командной строке;
- лимиты `db_cpus` / `db_memory`, swap = память;
- новый volume `mtusi-bench_restore`;
- метка `com.docker.compose.project=mtusi-bench` у контейнера и
volume: `leftovers()` их увидит.
Сервис в override compose не делается: `extends` между файлами compose
ненадёжен, а копия пина образа разошлась бы с `docker-compose.yml`.
Шаги и время. Отсчёт RTO — от `docker run`:
1. ожидание `pg_isready`;
2. `docker cp` backup в контейнер;
3. `pg_restore -j restore_jobs --no-owner --no-privileges
--exit-on-error` — `restore_seconds`;
4. `ANALYZE`: после restore статистики нет, без неё планы хуже —
`analyze_seconds`;
5. сверка БД (решение 4) — `verify_seconds`, в RTO не входит: в живой
процедуре её можно делать параллельно с работой;
6. переключение API: `docker compose up -d --no-deps --force-recreate
api` с `POSTGRES_HOST=postgres-restore` в окружении процесса
compose, ожидание `/health/ready` — `api_ready_seconds`;
7. RTO = время от `docker run` до готовности API без `verify_seconds`.
`Stand.stop()` удаляет контейнер восстановления и его volume до `compose
down`: иначе сеть не удалится. Файл `.work/backup.dump` удаляется вместе
с `.work/`, а копия в контейнере — вместе с контейнером.
### 4. Сверка в БД
Обе базы через `docker exec … psql` (SQL через stdin):
- **Число строк** `users`, `chats`, `chat_members`, `sessions` в
восстановленной базе равно исходному после нагрузки (шаг 5 решения
2). Нагрузка пишет только сообщения, а активность шага 7 идёт после.
- **Сообщения:** `SELECT id, chat_id, md5(concat_ws('|', chat_id,
sender_id, text, created_at))` в обеих базах:
- каждое восстановленное есть в исходной с тем же хэшем
(`mismatched = 0`);
- `ids_before ⊆ восстановленные`: всё, что было до backup, на месте;
- потерянные (`исходные − восстановленные`) не пересекаются с
`ids_before` и лежат только в чате записи или в чате «после backup».
- **Схема:** определения индексов (`pg_indexes`) и `alembic_version`
совпадают.
Любое расхождение — `BenchError` с размером, стенд и второе хранилище
убираются. 600 000 строк по ~70 байт — около 40 МБ вывода на базу,
сравнение в памяти оркестратора.
### 5. Проверки через HTTP и кэш
`restore_check.js` выполняет запросы в `setup()`. Итог — статусы и
элементы страниц — пишется в `.work/check-<phase>.json`, без токенов.
| Фаза | Когда | Что |
|---|---|---|
| `source` | до восстановления | страницы плана; `/users/me` читателя |
| `stale` | API на восстановленной базе, до `FLUSHALL` | `/users/me` читателя и пользователя «после backup»; `GET` чата «после backup» и `POST` сообщения в него; страницы плана |
| `restored` | после `FLUSHALL` | `GET` чата «после backup»; страницы плана |
Обязательно, иначе `BenchError`:
- читатель — 200;
- пользователь «после backup» — 401;
- после `FLUSHALL` чат «после backup» — 404;
- страницы плана в `stale` и `restored` поэлементно равны `source`.
Ответы на чат «после backup» до `FLUSHALL` (`GET` и `POST`)
записываются как есть: это измерение вреда устаревшего кэша, а не
условие прохождения. `FLUSHALL` — `docker exec mtusi-bench-valkey
valkey-cli FLUSHALL`, пароль из `VALKEYCLI_AUTH` контейнера.
### 6. Сводка и паспорт
`meta.sizes[].restore` — все величины решений 2–5. В `summary.md`
раздел «Backup и восстановление»:
- размер;
- сообщений до backup, в исходной в конце, восстановлено, потеряно;
- backup МиБ и байт на сообщение;
- время dump, restore, `ANALYZE`, готовности API, RTO;
- ответы на чат «после backup» до и после `FLUSHALL`;
- результат сверки.
Строка этапа печатается в вывод с временем, как другие этапы.
### 7. Граница чёрного ящика
Исключения для хранилищ стенда (`bench.md`, «Как писать») пополняются:
- `pg_dump` исходной базы;
- второе хранилище, `pg_restore` и `ANALYZE` в нём;
- построчная сверка обеих баз;
- `FLUSHALL` Valkey стенда;
- пересоздание API с другим адресом базы.
Приложение по-прежнему видит только HTTP от k6 и свою базу.
### 8. Гипотезы
Гипотезы записываются в `REPORT.md` до `make bench_restore`, по
`bench_restore_quick` и пробе (Context):
- **R1.** Backup не мешает записи: нагрузка во время `pg_dump` проходит
без ошибок.
- **R2.** Всё, что закоммичено до начала backup, восстанавливается без
изменений. Теряются только сообщения, закоммиченные после снимка, и
активность после backup.
- **R3.** Время восстановления растёт примерно линейно с данными. На
600 000 сообщений RTO меньше 30 с.
- **R4.** Backup в формате custom (сжатый, без индексов) меньше, чем
база занимает на диске. На сообщение — меньше трети от байт в БД.
- **R5.** Без `FLUSHALL` чат, созданный после backup, отдаётся из кэша
(200), а запись в него падает с 500. После `FLUSHALL` — 404.
Пороги уточняются по `bench_restore_quick` до записи.
## Risks / Trade-offs
- [Dump закончится раньше, чем начнётся запись, и граница потери не
проверится] → ожидание роста числа сообщений перед `pg_dump`. Отчёт
называет, сколько сообщений записано до снимка и после.
- [Сравнение `created_at` текстом зависит от `TimeZone`] → оба
контейнера из одного образа с одной настройкой. Расхождение дало бы
массовый `mismatched`, а не тихую ошибку.
- [Вывод сверки на 600 000 строк — десятки МБ через `docker exec`] →
секунды, в RTO не входит.
- [`POST` в устаревший чат даёт 500 и `error` в журнале API стенда] →
это стенд и это часть измерения. В рабочем журнале этого нет.
- [Второй Postgres с теми же лимитами: 4 + 4 CPU, 3 + 3 ГБ в VM 7,75
ГиБ] → лимиты памяти стенда с ним — 2 + 3 + 3 + 0,5 = 8,5 ГБ, больше
VM. Но исходный Postgres во время восстановления простаивает: его
кэш занят, рабочий набор — нет. Риск OOM виден по сторожу и пометкам.
Предупреждение о VM проверяет только основные лимиты, это записано в
ограничениях отчёта.
- [Логический backup не даёт PITR] → граница потери — момент снимка.
Сужение RPO (WAL-архив, `pg_receivewal`, физическая реплика) — в
обсуждении, не в реализации.
## Migration Plan
Развёртывания нет. Порядок — `tasks.md`:
1. код и `make bench_restore_quick`;
2. коммит;
3. гипотезы, коммит;
4. `make bench_restore`;
5. коммит доказательств;
6. отчёт.
Откат — `git revert`. Рабочий стенд не затрагивается.
@@ -0,0 +1,84 @@
# Proposal
## Why
Вторая часть трека «5» №2 (`README.md`):
- backup → восстановление в новое хранилище → сверка количества и
выбранных сообщений;
- обсуждение времени восстановления и границ потери данных.
Первая часть (`track2-query-plans`) готова, а без второй трек не
закончен. Есть и долг из `membership-cache`. Карточки чатов в Valkey
не инвалидируются: по контракту чат не меняется. Восстановление базы
из backup это допущение ломает. В кэше остаются карточки чатов,
созданных после снятия backup, и сервис отвечает на них из кэша, хотя
в базе их нет. Требование `chat-cache` «кэш MUST NOT содержать
карточку, которой нет в PostgreSQL» нарушается. Процедура
восстановления обязана очищать кэш, и это нужно показать, а не только
записать.
## What Changes
- **Этап «backup и восстановление» стенда `make bench`.** Включается
профилем. В конце каждого размера, на тех же данных (≥110 000
сообщений в чатах разного размера):
- backup `pg_dump` в формате custom, во время непрерывной записи
через HTTP;
- активность после backup: новый пользователь со своей сессией, новый
чат и сообщение в нём;
- восстановление `pg_restore` в новое хранилище: новый контейнер
PostgreSQL с новым volume, тот же образ и лимиты;
- сверка в БД:
- число строк каждой таблицы;
- каждое восстановленное сообщение совпадает с исходным по
контрольной сумме;
- потерянные сообщения — только записанные после начала backup;
- переключение API на восстановленную базу и сверка через HTTP:
- выбранные страницы истории совпадают с исходными;
- прежняя сессия действует, сессия после backup — 401;
- граница кэша:
- до `FLUSHALL` чат, созданный после backup, отдаётся из кэша;
- после `FLUSHALL` — 404.
- **Метрики восстановления** в сводке и паспорте:
- время и размер backup;
- время восстановления, `ANALYZE` и готовности API;
- время от начала восстановления до готовности API (RTO);
- число потерянных сообщений и что именно потеряно (RPO).
- **Команды** `make bench_restore` (профиль `restore`: 10k / 100k /
500k, без матрицы прогонов) и `make bench_restore_quick` (самопроверка
и сценарий защиты, ~2 мин).
- **Отчёт.** Трек 2, часть 2:
- гипотезы до замера, процедура восстановления, результаты метки
`restore`;
- время восстановления и границы потери данных;
- ограничения: логический backup без архивации WAL, один хост.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
- `load-benchmark`: новые требования — этап backup и восстановления с
проверками и метриками, команды запуска, восстановление в отчёте.
## Impact
- **Код стенда:**
- `bench/run.py`: профили `restore` и `restore_quick`, этап
восстановления, второй контейнер PostgreSQL и его уборка,
переключение API, сверка, сводка;
- `bench/k6/`: `after_backup.js` (активность после backup),
`restore_check.js` (проверки через HTTP);
- `Makefile`: цели `bench_restore`, `bench_restore_quick`.
- **Код приложения (`src/`), миграции, контракт, тесты** не меняются.
- **Документация:** `.claude/rules/bench.md` (граница чёрного ящика:
`pg_dump`, `pg_restore`, `FLUSHALL` стенда), `AGENTS.md` (команды,
карта кода, переходное состояние), `REPORT.md`.
- **Доказательства:** `evidence/bench/restore/`. Сам backup в результаты
не попадает: в нём хэши паролей и токенов. Он живёт в `.work/` и
удаляется в конце прогона.
- **Время хоста:** `make bench_restore` ~20 минут: наполнение 910 000
сообщений и три восстановления.
@@ -0,0 +1,101 @@
## ADDED Requirements
### Requirement: Backup и восстановление в новое хранилище
Профиль методики SHALL включать этап backup и восстановления. Команда
`make bench_restore` (метка `RESTORE_LABEL`, по умолчанию `restore`)
SHALL запускать его на размерах 10 000, 100 000 и 500 000 с фоновыми
чатами полной матрицы, без измеряемых прогонов. Команда `make
bench_restore_quick` — то же на малых размерах, метка `quick-…`.
На каждом размере, после наполнения и планов, стенд SHALL по порядку:
1. снять логический backup базы стенда, пока через HTTP API идёт запись
сообщений;
2. после backup через HTTP создать пользователя с сессией, чат с
ним и сообщение в этом чате;
3. восстановить backup в новое хранилище: новый контейнер PostgreSQL
того же образа и с теми же лимитами, на новом volume;
4. сверить базы:
- число строк каждой таблицы, кроме сообщений, совпадает с
исходной базой до активности шага 2;
- каждое сообщение восстановленной базы есть в исходной с теми же
полями;
- сообщений восстановлено не меньше, чем было до начала backup;
- каждое потерянное сообщение записано после начала backup;
- индексы и ревизия схемы совпадают;
5. переключить API на восстановленную базу и через HTTP проверить:
- выбранные страницы истории совпадают с исходными;
- прежняя сессия действует;
- сессия, созданная после backup, — 401;
- запрос чата, созданного после backup, до очистки кэша — записать
ответ;
6. очистить кэш и убедиться, что чат, созданный после backup, — 404.
Любое расхождение в шагах 4–6 SHALL завершать команду с ненулевым
кодом, называя размер и расхождение. Второе хранилище и его volume
SHALL удаляться вместе со стендом, в том числе при ошибке и по Ctrl+C.
Файл backup MUST NOT попадать в каталог метки.
Для каждого размера SHALL сохраняться:
- время и размер backup, байты backup на сообщение;
- время восстановления, сбора статистики и готовности API на
восстановленной базе;
- время от начала восстановления до готовности API;
- число сообщений до backup, в исходной базе в конце и в
восстановленной, число потерянных;
- результаты проверок шагов 4–6, включая ответ на чат из кэша до
очистки.
#### Scenario: Восстановление сходится
- **WHEN** выполняется `make bench_restore`
- **THEN** на каждом размере сверка шагов 4–6 проходит, код выхода 0, в
сводке — таблица восстановления
#### Scenario: Потеря ограничена началом backup
- **WHEN** во время backup и после него через API записаны сообщения
- **THEN** в восстановленной базе нет только части этих сообщений и
сущностей шага 2, а всё, что было до начала backup, восстановлено без
изменений
#### Scenario: Кэш после восстановления
- **WHEN** API переключён на восстановленную базу
- **THEN** до очистки кэша записан ответ на чат, созданный после
backup, а после очистки — 404
#### Scenario: Расхождение
- **WHEN** у восстановленной базы отличается число строк таблицы или
поля сообщения
- **THEN** команда завершается с ненулевым кодом, называет размер и
расхождение, оба хранилища удалены
#### Scenario: Backup не в результатах
- **WHEN** прогон завершён, в том числе с ошибкой
- **THEN** в каталоге метки нет файла backup, а в `.work/` его тоже нет
### Requirement: Восстановление в отчёте
Результат `make bench_restore` SHALL быть сохранён под меткой
`restore`. Гипотезы SHALL быть записаны в `REPORT.md` до её запуска.
`REPORT.md` SHALL описывать в треке 2:
- процедуру backup и восстановления по шагам, включая очистку кэша;
- сверку: что сравнивается и с каким результатом;
- время backup и восстановления по размерам, RTO;
- границу потери данных (RPO): что теряется при логическом backup и
чем её можно сузить;
- итог по гипотезам, как получился;
- ограничения.
Числа SHALL переноситься из файлов метки, со ссылкой на них.
#### Scenario: Проверяющий ищет восстановление
- **WHEN** проверяющий открывает трек 2 в `REPORT.md`
- **THEN** он находит backup, восстановление в новое хранилище, сверку
количества и выбранных сообщений на ≥100 000 сообщениях, время
восстановления и границы потери данных со ссылками на метку
`restore`
@@ -0,0 +1,95 @@
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться —
дельта `specs/load-benchmark/spec.md`. Правило слоя — `bench.md`. Замер
для отчёта — с закоммиченного кода. Код приложения, миграции, контракт и
`student-tests/` не меняются. Рабочий стенд (`mtusi-lab2`) не трогать.
## 1. Профили и команды
- [x] 1.1 Поля `Profile` (`restore`, `restore_jobs`,
`restore_write_load`, `restore_write_vus`), профили `restore` и
`restore_quick` (решение 1), цели `bench_restore` и
`bench_restore_quick` в `Makefile`. Проверка: `make -n bench_restore
bench_restore_quick` печатает команды, `uv run python -c` с импортом
`run.py` показывает у `restore` пустую `concurrency` и фон `full`.
## 2. Второе хранилище
- [x] 2.1 `Stand.start_restore()` и уборка в `Stand.stop()` (решение 3):
- образ исходного контейнера, сеть и алиас;
- пароль через `--env` без значения;
- лимиты, volume и метка проекта.
Проверка: на коротком прогоне `docker inspect` контейнера
восстановления показывает лимиты 4 CPU / 3 ГБ и метку проекта, а
`ps` хоста — `docker run` без пароля в аргументах. После прогона и
после Ctrl+C посреди этапа нет контейнеров и volume `mtusi-bench*`.
## 3. Этап backup и восстановления
- [x] 3.1 `after_backup.js` и `restore_check.js` с фазами `source`,
`stale`, `restored` (решения 2, 5). Итоги — в `.work/`, без токенов.
Проверка: `grep` значений токенов из `.work/` по каталогу метки
пуст.
- [x] 3.2 Этап в `run.py` (решения 2–5):
- `ids_before` и число строк;
- запись в фоне, `pg_dump` после начала записи;
- активность после backup;
- восстановление со временем шагов;
- сверка БД;
- переключение API;
- проверки HTTP до и после `FLUSHALL`.
Расхождение — `BenchError` с размером. Проверка на коротком прогоне:
- потерянные сообщения > 0 и только из чата записи и чата «после
backup»;
- `mismatched` = 0;
- сессия «после backup» — 401, после `FLUSHALL` — 404;
- временно испорченное ожидание числа строк (правка, не коммитить) —
отказ с размером, оба хранилища убраны.
- [x] 3.3 `meta.sizes[].restore` и раздел «Backup и восстановление» в
`summary.md` (решение 6). Проверка: раздел короткого прогона
заполнен по всем размерам.
## 4. Проверка и коммит кода
- [x] 4.1 `make lint` без замечаний. `make bench_quick --dry-run`
(`make -n bench_quick`) печатает команду: профили `full` и `quick`
этап восстановления не включают.
- [x] 4.2 `make bench_restore_quick` целиком: код 0, сверка проходит на
всех размерах, файла backup нет ни в каталоге метки, ни в `.work/`.
Записать время прогона.
- [x] 4.3 `.claude/rules/bench.md`: этап восстановления в «Что не
меняется» и новые исключения границы чёрного ящика (решение 7).
`AGENTS.md`: команды `bench_restore*`, карта кода (`after_backup.js`,
`restore_check.js`). Проверка: `grep -n "bench_restore"
AGENTS.md` находит строки.
- [x] 4.4 Закоммитить (`feat: add backup and restore stage to bench`).
Проверка: `git status` чистый.
## 5. Замер и отчёт
- [ ] 5.1 Записать в `REPORT.md` гипотезы R1–R5 (решение 8) до замера
и закоммитить (`docs: record track 2 backup and restore hypotheses`).
- [ ] 5.2 Подготовить хост и запустить `make bench_restore`. Проверка:
- код 0, `status: complete`, `dirty: false`, без `host_warnings`;
- сверка прошла на 10k, 100k и 500k.
- [ ] 5.3 Закоммитить `evidence/bench/restore/` (`docs: add track 2
backup and restore evidence`).
- [ ] 5.4 `REPORT.md`, трек 2, часть 2:
- процедура восстановления по шагам, включая `FLUSHALL`;
- сверка;
- время по размерам и RTO;
- RPO и способы его сузить;
- итог по R1–R5;
- ограничения.
Строка «Трек 5 №2, часть 2» в таблице доказательств и сценарий защиты
(`make bench_restore_quick`). В разделе «Кэш Valkey» — ссылка на
результат. В `AGENTS.md` закрыть «Переходное состояние» трека 2 и
пункт `FLUSHALL`. Проверка: каждое число есть в `summary.md` или
`meta.json` метки `restore`.
- [ ] 5.5 Закоммитить отчёт (`docs: report track 2 backup and
restore`). `openspec validate track2-backup-restore --strict`
проходит, `git status` чистый.