openframe-adapters-db-postgres 1.0.0__tar.gz → 1.2.0__tar.gz

{openframe_adapters_db_postgres-1.0.0 → openframe_adapters_db_postgres-1.2.0}/.gitignore

@@ -216,3 +216,6 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Miscellaneous
+.DS_Store

{openframe_adapters_db_postgres-1.0.0 → openframe_adapters_db_postgres-1.2.0}/PKG-INFO

@@ -1,12 +1,19 @@
 Metadata-Version: 2.4
 Name: openframe-adapters-db-postgres
-Version: 1.0.0
+Version: 1.2.0
 Summary: OpenFrame Microservice Suite — PostgreSQL database adapter.
+Project-URL: Homepage, https://github.com/Furious-Meteors/openframe-adapters
+Project-URL: Documentation, https://furious-meteors.github.io/openframe-adapters/
+Project-URL: Repository, https://github.com/Furious-Meteors/openframe-adapters
+Project-URL: Changelog, https://github.com/Furious-Meteors/openframe-adapters/blob/production/.github/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/Furious-Meteors/openframe-adapters/issues
+Author-email: Furious Meteors Engineering <engineering@furiousmeteors.dev>
+Maintainer-email: Furious Meteors Engineering <engineering@furiousmeteors.dev>
 License: MIT
 Keywords: asyncpg,hexagonal,microservice,openframe,postgres
 Requires-Python: >=3.11
 Requires-Dist: asyncpg>=0.29
-Requires-Dist: openframe-core<2,>=1.0
+Requires-Dist: openframe-core<3,>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-mock>=3.14; extra == 'dev'

{openframe_adapters_db_postgres-1.0.0 → openframe_adapters_db_postgres-1.2.0}/openframe/adapters/db/postgres/__init__.py

@@ -38,10 +38,12 @@ from __future__ import annotations
 
 from .config import PostgresSettings
 from .connection import get_postgres_pool
+from .plugin import PostgresPlugin
 from .repository import PostgresRepository
 
 __all__ = [
     "PostgresSettings",
     "PostgresRepository",
     "get_postgres_pool",
+    "PostgresPlugin",
 ]

openframe_adapters_db_postgres-1.2.0/openframe/adapters/db/postgres/plugin.py

