db-retry 0.3.0__tar.gz

db_retry-0.3.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: db-retry
+Version: 0.3.0
+Summary: PostgreSQL and SQLAlchemy Tools
+Keywords: python,postgresql,sqlalchemy
+Author: community-of-python
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: tenacity
+Requires-Dist: sqlalchemy[asyncio]
+Requires-Dist: asyncpg
+Requires-Python: >=3.13, <4
+Project-URL: repository, https://github.com/modern-python/sa-utils
+Description-Content-Type: text/markdown
+
+# db-retry
+
+A Python library providing robust retry mechanisms, connection utilities, and transaction helpers for PostgreSQL and SQLAlchemy applications.
+
+## Features
+
+- **Retry Decorators**: Automatic retry logic for transient database errors
+- **Connection Factories**: Robust connection handling with multi-host support
+- **DSN Utilities**: Flexible Data Source Name parsing and manipulation
+- **Transaction Helpers**: Simplified transaction management with automatic cleanup
+
+## Installation
+
+### Using uv
+
+```bash
+uv add db-retry
+```
+
+### Using pip
+
+```bash
+pip install db-retry
+```
+
+## ORM-Based Usage Examples
+
+### 1. Database Operations with Automatic Retry
+
+Protect your database operations from transient failures using ORM models:
+
+```python
+import asyncio
+import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from db_retry import postgres_retry
+
+
+class User(DeclarativeBase):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(sa.String())
+    email: Mapped[str] = mapped_column(sa.String(), index=True)
+
+
+# Apply retry logic to ORM operations
+@postgres_retry
+async def get_user_by_email(session: AsyncSession, email: str) -> User:
+    return await session.scalar(
+        sa.select(User).where(User.email == email)
+    )
+
+
+async def main():
+    engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+    async with AsyncSession(engine) as session:
+        # Automatically retries on connection failures or serialization errors
+        user = await get_user_by_email(session, "john.doe@example.com")
+        if user:
+            print(f"Found user: {user.name}")
+
+
+asyncio.run(main())
+```
+
+### 2. High Availability Database Connections
+
+Set up resilient database connections with multiple fallback hosts:
+
+```python
+import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from db_retry import build_connection_factory, build_db_dsn
+
+# Configure multiple database hosts for high availability
+multi_host_dsn = (
+    "postgresql://user:password@/"
+    "myapp_db?"
+    "host=primary-db:5432&"
+    "host=secondary-db:5432&"
+    "host=backup-db:5432"
+)
+
+# Build production-ready DSN
+dsn = build_db_dsn(
+    db_dsn=multi_host_dsn,
+    database_name="production_database",
+    drivername="postgresql+asyncpg"
+)
+
+# Create connection factory with timeout
+connection_factory = build_connection_factory(
+    url=dsn,
+    timeout=5.0  # 5 second connection timeout
+)
+
+# Engine will automatically try different hosts on failure
+engine = create_async_engine(dsn, async_creator=connection_factory)
+```
+
+### 3. Simplified Transaction Management
+
+Handle database transactions with automatic cleanup using ORM:
+
+```python
+import dataclasses
+import datetime
+import typing
+
+from schemas import AnalyticsEventCreate, AnalyticsEvent
+from db_retry import Transaction, postgres_retry
+
+from your_service_name.database.tables import EventsTable
+from your_service_name.producers.analytics_service_events_producer import AnalyticsEventsProducer
+from your_service_name.repositories.events_repository import EventsRepository
+from your_service_name.settings import settings
+
+
+@dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
+class CreateEventUseCase:
+    events_repository: EventsRepository
+    transaction: Transaction
+    analytics_events_producer: AnalyticsEventsProducer
+
+    @postgres_retry
+    async def __call__(
+            self,
+            event_create_data: AnalyticsEventCreate,
+    ) -> AnalyticsEvent:
+        async with self.transaction:
+            model: typing.Final = EventsTable(
+                **event_create_data.model_dump(),
+                created_at=datetime.datetime.now(tz=settings.common.default_timezone),
+            )
+            saved_event: typing.Final[EventsTable] = await self.events_repository.create(model)
+            event: typing.Final = AnalyticsEvent.model_validate(saved_event)
+            await self.analytics_events_producer.send_message(event)
+            await self.transaction.commit()
+            return event
+
+```
+
+### 4. Serializable Transactions for Consistency
+
+Use serializable isolation level to prevent race conditions with ORM:
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from db_retry import Transaction
+
+
+async def main():
+    engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+
+    async with AsyncSession(engine) as session:
+        strict_transaction = Transaction(
+            session=session,
+            isolation_level="SERIALIZABLE",
+        )
+        # use strict_transaction where needed
+```
+
+## Configuration
+
+The library can be configured using environment variables:
+
+| Variable                | Description                                      | Default |
+|-------------------------|--------------------------------------------------|---------|
+| `DB_RETRY_RETRIES_NUMBER` | Number of retry attempts for database operations | 3       |
+
+Example:
+```bash
+export DB_UTILS_RETRIES_NUMBER=5
+```
+
+## API Reference
+
+### Retry Decorator
+- `@postgres_retry` - Decorator for async functions that should retry on database errors
+
+### Connection Utilities
+- `build_connection_factory(url, timeout)` - Creates a connection factory for multi-host setups
+- `build_db_dsn(db_dsn, database_name, use_replica=False, drivername="postgresql")` - Builds a DSN with specified parameters
+- `is_dsn_multihost(db_dsn)` - Checks if a DSN contains multiple hosts
+
+### Transaction Helper
+- `Transaction(session, isolation_level=None)` - Context manager for simplified transaction handling
+
+## Requirements
+
+- Python 3.13+
+- SQLAlchemy with asyncio support
+- asyncpg PostgreSQL driver
+- tenacity for retry logic
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

db_retry-0.3.0/README.md

@@ -0,0 +1,201 @@
+# db-retry
+
+A Python library providing robust retry mechanisms, connection utilities, and transaction helpers for PostgreSQL and SQLAlchemy applications.
+
+## Features
+
+- **Retry Decorators**: Automatic retry logic for transient database errors
+- **Connection Factories**: Robust connection handling with multi-host support
+- **DSN Utilities**: Flexible Data Source Name parsing and manipulation
+- **Transaction Helpers**: Simplified transaction management with automatic cleanup
+
+## Installation
+
+### Using uv
+
+```bash
+uv add db-retry
+```
+
+### Using pip
+
+```bash
+pip install db-retry
+```
+
+## ORM-Based Usage Examples
+
+### 1. Database Operations with Automatic Retry
+
+Protect your database operations from transient failures using ORM models:
+
+```python
+import asyncio
+import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from db_retry import postgres_retry
+
+
+class User(DeclarativeBase):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(sa.String())
+    email: Mapped[str] = mapped_column(sa.String(), index=True)
+
+
+# Apply retry logic to ORM operations
+@postgres_retry
+async def get_user_by_email(session: AsyncSession, email: str) -> User:
+    return await session.scalar(
+        sa.select(User).where(User.email == email)
+    )
+
+
+async def main():
+    engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+    async with AsyncSession(engine) as session:
+        # Automatically retries on connection failures or serialization errors
+        user = await get_user_by_email(session, "john.doe@example.com")
+        if user:
+            print(f"Found user: {user.name}")
+
+
+asyncio.run(main())
+```
+
+### 2. High Availability Database Connections
+
+Set up resilient database connections with multiple fallback hosts:
+
+```python
+import sqlalchemy as sa
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from db_retry import build_connection_factory, build_db_dsn
+
+# Configure multiple database hosts for high availability
+multi_host_dsn = (
+    "postgresql://user:password@/"
+    "myapp_db?"
+    "host=primary-db:5432&"
+    "host=secondary-db:5432&"
+    "host=backup-db:5432"
+)
+
+# Build production-ready DSN
+dsn = build_db_dsn(
+    db_dsn=multi_host_dsn,
+    database_name="production_database",
+    drivername="postgresql+asyncpg"
+)
+
+# Create connection factory with timeout
+connection_factory = build_connection_factory(
+    url=dsn,
+    timeout=5.0  # 5 second connection timeout
+)
+
+# Engine will automatically try different hosts on failure
+engine = create_async_engine(dsn, async_creator=connection_factory)
+```
+
+### 3. Simplified Transaction Management
+
+Handle database transactions with automatic cleanup using ORM:
+
+```python
+import dataclasses
+import datetime
+import typing
+
+from schemas import AnalyticsEventCreate, AnalyticsEvent
+from db_retry import Transaction, postgres_retry
+
+from your_service_name.database.tables import EventsTable
+from your_service_name.producers.analytics_service_events_producer import AnalyticsEventsProducer
+from your_service_name.repositories.events_repository import EventsRepository
+from your_service_name.settings import settings
+
+
+@dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
+class CreateEventUseCase:
+    events_repository: EventsRepository
+    transaction: Transaction
+    analytics_events_producer: AnalyticsEventsProducer
+
+    @postgres_retry
+    async def __call__(
+            self,
+            event_create_data: AnalyticsEventCreate,
+    ) -> AnalyticsEvent:
+        async with self.transaction:
+            model: typing.Final = EventsTable(
+                **event_create_data.model_dump(),
+                created_at=datetime.datetime.now(tz=settings.common.default_timezone),
+            )
+            saved_event: typing.Final[EventsTable] = await self.events_repository.create(model)
+            event: typing.Final = AnalyticsEvent.model_validate(saved_event)
+            await self.analytics_events_producer.send_message(event)
+            await self.transaction.commit()
+            return event
+
+```
+
+### 4. Serializable Transactions for Consistency
+
+Use serializable isolation level to prevent race conditions with ORM:
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from db_retry import Transaction
+
+
+async def main():
+    engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+
+    async with AsyncSession(engine) as session:
+        strict_transaction = Transaction(
+            session=session,
+            isolation_level="SERIALIZABLE",
+        )
+        # use strict_transaction where needed
+```
+
+## Configuration
+
+The library can be configured using environment variables:
+
+| Variable                | Description                                      | Default |
+|-------------------------|--------------------------------------------------|---------|
+| `DB_RETRY_RETRIES_NUMBER` | Number of retry attempts for database operations | 3       |
+
+Example:
+```bash
+export DB_UTILS_RETRIES_NUMBER=5
+```
+
+## API Reference
+
+### Retry Decorator
+- `@postgres_retry` - Decorator for async functions that should retry on database errors
+
+### Connection Utilities
+- `build_connection_factory(url, timeout)` - Creates a connection factory for multi-host setups
+- `build_db_dsn(db_dsn, database_name, use_replica=False, drivername="postgresql")` - Builds a DSN with specified parameters
+- `is_dsn_multihost(db_dsn)` - Checks if a DSN contains multiple hosts
+
+### Transaction Helper
+- `Transaction(session, isolation_level=None)` - Context manager for simplified transaction handling
+
+## Requirements
+
+- Python 3.13+
+- SQLAlchemy with asyncio support
+- asyncpg PostgreSQL driver
+- tenacity for retry logic
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

