openframe-adapters-db-postgres 1.0.0__py3-none-any.whl

openframe/adapters/db/postgres/__init__.py

@@ -0,0 +1,47 @@
+"""
+openframe.adapters.db.postgres
+================================
+PostgreSQL database adapter for the OpenFrame Microservice Suite.
+
+Public API:
+
+    PostgresSettings    — Pydantic Settings subclass for connection config.
+    PostgresRepository  — Generic async repository (BaseRepository + HealthCheck).
+    get_postgres_pool   — Async factory that creates / returns the cached pool.
+
+Quick start::
+
+    from openframe.adapters.db.postgres import (
+        PostgresSettings,
+        PostgresRepository,
+        get_postgres_pool,
+    )
+
+    settings = PostgresSettings(database_url="postgresql://user:pw@localhost/db")
+
+    # Raw dict mode
+    repo = PostgresRepository(settings, table="items", id_column="id")
+    item = await repo.get("abc-123")           # dict | None
+
+    # Typed mode — subclass and override mapping methods
+    class ItemRepository(PostgresRepository[Item]):
+        _table = "items"
+        _id_column = "id"
+
+        def _row_to_entity(self, row):
+            return Item(**dict(row))
+
+        def _entity_to_row(self, entity):
+            return entity.model_dump()
+"""
+from __future__ import annotations
+
+from .config import PostgresSettings
+from .connection import get_postgres_pool
+from .repository import PostgresRepository
+
+__all__ = [
+    "PostgresSettings",
+    "PostgresRepository",
+    "get_postgres_pool",
+]

openframe/adapters/db/postgres/config.py

@@ -0,0 +1,59 @@
+"""
+openframe/adapters/db/postgres/config.py
+=========================================
+PostgreSQL adapter settings.
+
+Reads all connection configuration from environment variables via Pydantic
+Settings. Every field is validated at instantiation — missing required fields
+raise ``pydantic_core.ValidationError`` immediately so misconfigured
+deployments fail fast on startup.
+
+Required env vars:
+    DATABASE_URL: Full asyncpg DSN.
+                  Format: postgresql://user:pass@host:port/dbname
+                  SSL:    postgresql://user:pass@host/dbname?ssl=require
+
+Optional env vars (all have defaults):
+    POOL_SIZE:                       int   = 10
+    POOL_MAX_INACTIVE_CONN_LIFETIME: float = 300.0
+    POOL_COMMAND_TIMEOUT:            float = 60.0
+    POOL_MAX_QUERIES:                int   = 50000
+    POSTGRES_ADAPTER_NAME:           str   = "postgres"
+"""
+from __future__ import annotations
+
+from openframe.core.config import BaseAdapterSettings
+
+__all__ = ["PostgresSettings"]
+
+
+class PostgresSettings(BaseAdapterSettings):
+    """
+    Settings for the PostgreSQL adapter.
+
+    All fields read from environment variables. Missing required fields raise
+    ``pydantic_core.ValidationError`` at instantiation time.
+
+    Inherits from ``BaseAdapterSettings``:
+        adapter_name:       str   = "postgres"  (overrides base default)
+        connection_timeout: float = 30.0
+        operation_timeout:  float = 10.0
+        max_retries:        int   = 3
+
+    Attributes:
+        database_url:                     Full asyncpg DSN (required).
+        pool_size:                        Pool min_size and max_size. Default 10.
+        pool_max_inactive_conn_lifetime:  Seconds before idle connection is
+                                          closed. Default 300.0.
+        pool_command_timeout:             Per-statement timeout in the pool.
+                                          Default 60.0.
+        pool_max_queries:                 Queries per connection before recycle.
+                                          Default 50 000.
+    """
+
+    database_url: str
+    pool_size: int = 10
+    pool_max_inactive_conn_lifetime: float = 300.0
+    pool_command_timeout: float = 60.0
+    pool_max_queries: int = 50_000
+    adapter_name: str = "postgres"