@@ -0,0 +1,231 @@
+"""
+openframe/adapters/db/postgres/plugin.py
+==========================================
+OpenFrame plugin wrapper for PostgresRepository.
+
+Stability: beta
+
+Usage via PluginRegistry (optional)::
+
+    from openframe.core.plugins import PluginRegistry
+    from openframe.adapters.db.postgres import PostgresPlugin, PostgresSettings
+
+    registry = PluginRegistry()
+    registry.register(PostgresPlugin(PostgresSettings()))
+    await registry.initialize_all()
+
+    plugin = registry.get("persistence")
+    repo = plugin.get_repository()
+
+Usage via deps.py (unchanged, no plugin needed)::
+
+    repo = PostgresRepository(PostgresSettings())
+    traced = TracingProxy(repo, prefix="repository.item")
+"""
+# Capability: "persistence"
+# See capability taxonomy:
+# https://furious-meteors.github.io/openframe-core/developer-guide/composition-root/
+from __future__ import annotations
+
+import logging
+
+from openframe.core.exceptions import AdapterConnectionError
+from openframe.core.plugins import PluginContext, PluginHealth, PluginStatus
+
+from openframe.adapters.db.postgres.config import PostgresSettings
+from openframe.adapters.db.postgres.connection import _pool_cache, get_postgres_pool
+from openframe.adapters.db.postgres.repository import PostgresRepository
+
+__all__ = ["PostgresPlugin"]
+
+_logger = logging.getLogger(__name__)
+
+
+class PostgresPlugin:
+    """
+    PostgreSQL adapter plugin for the OpenFrame plugin registry.
+
+    Capability: "persistence"
+
+    Stability: beta
+
+    Lifecycle:
+        initialize() — creates the asyncpg connection pool and verifies
+                       connectivity via ping(). Raises AdapterConnectionError
+                       if the database is unreachable.
+        shutdown()   — closes the connection pool. Never raises.
+        health()     — calls ping() and returns PluginHealth. Never raises.
+
+    The plugin exposes get_repository() after initialization for use
+    in the composition root or ApplicationBootstrap.
+
+    By default constructs a plain PostgresRepository. To use a domain-specific
+    subclass, pass it via repository_class::
+
+        registry.register(PostgresPlugin(
+            PostgresSettings(),
+            table="items",
+            id_column="id",
+            repository_class=ItemPostgresRepository,
+        ))
+    """
+
+    name:       str = "openframe-postgres"
+    version:    str = "1.2.0"
+    capability: str = "persistence"
+
+    def __init__(
+        self,
+        settings: PostgresSettings,
+        table: str = "",
+        id_column: str = "id",
+        repository_class: type[PostgresRepository] = PostgresRepository,
+    ) -> None:
+        """
+        Args:
+            settings:         PostgresSettings instance.
+            table:            Table name. If omitted the plugin acts as a
+                              connection manager only (no get_repository()).
+            id_column:        Primary key column name. Defaults to "id".
+            repository_class: The PostgresRepository subclass to construct.
+                              Defaults to the base PostgresRepository. Pass a
+                              domain-specific subclass here to get proper
+                              entity mapping through get_repository().
+
+        Raises:
+            TypeError: repository_class is not a subclass of PostgresRepository.
+        """
+        if not (isinstance(repository_class, type) and issubclass(repository_class, PostgresRepository)):
+            raise TypeError(
+                f"repository_class must be a subclass of PostgresRepository, "
+                f"got {repository_class!r}"
+            )
+        self._settings = settings
+        self._table = table
+        self._id_column = id_column
+        self._repository_class = repository_class
+        self._repo: PostgresRepository | None = None
+        self._status = PluginStatus.REGISTERED
+
+    async def initialize(self, context: PluginContext) -> None:
+        """
+        Initialize the PostgreSQL connection pool and verify connectivity.
+
+        If a ``table`` was passed to the constructor, a
+        :class:`PostgresRepository` is created and connectivity is verified
+        via ``repo.ping()``.  When no table is provided the plugin is used
+        purely as a connection manager: connectivity is verified with a
+        direct ``SELECT 1`` against the pool.
+
+        Args:
+            context: Plugin context (config, plugin_name). Unused here —
+                     settings are provided at construction time.
+
+        Raises:
+            AdapterConnectionError: PostgreSQL is unreachable or credentials
+                                    are invalid.
+            AdapterConfigurationError: DATABASE_URL is malformed.
+        """
+        self._status = PluginStatus.INITIALIZED
+        try:
+            pool = await get_postgres_pool(self._settings)
+            if self._table:
+                self._repo = self._repository_class(
+                    self._settings,
+                    table=self._table,
+                    id_column=self._id_column,
+                )
+                if not await self._repo.ping():
+                    raise AdapterConnectionError(
+                        "PostgreSQL ping failed after pool creation",
+                        adapter="postgres",
+                        operation="initialize",
+                    )
+            else:
+                # Verify pool connectivity without requiring a table.
+                try:
+                    await pool.fetchval("SELECT 1")
+                except Exception as exc:
+                    raise AdapterConnectionError(
+                        f"PostgreSQL connectivity check failed: {exc}",
+                        adapter="postgres",
+                        operation="initialize",
+                    ) from exc
+            self._status = PluginStatus.READY
+            _logger.info(
+                "PostgresPlugin initialized — %s (repository_class=%s)",
+                self._settings.database_url.split("@")[-1],
+                self._repository_class.__name__,
+            )
+        except Exception:
+            self._status = PluginStatus.FAILED
+            raise
+
+    async def shutdown(self) -> None:
+        """
+        Close the PostgreSQL connection pool.
+
+        Never raises — logs errors and continues.
+        """
+        self._status = PluginStatus.STOPPING
+        try:
+            if self._repo is not None:
+                await self._repo.close()
+                _logger.info("PostgresPlugin shutdown complete.")
+        except Exception as exc:
+            _logger.error("PostgresPlugin shutdown error (ignored): %s", exc)
+        finally:
+            self._status = PluginStatus.STOPPED
+
+    async def health(self) -> PluginHealth:
+        """
+        Return current health snapshot.
+
+        Never raises — returns FAILED status on any exception.
+        """
+        try:
+            if self._status != PluginStatus.READY:
+                return PluginHealth(
+                    status=PluginStatus.FAILED,
+                    message=f"Plugin status: {self._status.name}",
+                )
+            if self._repo is not None:
+                healthy = await self._repo.ping()
+            else:
+                # No repository — ping the pool directly.
+                try:
+                    pool = await get_postgres_pool(self._settings)
+                    await pool.fetchval("SELECT 1")
+                    healthy = True
+                except Exception:
+                    healthy = False
+            return PluginHealth(
+                status=PluginStatus.READY if healthy else PluginStatus.FAILED,
+                message="" if healthy else "ping() returned False",
+            )
+        except Exception as exc:
+            return PluginHealth(
+                status=PluginStatus.FAILED,
+                message=str(exc),
+            )
+
+    def get_repository(self) -> PostgresRepository:
+        """
+        Return the initialized repository.
+
+        Only valid after registry.initialize_all() has been called.
+
+        Raises:
+            RuntimeError: Plugin not yet initialized.
+        """
+        if self._status != PluginStatus.READY:
+            raise RuntimeError(
+                f"PostgresPlugin is not ready (status: {self._status.name}). "
+                "Call await registry.initialize_all() first."
+            )
+        if self._repo is None:
+            raise RuntimeError(
+                "PostgresPlugin was initialized without a table name. "
+                "Pass table=... to PostgresPlugin() to enable get_repository()."
+            )
+        return self._repo