db_retry-0.3.0/db_retry/__init__.py

@@ -0,0 +1,13 @@
+from db_retry.connections import build_connection_factory
+from db_retry.dsn import build_db_dsn, is_dsn_multihost
+from db_retry.retry import postgres_retry
+from db_retry.transaction import Transaction
+
+
+__all__ = [
+    "Transaction",
+    "build_connection_factory",
+    "build_db_dsn",
+    "is_dsn_multihost",
+    "postgres_retry",
+]

db_retry-0.3.0/db_retry/connections.py

@@ -0,0 +1,79 @@
+import logging
+import random
+import typing
+from operator import itemgetter
+
+import asyncpg
+import sqlalchemy
+from asyncpg.connect_utils import SessionAttribute
+from sqlalchemy.dialects.postgresql.asyncpg import PGDialect_asyncpg
+
+
+if typing.TYPE_CHECKING:
+    ConnectionType = asyncpg.Connection[typing.Any]
+
+
+logger = logging.getLogger(__name__)
+
+
+def build_connection_factory(
+    url: sqlalchemy.URL,
+    timeout: float,
+) -> typing.Callable[[], typing.Awaitable["ConnectionType"]]:
+    connect_args: typing.Final[dict[str, typing.Any]] = PGDialect_asyncpg().create_connect_args(url)[1]  # type: ignore[no-untyped-call]
+    raw_target_session_attrs: typing.Final[str | None] = connect_args.pop("target_session_attrs", None)
+    target_session_attrs: typing.Final[SessionAttribute | None] = (
+        SessionAttribute(raw_target_session_attrs) if raw_target_session_attrs else None
+    )
+
+    raw_hosts: typing.Final[str | list[str]] = connect_args.pop("host")
+    raw_ports: typing.Final[int | list[int] | None] = connect_args.pop("port", None)
+    hosts_and_ports: list[tuple[str, int]]
+    hosts: str | list[str]
+    ports: int | list[int] | None
+    if isinstance(raw_hosts, list) and isinstance(raw_ports, list):
+        hosts_and_ports = list(zip(raw_hosts, raw_ports, strict=True))
+        random.shuffle(hosts_and_ports)
+        hosts = list(map(itemgetter(0), hosts_and_ports))
+        ports = list(map(itemgetter(1), hosts_and_ports))
+    else:
+        hosts_and_ports = []
+        hosts = raw_hosts
+        ports = raw_ports
+
+    async def _connection_factory() -> "ConnectionType":
+        connection: ConnectionType
+        nonlocal hosts_and_ports
+        try:
+            connection = await asyncpg.connect(
+                **connect_args,
+                host=hosts,
+                port=ports,
+                timeout=timeout,
+                target_session_attrs=target_session_attrs,
+            )
+            return connection  # noqa: TRY300
+        except TimeoutError:
+            if not hosts_and_ports:
+                raise
+
+            logger.warning("Failed to fetch asyncpg connection. Trying host by host.")
+
+        hosts_and_ports_copy: typing.Final = hosts_and_ports.copy()
+        random.shuffle(hosts_and_ports_copy)
+        for one_host, one_port in hosts_and_ports_copy:
+            try:
+                connection = await asyncpg.connect(
+                    **connect_args,
+                    host=one_host,
+                    port=one_port,
+                    timeout=timeout,
+                    target_session_attrs=target_session_attrs,
+                )
+                return connection  # noqa: TRY300
+            except (TimeoutError, OSError, asyncpg.TargetServerAttributeNotMatched) as exc:
+                logger.warning("Failed to fetch asyncpg connection from %s, %s", one_host, exc)
+        msg: typing.Final = f"None of the hosts match the target attribute requirement {target_session_attrs}"
+        raise asyncpg.TargetServerAttributeNotMatched(msg)
+
+    return _connection_factory

