diff --git a/openspec/changes/scaling-bench/specs/data-storage/spec.md b/openspec/changes/scaling-bench/specs/data-storage/spec.md
new file mode 100644
index 00000000..5171a5ba
--- /dev/null
+++ b/openspec/changes/scaling-bench/specs/data-storage/spec.md
@@ -0,0 +1,33 @@
+# Spec Delta
+
+## MODIFIED Requirements
+
+### Requirement: Недоступность PostgreSQL
+
+Если PostgreSQL недоступен, отказывает в новом подключении из-за
+предела соединений (`max_connections`) или не ответил за отведённое
+время, запрос SHALL завершаться ответом 503 с `code` `unavailable` в
+формате ошибки, а не 500 и не зависанием. Частично выполненная операция
+MUST NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
+обслуживать запросы без перезапуска.
+
+#### Scenario: БД остановлена
+
+- **WHEN** PostgreSQL остановлен, и клиент отправляет сообщение
+- **THEN** ответ 503 `unavailable` без деталей в `message`
+
+#### Scenario: БД вернулась
+
+- **WHEN** PostgreSQL остановлен, затем снова запущен, а сервис не
+ перезапускался
+- **THEN** следующие запросы после готовности БД обслуживаются штатно
+
+#### Scenario: Предел соединений PostgreSQL исчерпан
+
+- **WHEN** все слоты `max_connections` PostgreSQL заняты, и пулу
+ сервиса для запроса нужно новое соединение
+- **THEN** PostgreSQL отказывает в подключении («too many clients»,
+ SQLSTATE `53300`), а клиент получает 503 `unavailable` без деталей в
+ `message`, а не 500
+- **AND** после освобождения слотов запросы обслуживаются без
+ перезапуска сервиса
diff --git a/openspec/specs/data-storage/spec.md b/openspec/specs/data-storage/spec.md
index 1b50a7d8..b8e319e4 100644
--- a/openspec/specs/data-storage/spec.md
+++ b/openspec/specs/data-storage/spec.md
@@ -86,10 +86,11 @@ PostgreSQL как источник истины, сохранность посл
### Requirement: Недоступность PostgreSQL
-Если PostgreSQL недоступен или не ответил за отведённое время,
-запрос SHALL завершаться ответом 503 с `code` `unavailable` в формате
-ошибки, а не 500 и не зависанием. Частично выполненная операция MUST
-NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
+Если PostgreSQL недоступен, отказывает в новом подключении из-за
+предела соединений (`max_connections`) или не ответил за отведённое
+время, запрос SHALL завершаться ответом 503 с `code` `unavailable` в
+формате ошибки, а не 500 и не зависанием. Частично выполненная операция
+MUST NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
обслуживать запросы без перезапуска.
#### Scenario: БД остановлена
@@ -103,6 +104,16 @@ NOT фиксироваться. Когда PostgreSQL снова доступе
перезапускался
- **THEN** следующие запросы после готовности БД обслуживаются штатно
+#### Scenario: Предел соединений PostgreSQL исчерпан
+
+- **WHEN** все слоты `max_connections` PostgreSQL заняты, и пулу
+ сервиса для запроса нужно новое соединение
+- **THEN** PostgreSQL отказывает в подключении («too many clients»,
+ SQLSTATE `53300`), а клиент получает 503 `unavailable` без деталей в
+ `message`, а не 500
+- **AND** после освобождения слотов запросы обслуживаются без
+ перезапуска сервиса
+
### Requirement: Ограниченный пул соединений и таймауты
Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой.
diff --git a/src/infra/db/errors.py b/src/infra/db/errors.py
index 4657d008..90116122 100644
--- a/src/infra/db/errors.py
+++ b/src/infra/db/errors.py
@@ -9,7 +9,12 @@
- пул исчерпан — `sqlalchemy.exc.TimeoutError`;
- сработал `statement_timeout` — `DBAPIError` с SQLSTATE `57014`;
- соединение оборвано (рестарт, `pg_terminate_backend`) — `DBAPIError`
- с `connection_invalidated`.
+ с `connection_invalidated`;
+- отказ в подключении сверх `max_connections` — `TooManyConnectionsError`
+ asyncpg, `DBAPIError` с SQLSTATE `53300` (класс 53: нехватка ресурсов),
+ без `connection_invalidated`. Найден серией `pool` change
+ `scaling-bench`; остальные коды класса 53 (диск, память) сюда не
+ входят: их не воспроизводили.
Остальные `DBAPIError` (нарушение ограничения, синтаксис) — дефект
сервиса, им положен 500, а не 503.
@@ -17,9 +22,11 @@
from sqlalchemy import exc as sa_exc
-# класс 08 — ошибки соединения; 57014 — query_canceled (statement_timeout);
-# 57P01–57P03 — сервер останавливается или ещё не принимает подключения
-UNAVAILABLE_SQLSTATES = ("08", "57014", "57P01", "57P02", "57P03")
+# класс 08 — ошибки соединения; 53300 — too_many_connections (отказ в
+# подключении сверх max_connections); 57014 — query_canceled
+# (statement_timeout); 57P01–57P03 — сервер останавливается или ещё не
+# принимает подключения
+UNAVAILABLE_SQLSTATES = ("08", "53300", "57014", "57P01", "57P02", "57P03")
def is_db_unavailable(error: BaseException) -> bool:
diff --git a/student-tests/fault_hook.py b/student-tests/fault_hook.py
index 7b8933fd..d3e72f4d 100755
--- a/student-tests/fault_hook.py
+++ b/student-tests/fault_hook.py
@@ -20,6 +20,11 @@
моменту уже вставлен в той же транзакции)
clear-fail-messages убрать триггер
count-chats
число чатов с этим названием
+ fill-connections <секунд> занять все слоты max_connections сессиями
+ psql (`SELECT pg_sleep`) и оборвать
+ соединения API: их пулы переподключаются
+ и получают «too many clients» (53300)
+ clear-connections освободить слоты и дождаться подключения
Пароли не печатает: valkey-cli берёт пароль из VALKEYCLI_AUTH
контейнера, psql работает от POSTGRES_USER контейнера. Только stdlib.
@@ -92,6 +97,57 @@ DROP FUNCTION IF EXISTS fault_fail_messages();
"""
COUNT_CHATS_SQL = "SELECT count(*) FROM chats WHERE title = :'title';\n"
+# Заполнение слотов: отвязанный sh в контейнере Postgres. Сначала столько
+# попыток, сколько слотов, затем новая попытка раз в 0,05 с до конца
+# срока: слот, освободившийся после обрыва соединения API, сразу занимает
+# снова psql, а не переподключение пула. Лишние попытки получают отказ и
+# выходят. Сессии — через сокет ([local]), пользователь контейнера.
+FILL_PID = "/tmp/fault-fill.pid"
+FILL_SH = f"""\
+echo $$ > {FILL_PID}
+hold() {{
+ PGAPPNAME=fault_fill psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq \\
+ -c "SELECT pg_sleep($1)" >/dev/null 2>&1 &
+}}
+end=$(( $(date +%s) + $1 ))
+slots=$(psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq \\
+ -c 'SHOW max_connections')
+i=0
+while [ "$i" -lt "$slots" ]; do hold "$1"; i=$((i + 1)); done
+while [ "$(date +%s)" -lt "$end" ]; do hold "$1"; sleep 0.05; done
+"""
+# Обрыв соединений по TCP (это пулы API) сигналом SIGTERM — то же, что
+# pg_terminate_backend, но без своего слота. Заголовок процесса backend —
+# «postgres: <адрес>(<порт>) <состояние>»; сокет ([local]) и
+# проверку готовности с 127.0.0.1 не трогаем. Печатает число оборванных.
+KILL_TCP_SH = """\
+n=0
+for d in /proc/[0-9]*; do
+ t=$(tr '\\0' ' ' < "$d/cmdline" 2>/dev/null) || continue
+ case "$t" in
+ "postgres: "*" 127.0.0.1("*) ;;
+ "postgres: "*"("*")"*) kill -TERM "${d#/proc/}" 2>/dev/null \\
+ && n=$((n + 1)) ;;
+ esac
+done
+echo "$n"
+"""
+CLEAR_FILL_SH = f"""\
+[ -f {FILL_PID} ] && kill "$(cat {FILL_PID})" 2>/dev/null
+rm -f {FILL_PID}
+for d in /proc/[0-9]*; do
+ t=$(tr '\\0' ' ' < "$d/cmdline" 2>/dev/null) || continue
+ case "$t" in
+ "postgres: "*" [local] "*) kill -TERM "${{d#/proc/}}" 2>/dev/null ;;
+ esac
+done
+"""
+PROBE_SQL_SH = (
+ 'exec psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -XAtq -c "SELECT 1"'
+)
+TOO_MANY = "too many clients"
+FILL_TIMEOUT_S = 20
+
class HookError(Exception):
"""Неверный вызов или проект: код 2 и сообщение в stderr."""
@@ -231,6 +287,76 @@ def cache_has_chat(project: str, chat_id: str) -> str:
return valkey(project, "EXISTS", key)
+def postgres_sh(project: str, script: str, *args: str) -> str:
+ return compose(
+ project,
+ "exec",
+ "-T",
+ "postgres",
+ "sh",
+ "-c",
+ script,
+ "sh",
+ *args,
+ )
+
+
+def probe_connect(project: str) -> subprocess.CompletedProcess[str]:
+ """Новое подключение psql и `SELECT 1`."""
+ return compose_run(
+ project,
+ "exec",
+ "-T",
+ "postgres",
+ "sh",
+ "-c",
+ PROBE_SQL_SH,
+ )
+
+
+def slots_full(project: str) -> bool:
+ """Новое подключение получает «too many clients»."""
+ probe = probe_connect(project)
+ return probe.returncode != 0 and TOO_MANY in probe.stderr
+
+
+def fill_connections(project: str, seconds: str) -> str:
+ """Все слоты заняты psql, соединений API не осталось.
+
+ Готово, когда новое подключение получает отказ, а обрывать уже
+ некого: пул API, переподключаясь, получит 53300.
+ """
+ if int(seconds) <= 0:
+ raise HookError("seconds must be positive")
+ compose(
+ project,
+ "exec",
+ "-d",
+ "postgres",
+ "sh",
+ "-c",
+ FILL_SH,
+ "sh",
+ str(int(seconds)),
+ )
+ deadline = time.monotonic() + FILL_TIMEOUT_S
+ while time.monotonic() < deadline:
+ if slots_full(project) and postgres_sh(project, KILL_TCP_SH) == "0":
+ return ""
+ time.sleep(0.1)
+ raise HookError(f"connections are not filled in {FILL_TIMEOUT_S}s")
+
+
+def clear_connections(project: str) -> str:
+ deadline = time.monotonic() + FILL_TIMEOUT_S
+ while time.monotonic() < deadline:
+ postgres_sh(project, CLEAR_FILL_SH)
+ if probe_connect(project).returncode == 0:
+ return ""
+ time.sleep(0.2)
+ raise HookError(f"connections are not freed in {FILL_TIMEOUT_S}s")
+
+
def run(project: str, action: str, args: list[str]) -> str:
"""Выполнить действие; синтаксис без match: hook запускают и 3.9."""
if action in ("stop", "pause") and len(args) == 1:
@@ -257,6 +383,10 @@ def run(project: str, action: str, args: list[str]) -> str:
return psql(project, CLEAR_FAIL_MESSAGES_SQL)
if action == "count-chats" and len(args) == 1:
return psql(project, COUNT_CHATS_SQL, title=args[0])
+ if action == "fill-connections" and len(args) == 1:
+ return fill_connections(project, args[0])
+ if action == "clear-connections" and not args:
+ return clear_connections(project)
raise HookError(f"unknown action or arguments: {action} {args}")
diff --git a/student-tests/test_failures.py b/student-tests/test_failures.py
index 74b0189b..0876a58f 100644
--- a/student-tests/test_failures.py
+++ b/student-tests/test_failures.py
@@ -42,6 +42,9 @@ IDEMPOTENCY_TTL_S = 2
POOL_TIMEOUT_S = 1
# срок проверки Postgres в /health/ready
READINESS_TIMEOUT_S = 2
+# сколько секунд hook держит слоты max_connections; clear-connections
+# освобождает их раньше
+FILL_HOLD_S = 30
ME = f"{API}/users/me"
@@ -217,6 +220,29 @@ def test_pool_exhausted(tight_api: Api, stand: Stand) -> None:
assert_ok(tight_api.request("GET", ME, actor=fresh), 200, "User")
+@pytest.mark.spec("data-storage", "Предел соединений PostgreSQL исчерпан")
+def test_connection_limit_reached(tight_api: Api, stand: Stand) -> None:
+ actor = tight_api.register()
+ # hook оборвал соединение пула: при выдаче pool_pre_ping
+ # переподключается и получает «too many clients» (SQLSTATE 53300)
+ stand("fill-connections", str(FILL_HOLD_S))
+ try:
+ resp, took = timed(lambda: tight_api.request("GET", ME, actor=actor))
+ error = assert_error(resp, 503)
+ # отказ PostgreSQL мгновенный: ответ не ждёт срока пула
+ assert took < POOL_TIMEOUT_S + 0.5, f"503 took {took:.2f}s"
+ # недоступность хранилища — не отказ в аутентификации
+ assert "WWW-Authenticate" not in resp.headers
+ for word in ("postgres", "sql", "client", "connect"):
+ assert word not in error["message"].lower()
+ finally:
+ stand("clear-connections")
+ # слоты свободны: сервис снова обслуживает запросы без рестарта; срок
+ # сессии 2 с за время заполнения истёк — новый вход
+ fresh = tight_api.register()
+ assert_ok(tight_api.request("GET", ME, actor=fresh), 200, "User")
+
+
# ---------------------------------------------------------------------------
# Readiness
# ---------------------------------------------------------------------------