openframe_adapters_db_postgres-1.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openframe-adapters-db-postgres"
+version = "1.2.0"
+description = "OpenFrame Microservice Suite — PostgreSQL database adapter."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["openframe", "postgres", "asyncpg", "hexagonal", "microservice"]
+dependencies = [
+    "openframe-core>=2.0,<3",
+    "asyncpg>=0.29",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-mock>=3.14",
+]
+
+[[project.authors]]
+name = "Furious Meteors Engineering"
+email = "engineering@furiousmeteors.dev"
+
+[[project.maintainers]]
+name = "Furious Meteors Engineering"
+email = "engineering@furiousmeteors.dev"
+
+[project.urls]
+Homepage      = "https://github.com/Furious-Meteors/openframe-adapters"
+Documentation = "https://furious-meteors.github.io/openframe-adapters/"
+Repository    = "https://github.com/Furious-Meteors/openframe-adapters"
+Changelog     = "https://github.com/Furious-Meteors/openframe-adapters/blob/production/.github/CHANGELOG.md"
+"Bug Tracker" = "https://github.com/Furious-Meteors/openframe-adapters/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["openframe"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+

{openframe_adapters_db_postgres-1.0.0 → openframe_adapters_db_postgres-1.2.0}/tests/conftest.py

@@ -1,7 +1,8 @@
 """
-tests/conftest.py
-==================
-Shared pytest fixtures for openframe-adapters-db-postgres.
+tests/conftest.py — openframe-adapters-db-postgres
+=====================================================
+OTel reset fixtures are provided by openframe.core.testing.fixtures.
+This file contains only adapter-specific fixtures.
 
 All tests run with zero network calls. asyncpg is mocked at the
 ``openframe.adapters.db.postgres.connection`` import level so no real
@@ -9,6 +10,11 @@ Postgres server is needed.
 """
 from __future__ import annotations
 
+# Canonical OTel reset fixtures from openframe-core v2.0.
+# Provides (autouse): reset_telemetry_state
+# Provides (on-demand): span_exporter, metric_reader
+from openframe.core.testing.fixtures import *  # noqa: F401, F403
+
 import pytest
 from unittest.mock import AsyncMock, MagicMock
 

openframe_adapters_db_postgres-1.2.0/tests/test_plugin.py