db_retry-0.3.0/db_retry/dsn.py

@@ -0,0 +1,34 @@
+import typing
+
+import sqlalchemy as sa
+
+
+def build_db_dsn(
+    db_dsn: str,
+    database_name: str,
+    use_replica: bool = False,
+    drivername: str = "postgresql",
+) -> sa.URL:
+    """Parse DSN variable and replace some parts.
+
+    - DSN stored in format postgresql://login:password@/db_placeholder?host=host1&host=host2
+    https://docs.sqlalchemy.org/en/20/dialects/postgresql.html#specifying-multiple-fallback-hosts
+    - 'db_placeholder' is replaced here with service database name
+    - `target_session_attrs` is chosen based on `use_replica` arg
+    """
+    parsed_db_dsn: typing.Final = sa.make_url(db_dsn)
+    db_dsn_query: typing.Final[dict[str, typing.Any]] = dict(parsed_db_dsn.query or {})
+    return parsed_db_dsn.set(
+        database=database_name,
+        drivername=drivername,
+        query=db_dsn_query
+        | {
+            "target_session_attrs": "prefer-standby" if use_replica else "read-write",
+        },
+    )
+
+
+def is_dsn_multihost(db_dsn: str) -> bool:
+    parsed_db_dsn: typing.Final = sa.make_url(db_dsn)
+    db_dsn_query: typing.Final[dict[str, typing.Any]] = dict(parsed_db_dsn.query or {})
+    return bool((hosts := db_dsn_query.get("host")) and isinstance(hosts, tuple) and len(hosts) > 1)

