"""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()