@@ -0,0 +1,244 @@
+"""
+tests/test_plugin.py — openframe-adapters-db-postgres
+========================================================
+Tests for PostgresPlugin: protocol conformance, lifecycle, and health.
+"""
+from __future__ import annotations
+
+import pytest
+
+from openframe.adapters.db.postgres import PostgresPlugin, PostgresRepository, PostgresSettings
+from openframe.core.plugins import OpenFramePlugin, PluginContext, PluginStatus
+
+
+@pytest.fixture
+def settings():
+    """A PostgresSettings instance with dummy connection details."""
+    return PostgresSettings(
+        database_url="postgresql://test:test@localhost/test"
+    )
+
+
+@pytest.fixture
+def plugin(settings):
+    """An uninitialized PostgresPlugin pre-configured for the 'items' table."""
+    return PostgresPlugin(settings, table="items")
+
+
+@pytest.fixture
+def plugin_context():
+    """A minimal PluginContext for tests."""
+    return PluginContext(
+        config={},
+        plugin_name="openframe-postgres",
+    )
+
+
+# ── Protocol conformance ───────────────────────────────────────────────────
+
+def test_postgres_plugin_satisfies_openframe_plugin_protocol(plugin):
+    """PostgresPlugin must satisfy the OpenFramePlugin runtime-checkable Protocol."""
+    assert isinstance(plugin, OpenFramePlugin)
+
+
+def test_postgres_plugin_name(plugin):
+    assert plugin.name == "openframe-postgres"
+
+
+def test_postgres_plugin_version(plugin):
+    assert plugin.version == "1.2.0"
+
+
+def test_postgres_plugin_capability(plugin):
+    assert plugin.capability == "persistence"
+
+
+# ── Lifecycle ──────────────────────────────────────────────────────────────
+
+async def test_initialize_succeeds_when_ping_returns_true(
+    plugin, plugin_context, mock_pool, mock_settings
+):
+    """Successful pool creation + ping → status READY."""
+    import openframe.adapters.db.postgres.connection as conn_module
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1  # ping SELECT 1
+
+    plugin._settings = mock_settings
+    await plugin.initialize(plugin_context)
+
+    assert plugin._status == PluginStatus.READY
+    conn_module._pool_cache.clear()
+
+
+async def test_initialize_fails_when_ping_raises(
+    plugin, plugin_context, mock_pool, mock_settings
+):
+    """Ping raising an exception → status FAILED, AdapterConnectionError propagated."""
+    import openframe.adapters.db.postgres.connection as conn_module
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.side_effect = Exception("connection refused")
+
+    plugin._settings = mock_settings
+    from openframe.core.exceptions import AdapterConnectionError
+    with pytest.raises((AdapterConnectionError, Exception)):
+        await plugin.initialize(plugin_context)
+
+    assert plugin._status == PluginStatus.FAILED
+    conn_module._pool_cache.clear()
+
+
+async def test_shutdown_never_raises_when_repo_is_none(plugin):
+    """shutdown() must not raise even if repo was never set."""
+    plugin._repo = None
+    await plugin.shutdown()
+    assert plugin._status == PluginStatus.STOPPED
+
+
+async def test_shutdown_sets_status_stopped(plugin, mock_pool, mock_settings, plugin_context):
+    """shutdown() always transitions to STOPPED."""
+    import openframe.adapters.db.postgres.connection as conn_module
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1
+    plugin._settings = mock_settings
+    await plugin.initialize(plugin_context)
+
+    await plugin.shutdown()
+    assert plugin._status == PluginStatus.STOPPED
+    conn_module._pool_cache.clear()
+
+
+async def test_get_repository_raises_before_initialize(plugin):
+    """get_repository() must raise RuntimeError when plugin is not READY."""
+    with pytest.raises(RuntimeError, match="not ready"):
+        plugin.get_repository()
+
+
+async def test_get_repository_returns_instance_after_initialize(
+    plugin, plugin_context, mock_pool, mock_settings
+):
+    """get_repository() returns a PostgresRepository after successful init."""
+    import openframe.adapters.db.postgres.connection as conn_module
+    from openframe.adapters.db.postgres import PostgresRepository
+
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1
+    plugin._settings = mock_settings
+    await plugin.initialize(plugin_context)
+
+    repo = plugin.get_repository()
+    assert isinstance(repo, PostgresRepository)
+    conn_module._pool_cache.clear()
+
+
+# ── Health ─────────────────────────────────────────────────────────────────
+
+async def test_health_returns_failed_when_not_initialized(plugin):
+    """health() before initialize() → FAILED status."""
+    health = await plugin.health()
+    assert health.status == PluginStatus.FAILED
+
+
+async def test_health_never_raises(plugin):
+    """health() must never raise — even with a None repo."""
+    plugin._repo = None
+    result = await plugin.health()
+    assert result is not None
+    assert result.status == PluginStatus.FAILED
+
+
+async def test_health_returns_ready_after_initialize(
+    plugin, plugin_context, mock_pool, mock_settings
+):
+    """health() after successful init with ping returning True → READY."""
+    import openframe.adapters.db.postgres.connection as conn_module
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1
+    plugin._settings = mock_settings
+    await plugin.initialize(plugin_context)
+
+    health = await plugin.health()
+    assert health.status == PluginStatus.READY
+    conn_module._pool_cache.clear()
+
+
+async def test_health_returns_failed_when_ping_fails(
+    plugin, plugin_context, mock_pool, mock_settings
+):
+    """health() when ping returns False → FAILED status, no exception raised."""
+    import openframe.adapters.db.postgres.connection as conn_module
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1
+    plugin._settings = mock_settings
+    await plugin.initialize(plugin_context)
+
+    # Now make ping fail for health check
+    mock_pool.fetchval.side_effect = Exception("db gone")
+    result = await plugin.health()
+    assert result is not None
+    assert result.status == PluginStatus.FAILED
+    conn_module._pool_cache.clear()
+
+
+# ── repository_class parameter ─────────────────────────────────────────────
+
+def test_plugin_defaults_to_base_repository_class(settings):
+    """Backwards compatibility — no repository_class passed."""
+    plugin = PostgresPlugin(settings, table="items")
+    assert plugin._repository_class is PostgresRepository
+
+
+def test_plugin_accepts_custom_repository_class(settings):
+    class CustomRepo(PostgresRepository):
+        pass
+
+    plugin = PostgresPlugin(settings, table="items", repository_class=CustomRepo)
+    assert plugin._repository_class is CustomRepo
+
+
+def test_plugin_rejects_non_repository_class(settings):
+    """repository_class must be a subclass of PostgresRepository — TypeError if not."""
+    with pytest.raises(TypeError, match="subclass of PostgresRepository"):
+        PostgresPlugin(settings, table="items", repository_class=object)  # type: ignore[arg-type]
+
+
+async def test_initialize_constructs_custom_repository_class(
+    settings, plugin_context, mock_pool, mock_settings
+):
+    """
+    REGRESSION: plugin always constructed the base class, silently discarding
+    domain subclass overrides of entity mapping methods.
+    """
+    import openframe.adapters.db.postgres.connection as conn_module
+
+    class CustomRepo(PostgresRepository):
+        marker = True
+
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1
+
+    plugin = PostgresPlugin(mock_settings, table="items", repository_class=CustomRepo)
+    await plugin.initialize(plugin_context)
+
+    repo = plugin.get_repository()
+    assert isinstance(repo, CustomRepo)
+    assert hasattr(repo, "marker")
+    conn_module._pool_cache.clear()
+
+
+async def test_get_repository_returns_subclass_not_base_class(
+    settings, plugin_context, mock_pool, mock_settings
+):
+    """type(repo) must be the subclass, not just isinstance-compatible."""
+    import openframe.adapters.db.postgres.connection as conn_module
+
+    class CustomRepo(PostgresRepository):
+        pass
+
+    conn_module._pool_cache[mock_settings.database_url] = mock_pool
+    mock_pool.fetchval.return_value = 1
+
+    plugin = PostgresPlugin(mock_settings, table="items", repository_class=CustomRepo)
+    await plugin.initialize(plugin_context)
+
+    assert type(plugin.get_repository()) is CustomRepo
+    conn_module._pool_cache.clear()