db_retry-0.3.0/db_retry/retry.py

@@ -0,0 +1,42 @@
+import functools
+import logging
+import typing
+
+import asyncpg
+import tenacity
+from sqlalchemy.exc import DBAPIError
+
+from db_retry import settings
+
+
+logger = logging.getLogger(__name__)
+
+
+def _retry_handler(exception: BaseException) -> bool:
+    if (
+        isinstance(exception, DBAPIError)
+        and hasattr(exception, "orig")
+        and isinstance(exception.orig.__cause__, (asyncpg.SerializationError, asyncpg.PostgresConnectionError))  # type: ignore[union-attr]
+    ):
+        logger.debug("postgres_retry, retrying")
+        return True
+
+    logger.debug("postgres_retry, giving up on retry")
+    return False
+
+
+def postgres_retry[**P, T](
+    func: typing.Callable[P, typing.Coroutine[None, None, T]],
+) -> typing.Callable[P, typing.Coroutine[None, None, T]]:
+    @tenacity.retry(
+        stop=tenacity.stop_after_attempt(settings.DB_RETRY_RETRIES_NUMBER),
+        wait=tenacity.wait_exponential_jitter(),
+        retry=tenacity.retry_if_exception(_retry_handler),
+        reraise=True,
+        before=tenacity.before_log(logger, logging.DEBUG),
+    )
+    @functools.wraps(func)
+    async def wrapped_method(*args: P.args, **kwargs: P.kwargs) -> T:
+        return await func(*args, **kwargs)
+
+    return wrapped_method

