186 lines
9.0 KiB
Python
186 lines
9.0 KiB
Python
"""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()
|