Files
mtusi2026lab3/src/db.py
T

186 lines
9.0 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""PostgreSQL: engine с ограниченным пулом, срок операции, отказ → 503.
`Db` — то, через что хранилище ходит в базу. Запись — явная транзакция
`transaction()`: commit при выходе, откат при ошибке. Одиночный SELECT
читает через `read()` в AUTOCOMMIT. Вся операция ограничена
`DB_OPERATION_TIMEOUT`: зависший сервер не держит запрос бесконечно.
Ошибки, которые значат «базы нет или она не отвечает», превращаются в
`Unavailable` (503) со строкой `warning` в журнале; остальные (нарушение
ограничения, синтаксис) идут дальше как есть: это дефект или доменная
ошибка, а не отказ хранилища.
Engine открывает соединения лениво: без PostgreSQL процесс стартует,
а `/health/ready` отвечает 503.
"""
import asyncio
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import asyncpg
from sqlalchemy import URL, text
from sqlalchemy import exc as sa_exc
from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine, create_async_engine
from src.config import Database as DatabaseSettings
from src.constants import DB_APPLICATION_NAME, DB_CLOSE_TIMEOUT, READINESS_TIMEOUT
from src.errors import Unavailable
from src.log import get_logger
log = get_logger(__name__)
# SQLSTATE «база недоступна»: класс 08 — ошибки соединения, 57014 —
# сработал statement_timeout, 57P01–57P03 — сервер останавливается или
# ещё не принимает подключения
UNAVAILABLE_SQLSTATES = ("08", "57014", "57P01", "57P02", "57P03")
# длина текста ошибки в журнале: одна строка, без простыни SQLAlchemy
_ERROR_TEXT_LIMIT = 300
class BoundedCloseConnection(asyncpg.Connection):
"""Соединение asyncpg, мягкое закрытие которого ограничено сроком.
Прерванный по сроку запрос SQLAlchemy закрывает соединение мягко, а
asyncpg при этом ждёт ответа сервера без ограничения: замёрзший
PostgreSQL держал бы запрос до разморозки. Здесь закрытие ограничено
`DB_CLOSE_TIMEOUT`, дальше asyncpg обрывает соединение.
"""
# сигнатура — как у asyncpg.Connection.close: SQLAlchemy зовёт её так
async def close(self, *, timeout: float | None = None) -> None: # noqa: ASYNC109
await asyncio.wait_for(
super().close(timeout=timeout), timeout or DB_CLOSE_TIMEOUT
)
def database_url(settings: DatabaseSettings) -> URL:
"""URL драйвера asyncpg; пароль экранирует `URL.create`, строку не собираем."""
return URL.create(
"postgresql+asyncpg",
username=settings.user,
password=settings.password,
host=settings.host,
port=settings.port,
database=settings.name,
)
def create_engine(settings: DatabaseSettings) -> AsyncEngine:
"""Engine с ограниченным пулом и таймаутами из настроек."""
return create_async_engine(
database_url(settings),
pool_size=settings.pool_size,
max_overflow=settings.pool_overflow,
pool_timeout=settings.pool_timeout,
# одиночные SELECT не требуют отдельных BEGIN/COMMIT; запись ниже
# получает READ COMMITTED через engine с тем же пулом
isolation_level="AUTOCOMMIT",
skip_autocommit_rollback=True,
# после рестарта PostgreSQL соединения пула мертвы: проверка при
# выдаче не даёт первому запросу получить ошибку
pool_pre_ping=True,
# текст ошибки драйвера уходит в журнал: без этого в нём были бы
# параметры SQL — тексты сообщений, хэши паролей и токенов
hide_parameters=True,
connect_args={
"timeout": settings.connect_timeout,
# command_timeout asyncpg не задан: на зависшем сервере он
# отменяет запрос через новое соединение и ждёт без срока
"connection_class": BoundedCloseConnection,
"server_settings": {
"application_name": DB_APPLICATION_NAME,
"statement_timeout": str(settings.statement_timeout_ms),
},
},
)
def is_unavailable(error: BaseException) -> bool:
"""Ошибка значит «PostgreSQL недоступен» (→ 503), а не дефект (→ 500).
Остановленный сервер — `ConnectionRefusedError`, неразрешимое имя —
`socket.gaierror`, срок операции — `TimeoutError`: всё это `OSError`.
Пул исчерпан — `sqlalchemy.exc.TimeoutError`. Оборванное соединение и
statement_timeout — `DBAPIError` с признаком или SQLSTATE.
"""
if isinstance(error, OSError | sa_exc.TimeoutError):
return True
if isinstance(error, sa_exc.DBAPIError):
if error.connection_invalidated:
return True
sqlstate = getattr(error.orig, "sqlstate", None) or ""
return sqlstate.startswith(UNAVAILABLE_SQLSTATES)
return False
def _one_line(error: BaseException) -> str:
# TimeoutError от asyncio.timeout без текста — тогда repr
raw = " ".join(str(error).split()) or repr(error)
return raw[:_ERROR_TEXT_LIMIT]
class Db:
"""Engine процесса и границы транзакций хранилища."""
def __init__(self, settings: DatabaseSettings) -> None:
# имя базы: им же разделяются ключи кэша разных баз на одном Valkey
self.name = settings.name
self.engine = create_engine(settings)
# производный engine разделяет пул; запись всегда в транзакции
self._write_engine = self.engine.execution_options(
isolation_level="READ COMMITTED"
)
self._operation_timeout = settings.operation_timeout
@asynccontextmanager
async def _operation(self) -> AsyncIterator[None]:
"""Срок и перевод отказов общие для чтения и записи.
На сроке asyncio отменяет ожидание драйвера: SQLAlchemy считает
такое соединение испорченным и не возвращает его в пул, а его
закрытие ограничено `BoundedCloseConnection`. Поэтому замёрзший
сервер даёт 503 через `DB_OPERATION_TIMEOUT` + `DB_CLOSE_TIMEOUT`.
"""
try:
async with asyncio.timeout(self._operation_timeout):
yield
except Exception as exc:
if not is_unavailable(exc):
raise
log.warning(
"database unavailable error_type=%s error=%s",
type(exc).__name__,
_one_line(exc),
)
raise Unavailable from exc
@asynccontextmanager
async def transaction(self) -> AsyncIterator[AsyncConnection]:
"""Атомарная запись: commit при выходе, rollback при исключении."""
async with self._operation(), self._write_engine.begin() as connection:
yield connection
@asynccontextmanager
async def read(self) -> AsyncIterator[AsyncConnection]:
"""Один SELECT в AUTOCOMMIT; составные операции требуют transaction."""
async with self._operation(), self.engine.connect() as connection:
yield connection
async def ping(self) -> None:
"""`SELECT 1` за `READINESS_TIMEOUT`; иначе `Unavailable`.
Не логирует: healthcheck спрашивает каждые несколько секунд.
Любая ошибка — 503: готовность не отвечает 500.
"""
try:
async with (
asyncio.timeout(READINESS_TIMEOUT),
self.engine.connect() as connection,
):
await connection.execute(text("SELECT 1"))
except Exception as exc:
raise Unavailable from exc
async def dispose(self) -> None:
await self.engine.dispose()