db_retry-0.3.0/db_retry/settings.py

@@ -0,0 +1,5 @@
+import os
+import typing
+
+
+DB_RETRY_RETRIES_NUMBER: typing.Final = int(os.getenv("DB_RETRY_RETRIES_NUMBER", "3"))

db_retry-0.3.0/db_retry/transaction.py

@@ -0,0 +1,28 @@
+import dataclasses
+
+import typing_extensions
+from sqlalchemy.engine.interfaces import IsolationLevel
+from sqlalchemy.ext import asyncio as sa_async
+
+
+@dataclasses.dataclass(kw_only=True, frozen=True, slots=True)
+class Transaction:
+    session: sa_async.AsyncSession
+    isolation_level: IsolationLevel | None = None
+
+    async def __aenter__(self) -> typing_extensions.Self:
+        if self.isolation_level:
+            await self.session.connection(execution_options={"isolation_level": self.isolation_level})
+
+        if not self.session.in_transaction():
+            await self.session.begin()
+        return self
+
+    async def __aexit__(self, *args: object, **kwargs: object) -> None:
+        await self.session.close()
+
+    async def commit(self) -> None:
+        await self.session.commit()
+
+    async def rollback(self) -> None:
+        await self.session.rollback()

db_retry-0.3.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "db-retry"
+description = "PostgreSQL and SQLAlchemy Tools"
+authors = [
+    { name = "community-of-python" },
+]
+readme = "README.md"
+requires-python = ">=3.13,<4"
+license = "MIT"
+keywords = [
+    "python",
+    "postgresql",
+    "sqlalchemy",
+]
+classifiers = [
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+    "Topic :: Software Development :: Libraries",
+]
+version = "0.3.0"
+dependencies = [
+    "tenacity",
+    "sqlalchemy[asyncio]",
+    "asyncpg",
+]
+
+[project.urls]
+repository = "https://github.com/modern-python/sa-utils"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "pytest-cov",
+    "pytest-asyncio",
+]
+lint = [
+    "ruff",
+    "mypy",
+    "eof-fixer",
+    "asyncpg-stubs",
+]
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "db_retry"
+module-root = ""
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+
+[tool.ruff]
+fix = false
+unsafe-fixes = true
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D1", # allow missing docstrings
+    "S101", # allow asserts
+    "TCH", # ignore flake8-type-checking
+    "FBT", # allow boolean args
+    "D203", # "one-blank-line-before-class" conflicting with D211
+    "D213", # "multi-line-summary-second-line" conflicting with D212
+    "COM812", # flake8-commas "Trailing comma missing"
+    "ISC001", # flake8-implicit-str-concat
+    "G004", # allow f-strings in logging
+]
+isort.lines-after-imports = 2
+isort.no-lines-before = ["standard-library", "local-folder"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=. --cov-report term-missing"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.coverage.run]
+concurrency = ["thread", "greenlet"]
+
+[tool.coverage.report]
+exclude_also = [
+    "if typing.TYPE_CHECKING:",
+]