openframe/adapters/db/postgres/connection.py

@@ -0,0 +1,99 @@
+"""
+openframe/adapters/db/postgres/connection.py
+==============================================
+asyncpg connection pool factory and cache.
+
+``get_postgres_pool()`` is the single entry point for obtaining an asyncpg
+pool. It creates the pool on first call and returns the cached instance on
+every subsequent call with the same ``DATABASE_URL``. Multiple
+``PostgresRepository`` instances in the same process share the same pool.
+
+Pool cache: ``_pool_cache`` is a module-level dict keyed by database URL.
+Do NOT replace this with ``@lru_cache`` — that decorator does not support
+async functions and would create a new coroutine on each call.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import asyncpg
+
+from openframe.core.exceptions import (
+    AdapterConfigurationError,
+    AdapterConnectionError,
+    AdapterTimeoutError,
+)
+
+from .config import PostgresSettings
+
+__all__ = ["get_postgres_pool", "_pool_cache"]
+
+_pool_cache: dict[str, asyncpg.Pool] = {}  # type: ignore[type-arg]
+
+
+async def get_postgres_pool(settings: PostgresSettings) -> asyncpg.Pool:  # type: ignore[type-arg]
+    """
+    Create or return the cached asyncpg connection pool.
+
+    Creates the pool on first call for a given ``database_url``. Subsequent
+    calls with the same URL return the cached pool without re-connecting. The
+    pool is shared across all ``PostgresRepository`` instances in the process.
+
+    Args:
+        settings: A fully-validated ``PostgresSettings`` instance.
+
+    Returns:
+        An ``asyncpg.Pool`` that is ready to use.
+
+    Raises:
+        AdapterConnectionError:    Pool creation failed — host unreachable,
+                                   bad credentials, TLS error, etc.
+        AdapterConfigurationError: ``DATABASE_URL`` is syntactically invalid
+                                   (``asyncpg.InvalidCatalogNameError``).
+        AdapterTimeoutError:       Pool creation exceeded
+                                   ``settings.connection_timeout``.
+    """
+    url = settings.database_url
+    if url in _pool_cache:
+        return _pool_cache[url]
+
+    try:
+        async with asyncio.timeout(settings.connection_timeout):
+            pool: asyncpg.Pool = await asyncpg.create_pool(  # type: ignore[assignment]
+                dsn=url,
+                min_size=settings.pool_size,
+                max_size=settings.pool_size,
+                max_inactive_connection_lifetime=settings.pool_max_inactive_conn_lifetime,
+                command_timeout=settings.pool_command_timeout,
+                max_queries=settings.pool_max_queries,
+            )
+    except asyncio.TimeoutError as exc:
+        raise AdapterTimeoutError(
+            f"Pool creation exceeded {settings.connection_timeout}s connection_timeout",
+            adapter=settings.adapter_name,
+            operation="connect",
+            cause=exc,
+        ) from exc
+    except asyncpg.InvalidCatalogNameError as exc:
+        raise AdapterConfigurationError(
+            f"DATABASE_URL references an invalid or non-existent catalog: {url!r}",
+            adapter=settings.adapter_name,
+            operation="init",
+            cause=exc,
+        ) from exc
+    except (
+        asyncpg.InvalidPasswordError,
+        asyncpg.CannotConnectNowError,
+        asyncpg.TooManyConnectionsError,
+        OSError,
+    ) as exc:
+        raise AdapterConnectionError(
+            f"Cannot connect to Postgres at {url!r}: {exc}",
+            adapter=settings.adapter_name,
+            operation="connect",
+            cause=exc,
+        ) from exc
+
+    _pool_cache[url] = pool
+    return pool

openframe/adapters/db/postgres/repository.py

@@ -0,0 +1,419 @@
+"""
+openframe/adapters/db/postgres/repository.py
+==============================================
+Generic PostgreSQL repository implementing ``BaseRepository[T]`` and
+``HealthCheck`` from ``openframe-core`` via structural subtyping.
+
+The base class works with raw ``dict[str, Any]`` rows. Domain adapters
+subclass it and override ``_row_to_entity()`` / ``_entity_to_row()`` to map
+between rows and typed domain objects.
+
+Usage — raw dict mode (no subclassing needed):
+
+    repo = PostgresRepository(settings, table="items", id_column="id")
+    item: dict | None = await repo.get("abc-123")
+
+Usage — typed domain mode (subclass):
+
+    class ItemRepository(PostgresRepository[Item]):
+        _table = "items"
+        _id_column = "id"
+
+        def _row_to_entity(self, row: asyncpg.Record) -> Item:
+            return Item(**dict(row))
+
+        def _entity_to_row(self, entity: Item) -> dict[str, Any]:
+            return entity.model_dump()
+
+Structural conformance (no inheritance from Protocols required):
+
+    assert isinstance(repo, BaseRepository)
+    assert isinstance(repo, HealthCheck)
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Generic, TypeVar
+
+import asyncpg
+
+from openframe.core.exceptions import (
+    AdapterConfigurationError,
+    AdapterQueryError,
+    AdapterTimeoutError,
+)
+
+from .config import PostgresSettings
+from .connection import _pool_cache, get_postgres_pool
+
+__all__ = ["PostgresRepository"]
+
+T = TypeVar("T")
+
+
+class PostgresRepository(Generic[T]):
+    """
+    Generic PostgreSQL repository.
+
+    Implements ``BaseRepository[T]`` and ``HealthCheck`` structurally — no
+    inheritance from either Protocol. All asyncpg exceptions are caught and
+    re-raised as ``AdapterError`` subclasses. Every operation wraps its
+    asyncpg call in ``asyncio.timeout(settings.operation_timeout)``.
+
+    Class attributes (override in subclass):
+        _table:     Table name used when no ``table`` argument is passed.
+        _id_column: Primary key column. Default ``"id"``.
+
+    Args:
+        settings:  A ``PostgresSettings`` instance.
+        table:     Table name. Overrides the ``_table`` class attribute.
+        id_column: PK column name. Overrides the ``_id_column`` class attribute.
+
+    Raises:
+        AdapterConfigurationError: If neither ``table`` param nor ``_table``
+                                   class attribute is set.
+    """
+
+    _table: str = ""
+    _id_column: str = "id"
+
+    def __init__(
+        self,
+        settings: PostgresSettings,
+        table: str | None = None,
+        id_column: str | None = None,
+    ) -> None:
+        self._settings = settings
+        self._table = table or self.__class__._table
+        self._id_column = id_column or self.__class__._id_column
+
+        if not self._table:
+            raise AdapterConfigurationError(
+                "PostgresRepository requires a table name. "
+                "Pass table= to __init__ or set _table on the subclass.",
+                adapter=settings.adapter_name,
+                operation="init",
+            )
+
+    # ------------------------------------------------------------------
+    # Row ↔ entity mapping (override in typed subclasses)
+    # ------------------------------------------------------------------
+
+    def _row_to_entity(self, row: asyncpg.Record) -> T:  # type: ignore[type-arg]
+        """
+        Convert an asyncpg Record to the entity type ``T``.
+
+        Base implementation returns ``dict(row)``. Subclasses override this
+        to return typed domain objects.
+        """
+        return dict(row)  # type: ignore[return-value]
+
+    def _entity_to_row(self, entity: T) -> dict[str, Any]:
+        """
+        Convert the entity type ``T`` to a column→value dict for SQL.
+
+        Base implementation returns the entity unchanged if it is already a
+        dict, or falls back to ``vars(entity)`` for simple objects. Subclasses
+        override this to serialise typed domain objects correctly.
+        """
+        if isinstance(entity, dict):
+            return entity
+        return vars(entity)
+
+    # ------------------------------------------------------------------
+    # BaseRepository[T] interface
+    # ------------------------------------------------------------------
+
+    async def get(self, entity_id: str) -> T | None:
+        """
+        Retrieve a single row by primary key.
+
+        Args:
+            entity_id: Value of the ``_id_column`` to look up.
+
+        Returns:
+            The entity if a matching row exists, ``None`` otherwise.
+
+        Raises:
+            AdapterQueryError:   Query failed after connection was established.
+            AdapterTimeoutError: Operation exceeded ``operation_timeout``.
+        """
+        pool = await get_postgres_pool(self._settings)
+        query = (
+            f"SELECT * FROM {self._table} "
+            f"WHERE {self._id_column} = $1 LIMIT 1"
+        )
+        try:
+            async with asyncio.timeout(self._settings.operation_timeout):
+                row = await pool.fetchrow(query, entity_id)
+        except asyncio.TimeoutError as exc:
+            raise AdapterTimeoutError(
+                f"get exceeded {self._settings.operation_timeout}s operation_timeout",
+                adapter=self._settings.adapter_name,
+                operation="get",
+                cause=exc,
+            ) from exc
+        except asyncpg.PostgresError as exc:
+            raise AdapterQueryError(
+                f"get failed on {self._table}: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="get",
+                cause=exc,
+            ) from exc
+
+        if row is None:
+            return None
+        return self._row_to_entity(row)
+
+    async def list(self, limit: int, offset: int) -> tuple[list[T], int]:
+        """
+        Return a paginated slice of rows and the total row count.
+
+        Both queries run on a single connection acquired from the pool.
+
+        Args:
+            limit:  Maximum number of rows to return.
+            offset: Number of rows to skip.
+
+        Returns:
+            A 2-tuple ``(entities, total_count)`` where ``total_count`` is
+            the number of all rows in the table (not just the slice).
+
+        Raises:
+            AdapterQueryError:   Query failed after connection was established.
+            AdapterTimeoutError: Operation exceeded ``operation_timeout``.
+        """
+        pool = await get_postgres_pool(self._settings)
+        rows_query = (
+            f"SELECT * FROM {self._table} "
+            f"ORDER BY {self._id_column} LIMIT $1 OFFSET $2"
+        )
+        count_query = f"SELECT COUNT(*) FROM {self._table}"
+        try:
+            async with asyncio.timeout(self._settings.operation_timeout):
+                async with pool.acquire() as conn:
+                    rows = await conn.fetch(rows_query, limit, offset)
+                    count: int = await conn.fetchval(count_query)
+        except asyncio.TimeoutError as exc:
+            raise AdapterTimeoutError(
+                f"list exceeded {self._settings.operation_timeout}s operation_timeout",
+                adapter=self._settings.adapter_name,
+                operation="list",
+                cause=exc,
+            ) from exc
+        except asyncpg.PostgresError as exc:
+            raise AdapterQueryError(
+                f"list failed on {self._table}: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="list",
+                cause=exc,
+            ) from exc
+
+        entities = [self._row_to_entity(r) for r in rows]
+        return entities, count
+
+    async def create(self, entity: T) -> T:
+        """
+        Insert a new row and return the stored row (with DB-generated fields).
+
+        Calls ``_entity_to_row(entity)`` to obtain the column dict, then
+        executes an ``INSERT … RETURNING *`` so that database-generated
+        fields (e.g. auto-increment PK, ``created_at``) are included in the
+        returned entity.
+
+        Args:
+            entity: The entity to insert.
+
+        Returns:
+            The entity as stored, including any backend-assigned fields.
+
+        Raises:
+            AdapterQueryError:   Insert failed (e.g. unique-constraint violation).
+            AdapterTimeoutError: Operation exceeded ``operation_timeout``.
+        """
+        pool = await get_postgres_pool(self._settings)
+        row_dict = self._entity_to_row(entity)
+        columns = list(row_dict.keys())
+        values = list(row_dict.values())
+        placeholders = ", ".join(f"${i + 1}" for i in range(len(columns)))
+        col_list = ", ".join(columns)
+        query = (
+            f"INSERT INTO {self._table} ({col_list}) "
+            f"VALUES ({placeholders}) RETURNING *"
+        )
+        try:
+            async with asyncio.timeout(self._settings.operation_timeout):
+                row = await pool.fetchrow(query, *values)
+        except asyncio.TimeoutError as exc:
+            raise AdapterTimeoutError(
+                f"create exceeded {self._settings.operation_timeout}s operation_timeout",
+                adapter=self._settings.adapter_name,
+                operation="create",
+                cause=exc,
+            ) from exc
+        except asyncpg.PostgresError as exc:
+            raise AdapterQueryError(
+                f"create failed on {self._table}: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="create",
+                cause=exc,
+            ) from exc
+
+        return self._row_to_entity(row)  # type: ignore[arg-type]
+
+    async def update(self, entity: T) -> T | None:
+        """
+        Update an existing row and return the stored row.
+
+        The ``_id_column`` value is extracted from the row dict and used in
+        the ``WHERE`` clause. All other columns form the ``SET`` clause.
+
+        Args:
+            entity: The entity with updated fields. Must contain ``_id_column``.
+
+        Returns:
+            The updated entity as stored, or ``None`` if no row was matched.
+
+        Raises:
+            AdapterQueryError:   Update failed (e.g. constraint violation).
+            AdapterTimeoutError: Operation exceeded ``operation_timeout``.
+        """
+        pool = await get_postgres_pool(self._settings)
+        row_dict = self._entity_to_row(entity)
+        entity_id = row_dict.get(self._id_column)
+
+        update_cols = {k: v for k, v in row_dict.items() if k != self._id_column}
+        if not update_cols:
+            raise AdapterQueryError(
+                f"update on {self._table}: entity has no columns to update "
+                f"(only id column {self._id_column!r} found).",
+                adapter=self._settings.adapter_name,
+                operation="update",
+            )
+
+        set_parts = [
+            f"{col} = ${i + 1}" for i, col in enumerate(update_cols.keys())
+        ]
+        set_clause = ", ".join(set_parts)
+        id_placeholder = f"${len(update_cols) + 1}"
+        query = (
+            f"UPDATE {self._table} SET {set_clause} "
+            f"WHERE {self._id_column} = {id_placeholder} RETURNING *"
+        )
+        values = list(update_cols.values()) + [entity_id]
+        try:
+            async with asyncio.timeout(self._settings.operation_timeout):
+                row = await pool.fetchrow(query, *values)
+        except asyncio.TimeoutError as exc:
+            raise AdapterTimeoutError(
+                f"update exceeded {self._settings.operation_timeout}s operation_timeout",
+                adapter=self._settings.adapter_name,
+                operation="update",
+                cause=exc,
+            ) from exc
+        except asyncpg.PostgresError as exc:
+            raise AdapterQueryError(
+                f"update failed on {self._table}: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="update",
+                cause=exc,
+            ) from exc
+
+        if row is None:
+            return None
+        return self._row_to_entity(row)
+
+    async def delete(self, entity_id: str) -> bool:
+        """
+        Delete a row by primary key.
+
+        Args:
+            entity_id: Value of the ``_id_column`` to delete.
+
+        Returns:
+            ``True`` if a row was deleted, ``False`` if no row matched.
+
+        Raises:
+            AdapterQueryError:   Deletion failed.
+            AdapterTimeoutError: Operation exceeded ``operation_timeout``.
+        """
+        pool = await get_postgres_pool(self._settings)
+        query = f"DELETE FROM {self._table} WHERE {self._id_column} = $1"
+        try:
+            async with asyncio.timeout(self._settings.operation_timeout):
+                status: str = await pool.execute(query, entity_id)
+        except asyncio.TimeoutError as exc:
+            raise AdapterTimeoutError(
+                f"delete exceeded {self._settings.operation_timeout}s operation_timeout",
+                adapter=self._settings.adapter_name,
+                operation="delete",
+                cause=exc,
+            ) from exc
+        except asyncpg.PostgresError as exc:
+            raise AdapterQueryError(
+                f"delete failed on {self._table}: {exc}",
+                adapter=self._settings.adapter_name,
+                operation="delete",
+                cause=exc,
+            ) from exc
+
+        # asyncpg returns "DELETE N" where N is the number of deleted rows.
+        return status == "DELETE 1"
+
+    # ------------------------------------------------------------------
+    # HealthCheck interface
+    # ------------------------------------------------------------------
+
+    async def ping(self) -> bool:
+        """
+        Low-cost liveness check — ``SELECT 1`` with a 5-second timeout.
+
+        Returns:
+            ``True`` if the backend responded, ``False`` on any failure.
+            Never raises.
+        """
+        try:
+            pool = await get_postgres_pool(self._settings)
+            await asyncio.wait_for(pool.fetchval("SELECT 1"), timeout=5.0)
+            return True
+        except Exception:  # noqa: BLE001
+            return False
+
+    async def is_ready(self) -> bool:
+        """
+        Full readiness check — verifies public schema tables are accessible.
+
+        Queries ``pg_tables`` to confirm the database connection is healthy
+        and the schema is queryable. Uses a 10-second timeout.
+
+        Returns:
+            ``True`` if the database is ready, ``False`` on any failure.
+            Never raises.
+        """
+        try:
+            pool = await get_postgres_pool(self._settings)
+            await asyncio.wait_for(
+                pool.fetchval(
+                    "SELECT COUNT(*) FROM pg_tables WHERE schemaname = 'public'"
+                ),
+                timeout=10.0,
+            )
+            return True
+        except Exception:  # noqa: BLE001
+            return False
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def close(self) -> None:
+        """
+        Close the connection pool and remove it from the cache.
+
+        Call once at application shutdown. After this returns the pool is
+        closed and a subsequent operation will create a new pool.
+        """
+        pool = _pool_cache.get(self._settings.database_url)
+        if pool is not None:
+            await pool.close()
+            _pool_cache.pop(self._settings.database_url, None)