{openframe_adapters_db_postgres-1.0.0 → openframe_adapters_db_postgres-1.2.0}/tests/test_repository.py

@@ -1,7 +1,8 @@
 """
-tests/test_repository.py
-==========================
-Unit tests for PostgresRepository CRUD operations and Protocol conformance.
+tests/test_repository.py — openframe-adapters-db-postgres
+===========================================================
+Contract tests (RepositoryContractTests) run first, then adapter-specific
+unit tests covering PostgreSQL error mapping and driver behaviour.
 """
 from __future__ import annotations
 
@@ -13,6 +14,103 @@ from openframe.adapters.db.postgres import PostgresRepository
 from openframe.core.exceptions import AdapterConfigurationError, AdapterQueryError, AdapterTimeoutError
 from openframe.core.health import HealthCheck
 from openframe.core.ports import BaseRepository
+from openframe.core.testing import RepositoryContractTests
+
+
+# ── Contract tests — must pass for every BaseRepository implementation ─────
+
+class TestPostgresRepositoryContracts(RepositoryContractTests):
+    """
+    PostgresRepository passes the full openframe contract suite.
+
+    All 18 RepositoryContractTests run against a mocked asyncpg pool.
+    No real database required.
+    """
+
+    @pytest.fixture
+    def repository(self, mock_settings, mock_pool):
+        """
+        PostgresRepository backed by a stateful in-memory mock pool.
+
+        The mock pool tracks insertions, updates, and deletions so that the
+        RepositoryContractTests behavioural assertions (create → get, list
+        pagination, etc.) pass without a real database.
+        """
+        import re
+        from unittest.mock import AsyncMock
+
+        import openframe.adapters.db.postgres.connection as conn_module
+
+        conn_module._pool_cache[mock_settings.database_url] = mock_pool
+
+        # In-memory store that simulates the database table.
+        _store: dict[str, dict] = {}
+
+        def _fetchrow(query: str, *args):
+            q = query.upper()
+            if "INSERT" in q:
+                # Parse column list from: INSERT INTO tbl (col1, col2) VALUES ...
+                m = re.search(r"\(([^)]+)\)\s*VALUES", query, re.IGNORECASE)
+                cols = [c.strip() for c in m.group(1).split(",")] if m else []
+                row = dict(zip(cols, args))
+                _store[str(row.get("id", ""))] = row
+                return row
+            if "UPDATE" in q:
+                # Last arg is the WHERE id value.
+                entity_id = str(args[-1])
+                if entity_id not in _store:
+                    return None
+                # Parse SET columns: UPDATE tbl SET col=$1,... WHERE id=$N
+                m = re.search(r"SET\s+(.+?)\s+WHERE", query, re.IGNORECASE)
+                set_cols = (
+                    [p.strip().split("=")[0].strip() for p in m.group(1).split(",")]
+                    if m
+                    else []
+                )
+                row = dict(_store[entity_id])
+                for i, col in enumerate(set_cols):
+                    row[col] = args[i]
+                _store[entity_id] = row
+                return row
+            # SELECT — first arg is entity_id.
+            entity_id = str(args[0]) if args else ""
+            return _store.get(entity_id)
+
+        def _execute(query: str, *args):
+            if "DELETE" in query.upper():
+                entity_id = str(args[0]) if args else ""
+                if entity_id in _store:
+                    del _store[entity_id]
+                    return "DELETE 1"
+                return "DELETE 0"
+            return ""
+
+        def _conn_fetch(query: str, limit: int, offset: int):
+            items = list(_store.values())
+            return items[offset : offset + limit]
+
+        def _conn_fetchval(query: str):
+            return len(_store)
+
+        mock_pool.fetchrow = AsyncMock(side_effect=_fetchrow)
+        mock_pool.execute = AsyncMock(side_effect=_execute)
+        mock_pool.fetchval = AsyncMock(return_value=1)  # ping / is_ready
+        conn = mock_pool.acquire.return_value
+        conn.fetch = AsyncMock(side_effect=_conn_fetch)
+        conn.fetchval = AsyncMock(side_effect=_conn_fetchval)
+
+        r = PostgresRepository(mock_settings, table="items", id_column="id")
+        yield r
+        conn_module._pool_cache.clear()
+
+    @pytest.fixture
+    def make_entity(self):
+        def _make(id: str, name: str = "test") -> dict:
+            return {"id": id, "name": name}
+        return _make
+
+
+# ── Adapter-specific tests — beyond what the contract covers ───────────────
 
 
 # ---------------------------------------------------------------------------

openframe_adapters_db_postgres-1.0.0/pyproject.toml

@@ -1,30 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "openframe-adapters-db-postgres"
-version = "1.0.0"
-description = "OpenFrame Microservice Suite — PostgreSQL database adapter."
-readme = "README.md"
-requires-python = ">=3.11"
-license = { text = "MIT" }
-keywords = ["openframe", "postgres", "asyncpg", "hexagonal", "microservice"]
-dependencies = [
-    "openframe-core>=1.0,<2",
-    "asyncpg>=0.29",
-]
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=8.0",
-    "pytest-asyncio>=0.23",
-    "pytest-mock>=3.14",
-]
-
-[tool.hatch.build.targets.wheel]
-packages = ["openframe"]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]