openframe_adapters_db_postgres-1.0.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: openframe-adapters-db-postgres
+Version: 1.0.0
+Summary: OpenFrame Microservice Suite — PostgreSQL database adapter.
+License: MIT
+Keywords: asyncpg,hexagonal,microservice,openframe,postgres
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: openframe-core<2,>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openframe-adapters-db-postgres
+
+PostgreSQL database adapter for the **OpenFrame Microservice Suite**.
+
+Part of the `openframe-adapters` monorepo. Implements `BaseRepository[T]` and
+`HealthCheck` from `openframe-core` using `asyncpg`.
+
+---
+
+## Installation
+
+```bash
+pip install openframe-adapters-db-postgres
+```
+
+Required env var:
+
+```
+DATABASE_URL=postgresql://user:password@host:5432/dbname
+```
+
+---
+
+## Quick start
+
+### Raw dict mode
+
+```python
+from openframe.adapters.db.postgres import PostgresSettings, PostgresRepository
+
+settings = PostgresSettings()  # reads DATABASE_URL from env
+repo = PostgresRepository(settings, table="items", id_column="id")
+
+item = await repo.get("abc-123")          # dict | None
+items, total = await repo.list(10, 0)     # ([dict, ...], int)
+created = await repo.create({"name": "x"})
+updated = await repo.update({"id": "abc-123", "name": "y"})
+deleted = await repo.delete("abc-123")    # bool
+```
+
+### Typed domain mode
+
+```python
+from dataclasses import dataclass
+from openframe.adapters.db.postgres import PostgresSettings, PostgresRepository
+
+@dataclass
+class Item:
+    id: str
+    name: str
+
+class ItemRepository(PostgresRepository[Item]):
+    _table = "items"
+    _id_column = "id"
+
+    def _row_to_entity(self, row) -> Item:
+        return Item(**dict(row))
+
+    def _entity_to_row(self, entity: Item) -> dict:
+        return {"id": entity.id, "name": entity.name}
+
+settings = PostgresSettings()
+repo = ItemRepository(settings)
+item: Item | None = await repo.get("abc-123")
+```
+
+---
+
+## Configuration
+
+All settings are read from environment variables.
+
+| Env var | Type | Default | Description |
+|---|---|---|---|
+| `DATABASE_URL` | `str` | **required** | Full asyncpg DSN |
+| `POOL_SIZE` | `int` | `10` | Pool min/max size |
+| `POOL_MAX_INACTIVE_CONN_LIFETIME` | `float` | `300.0` | Idle connection TTL (s) |
+| `POOL_COMMAND_TIMEOUT` | `float` | `60.0` | Per-statement timeout (s) |
+| `POOL_MAX_QUERIES` | `int` | `50000` | Queries per connection before recycle |
+| `CONNECTION_TIMEOUT` | `float` | `30.0` | Pool creation timeout (s) |
+| `OPERATION_TIMEOUT` | `float` | `10.0` | Per-operation timeout (s) |
+| `MAX_RETRIES` | `int` | `3` | Max retry attempts |
+
+---
+
+## Health checks
+
+`PostgresRepository` implements the `HealthCheck` protocol from `openframe-core`.
+
+```python
+alive = await repo.ping()       # SELECT 1 — fast liveness check
+ready = await repo.is_ready()   # pg_tables query — full readiness check
+```
+
+Both methods return `False` on any failure and never raise.
+
+---
+
+## Exception hierarchy
+
+All exceptions are `AdapterError` subclasses from `openframe.core.exceptions`.
+Raw `asyncpg` exceptions never escape the adapter.
+
+| Situation | Exception |
+|---|---|
+| Cannot connect to Postgres | `AdapterConnectionError` |
+| Invalid `DATABASE_URL` catalog | `AdapterConfigurationError` |
+| Query failed (constraint, syntax, etc.) | `AdapterQueryError` |
+| Entity not found | `AdapterNotFoundError` |
+| Operation exceeded timeout | `AdapterTimeoutError` |
+
+---
+
+## Development
+
+```bash
+# from the package directory
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## Protocol conformance
+
+```python
+from openframe.core.ports import BaseRepository
+from openframe.core.health import HealthCheck
+
+repo = PostgresRepository(settings, table="items", id_column="id")
+assert isinstance(repo, BaseRepository)   # True — structural check
+assert isinstance(repo, HealthCheck)      # True — structural check
+```
+
+No inheritance from either Protocol is required or used.
+
+---
+
+## License
+
+MIT

openframe_adapters_db_postgres-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+openframe/adapters/db/postgres/__init__.py,sha256=XB6XPlXDVXJNNZvvvnbJqmI_dtvfHB6htaiS-c1m9u8,1355
+openframe/adapters/db/postgres/config.py,sha256=jiJEHdVFqmFxiTxrLbpJEOpZNgxK5_YVWqBH2Wu4g-I,2263
+openframe/adapters/db/postgres/connection.py,sha256=BiVXCz6QJr0wSwOuvNu7YwCRs8UIPDJpatcPECyPRsc,3592
+openframe/adapters/db/postgres/repository.py,sha256=JCVP_OiJbGol_u5iSPbuNJRJb1rm0e3tT03IFiLXl-8,15438
+openframe_adapters_db_postgres-1.0.0.dist-info/METADATA,sha256=_EZBlpZ5N6x4KCdpa2PTf3crS8gywCUqxE6-AKfmZVA,4061
+openframe_adapters_db_postgres-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+openframe_adapters_db_postgres-1.0.0.dist-info/RECORD,,

openframe_adapters_db_postgres-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any