openframe-adapters-db-cockroachdb 0.1.0__py3-none-any.whl

openframe/adapters/db/cockroachdb/__init__.py

@@ -0,0 +1,58 @@
+"""
+openframe.adapters.db.cockroachdb
+====================================
+CockroachDB database adapter for the OpenFrame Microservice Suite.
+
+CockroachDB speaks the PostgreSQL wire protocol, so this package uses the
+same ``asyncpg`` driver as ``openframe-adapters-db-postgres`` and shares its
+connection pooling and exception-classification design. See
+``repository.py``'s module docstring and this package's README for the real
+SQL-dialect and transaction-semantics differences from Postgres that matter
+at this adapter's boundary (no ``SERIAL``, default ``SERIALIZABLE``
+isolation with client-side retry requirements for explicit multi-statement
+transactions).
+
+Public API:
+
+    CockroachdbSettings    — Pydantic Settings subclass for connection config.
+    CockroachdbRepository  — Generic async repository (BaseRepository).
+    get_cockroachdb_pool   — Async factory that creates / returns the cached pool.
+
+Quick start::
+
+    from openframe.adapters.db.cockroachdb import (
+        CockroachdbSettings,
+        CockroachdbRepository,
+        get_cockroachdb_pool,
+    )
+
+    settings = CockroachdbSettings(cockroachdb_url="postgresql://user:pw@localhost:26257/db")
+
+    # Raw dict mode
+    repo = CockroachdbRepository(settings, table="items", id_column="id")
+    item = await repo.get("abc-123")           # dict | None
+
+    # Typed mode — subclass and override mapping methods
+    class ItemRepository(CockroachdbRepository[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 CockroachdbSettings
+from .connection import get_cockroachdb_pool
+from .plugin import CockroachdbPlugin
+from .repository import CockroachdbRepository
+
+__all__ = [
+    "CockroachdbSettings",
+    "CockroachdbRepository",
+    "get_cockroachdb_pool",
+    "CockroachdbPlugin",
+]

openframe/adapters/db/cockroachdb/config.py

@@ -0,0 +1,70 @@
+"""
+openframe/adapters/db/cockroachdb/config.py
+=============================================
+CockroachDB 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.
+
+CockroachDB speaks the PostgreSQL wire protocol, so this adapter uses the
+same ``asyncpg`` driver as ``openframe-adapters-db-postgres``. The DSN
+scheme is still ``postgresql://`` — asyncpg has no notion of "CockroachDB"
+as a distinct backend, it only ever knows it is talking wire-protocol
+Postgres. Point the URL at a CockroachDB node/load balancer the same way
+you would a Postgres primary.
+
+Required env vars:
+    COCKROACHDB_URL: Full asyncpg DSN pointed at a CockroachDB cluster.
+                      Format: postgresql://user:pass@host:port/dbname
+                      SSL:    postgresql://user:pass@host:26257/dbname?sslmode=verify-full
+
+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
+    COCKROACHDB_ADAPTER_NAME:        str   = "cockroachdb"
+"""
+from __future__ import annotations
+
+from openframe.core.config import BaseAdapterSettings
+
+__all__ = ["CockroachdbSettings"]
+
+
+class CockroachdbSettings(BaseAdapterSettings):
+    """
+    Settings for the CockroachDB adapter.
+
+    All fields read from environment variables. Missing required fields raise
+    ``pydantic_core.ValidationError`` at instantiation time.
+
+    Inherits from ``BaseAdapterSettings``:
+        adapter_name:       str   = "cockroachdb"  (overrides base default)
+        connection_timeout: float = 30.0
+        operation_timeout:  float = 10.0
+        max_retries:        int   = 3
+
+    Attributes:
+        cockroachdb_url:                  Full asyncpg DSN pointed at a
+                                          CockroachDB cluster (required). The
+                                          URL scheme is ``postgresql://`` —
+                                          asyncpg only speaks the wire
+                                          protocol, not a vendor name.
+        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.
+    """
+
+    cockroachdb_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 = "cockroachdb"

openframe/adapters/db/cockroachdb/connection.py

@@ -0,0 +1,138 @@
+"""
+openframe/adapters/db/cockroachdb/connection.py
+==================================================
+asyncpg connection pool factory and cache for CockroachDB.
+
+CockroachDB speaks the PostgreSQL wire protocol, so this module is
+byte-for-byte the same pooling strategy as
+``openframe-adapters-db-postgres``'s ``connection.py`` — same driver
+(``asyncpg``), same pool-creation call shape, same exception hierarchy.
+
+``get_cockroachdb_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 ``cockroachdb_url`` AND the
+same pool-relevant settings (``pool_size``, ``pool_max_inactive_conn_lifetime``,
+``pool_command_timeout``, ``pool_max_queries``). Multiple
+``CockroachdbRepository`` instances constructed with matching settings share
+the same pool.
+
+Pool cache: ``_pool_cache`` is a module-level dict keyed by
+``(cockroachdb_url, pool-config-tuple)`` — not the URL alone. Two
+``CockroachdbSettings`` instances with the same ``cockroachdb_url`` but
+different pool sizing get two distinct pools, rather than the second one
+silently inheriting the first one's configuration (the bug this key shape
+fixes — the same live bug found in the Postgres/Mongo/Redis adapters before
+the ecosystem-wide checklist existed).
+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 CockroachdbSettings
+
+__all__ = ["get_cockroachdb_pool", "_pool_cache", "_cache_key"]
+
+_PoolCacheKey = tuple[str, tuple[int, float, float, int]]
+
+_pool_cache: dict[_PoolCacheKey, asyncpg.Pool] = {}  # type: ignore[type-arg]
+
+
+def _cache_key(settings: CockroachdbSettings) -> _PoolCacheKey:
+    """
+    Cache key covering the URL plus every pool-shape setting.
+
+    Two ``CockroachdbSettings`` for the same ``cockroachdb_url`` but
+    different pool sizing must not share a pool — a shared key here would
+    mean the second caller silently gets the first caller's pool
+    configuration.
+    """
+    return (
+        settings.cockroachdb_url,
+        (
+            settings.pool_size,
+            settings.pool_max_inactive_conn_lifetime,
+            settings.pool_command_timeout,
+            settings.pool_max_queries,
+        ),
+    )
+
+
+async def get_cockroachdb_pool(settings: CockroachdbSettings) -> asyncpg.Pool:  # type: ignore[type-arg]
+    """
+    Create or return the cached asyncpg connection pool.
+
+    Creates the pool on first call for a given ``(cockroachdb_url, pool
+    config)`` pair. Subsequent calls with matching URL and pool settings
+    return the cached pool without re-connecting. A different pool
+    configuration for the same URL gets its own pool rather than reusing
+    the first one's.
+
+    Args:
+        settings: A fully-validated ``CockroachdbSettings`` instance.
+
+    Returns:
+        An ``asyncpg.Pool`` that is ready to use.
+
+    Raises:
+        AdapterConnectionError:    Pool creation failed — host unreachable,
+                                   bad credentials, TLS error, etc.
+        AdapterConfigurationError: ``COCKROACHDB_URL`` is syntactically
+                                   invalid (``asyncpg.InvalidCatalogNameError``).
+        AdapterTimeoutError:       Pool creation exceeded
+                                   ``settings.connection_timeout``.
+    """
+    url = settings.cockroachdb_url
+    key = _cache_key(settings)
+    if key in _pool_cache:
+        return _pool_cache[key]
+
+    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"COCKROACHDB_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 CockroachDB at {url!r}: {exc}",
+            adapter=settings.adapter_name,
+            operation="connect",
+            cause=exc,
+        ) from exc
+
+    _pool_cache[key] = pool
+    return pool

openframe/adapters/db/cockroachdb/plugin.py

@@ -0,0 +1,240 @@
+"""
+openframe/adapters/db/cockroachdb/plugin.py
+==============================================
+OpenFrame plugin wrapper for CockroachdbRepository.
+
+Stability: beta
+
+Recommended usage — ApplicationBootstrap.compose() (openframe-core>=3.3)::
+
+    from openframe.core.runtime import ApplicationBootstrap
+    from openframe.core.ports import Capability
+    from openframe.adapters.db.cockroachdb import CockroachdbPlugin, CockroachdbSettings
+
+    plugin = CockroachdbPlugin(CockroachdbSettings(), table="items", id_column="id")
+
+    async with ApplicationBootstrap.compose(plugin) as app:
+        repo = app.get(Capability.PERSISTENCE)
+        item = await repo.get("abc-123")
+    # plugin.shutdown() ran automatically on exit
+
+Use a subclassed ApplicationBootstrap (configure()) instead when you need
+per-port config=/init_timeout= or conditional registration order, and
+app.registry (PluginRegistry escape hatch) only for what neither tier
+covers.
+
+For tests, scripts, or anywhere plugin lifecycle management isn't needed,
+construct CockroachdbRepository directly (no plugin required)::
+
+    repo = CockroachdbRepository(CockroachdbSettings())
+    traced = TracingProxy(repo, prefix="repository.item")
+"""
+# Capability: "persistence"
+# See capability taxonomy:
+# https://furious-meteors.github.io/openframe-core/developer-guide/how-it-works/#choosing-a-wiring-pattern
+from __future__ import annotations
+
+import logging
+
+from openframe.core.ports import BasePort, Capability, PluginContext, PluginHealth, PluginStatus
+from openframe.core.exceptions import AdapterConnectionError
+
+from openframe.adapters.db.cockroachdb.config import CockroachdbSettings
+from openframe.adapters.db.cockroachdb.connection import _pool_cache, get_cockroachdb_pool
+from openframe.adapters.db.cockroachdb.repository import CockroachdbRepository
+
+__all__ = ["CockroachdbPlugin"]
+
+_logger = logging.getLogger(__name__)
+
+
+class CockroachdbPlugin(BasePort):
+    """
+    CockroachDB adapter plugin for the OpenFrame plugin registry.
+
+    Capability: "persistence"
+
+    Stability: beta
+
+    Lifecycle:
+        initialize() — creates the asyncpg connection pool and verifies
+                       connectivity via the repository's health(). Raises
+                       AdapterConnectionError if the database is unreachable.
+        shutdown()   — closes the connection pool. Never raises.
+        health()     — delegates to the repository's health() and returns
+                       its PluginHealth. Never raises.
+
+    The plugin exposes get_repository() after initialization for use
+    in the composition root or ApplicationBootstrap.
+
+    By default constructs a plain CockroachdbRepository. To use a
+    domain-specific subclass, pass it via repository_class::
+
+        registry.register(CockroachdbPlugin(
+            CockroachdbSettings(),
+            table="items",
+            id_column="id",
+            repository_class=ItemCockroachdbRepository,
+        ))
+    """
+
+    name:       str = "openframe-cockroachdb"
+    version:    str = "0.1.0"
+    capability: Capability = Capability.PERSISTENCE
+
+    def __init__(
+        self,
+        settings: CockroachdbSettings,
+        table: str = "",
+        id_column: str = "id",
+        repository_class: type[CockroachdbRepository] = CockroachdbRepository,
+    ) -> None:
+        """
+        Args:
+            settings:         CockroachdbSettings 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 CockroachdbRepository subclass to construct.
+                              Defaults to the base CockroachdbRepository. Pass a
+                              domain-specific subclass here to get proper
+                              entity mapping through get_repository().
+
+        Raises:
+            TypeError: repository_class is not a subclass of CockroachdbRepository.
+        """
+        if not (isinstance(repository_class, type) and issubclass(repository_class, CockroachdbRepository)):
+            raise TypeError(
+                f"repository_class must be a subclass of CockroachdbRepository, "
+                f"got {repository_class!r}"
+            )
+        self._settings = settings
+        self._table = table
+        self._id_column = id_column
+        self._repository_class = repository_class
+        self._repo: CockroachdbRepository | None = None
+        self._status = PluginStatus.REGISTERED
+
+    async def initialize(self, context: PluginContext) -> None:
+        """
+        Initialize the CockroachDB connection pool and verify connectivity.
+
+        If a ``table`` was passed to the constructor, a
+        :class:`CockroachdbRepository` is created and connectivity is
+        verified via ``repo.health()``. 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: CockroachDB is unreachable or credentials
+                                    are invalid.
+            AdapterConfigurationError: COCKROACHDB_URL is malformed.
+        """
+        self._status = PluginStatus.INITIALIZED
+        try:
+            pool = await get_cockroachdb_pool(self._settings)
+            if self._table:
+                self._repo = self._repository_class(
+                    self._settings,
+                    table=self._table,
+                    id_column=self._id_column,
+                )
+                health = await self._repo.health()
+                if health.status != PluginStatus.READY:
+                    raise AdapterConnectionError(
+                        health.message or "CockroachDB health check failed after pool creation",
+                        adapter="cockroachdb",
+                        operation="initialize",
+                    ) from None
+            else:
+                # Verify pool connectivity without requiring a table.
+                try:
+                    await pool.fetchval("SELECT 1")
+                except Exception as exc:
+                    raise AdapterConnectionError(
+                        f"CockroachDB connectivity check failed: {exc}",
+                        adapter="cockroachdb",
+                        operation="initialize",
+                    ) from exc
+            self._status = PluginStatus.READY
+            _logger.info(
+                "CockroachdbPlugin initialized — %s (repository_class=%s)",
+                self._settings.cockroachdb_url.split("@")[-1],
+                self._repository_class.__name__,
+            )
+        except Exception:
+            self._status = PluginStatus.FAILED
+            raise
+
+    async def shutdown(self) -> None:
+        """
+        Close the CockroachDB 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("CockroachdbPlugin shutdown complete.")
+        except Exception as exc:
+            _logger.error("CockroachdbPlugin shutdown error (ignored): %s", exc)
+        finally:
+            self._status = PluginStatus.STOPPED
+
+    async def health(self) -> PluginHealth:
+        """
+        Return current health snapshot.
+
+        Delegates to the repository's own ``health()`` when one exists — no
+        translation needed, it already returns a ``PluginHealth``. When the
+        plugin was constructed without a table (connection-manager-only
+        mode, no repository), the pool is checked directly.
+
+        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:
+                return await self._repo.health()
+            # No repository — check the pool directly.
+            try:
+                pool = await get_cockroachdb_pool(self._settings)
+                await pool.fetchval("SELECT 1")
+                return PluginHealth(status=PluginStatus.READY, message="")
+            except Exception as exc:
+                return PluginHealth(status=PluginStatus.FAILED, message=str(exc))
+        except Exception as exc:
+            return PluginHealth(
+                status=PluginStatus.FAILED,
+                message=str(exc),
+            )
+
+    def get_repository(self) -> CockroachdbRepository:
+        """
+        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"CockroachdbPlugin is not ready (status: {self._status.name}). "
+                "Call await registry.initialize_all() first."
+            )
+        if self._repo is None:
+            raise RuntimeError(
+                "CockroachdbPlugin was initialized without a table name. "
+                "Pass table=... to CockroachdbPlugin() to enable get_repository()."
+            )
+        return self._repo

openframe/adapters/db/cockroachdb/repository.py

@@ -0,0 +1,503 @@
+"""
+openframe/adapters/db/cockroachdb/repository.py
+==================================================
+Generic CockroachDB repository implementing ``BaseRepository[T]``
+from ``openframe-core`` via structural subtyping.
+
+CockroachDB speaks the PostgreSQL wire protocol and this adapter uses the
+same ``asyncpg`` driver as ``openframe-adapters-db-postgres`` — connection
+pooling, the asyncpg exception hierarchy used for connection-vs-query
+classification, and health checks (``SELECT 1``) are all identical.
+
+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 = CockroachdbRepository(settings, table="items", id_column="id")
+    item: dict | None = await repo.get("abc-123")
+
+Usage — typed domain mode (subclass):
+
+    class ItemRepository(CockroachdbRepository[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)
+
+--------------------------------------------------------------------------
+CockroachDB/Postgres schema differences — READ BEFORE DESIGNING A SCHEMA
+--------------------------------------------------------------------------
+
+1. **No ``SERIAL``/``BIGSERIAL``.** CockroachDB does not implement
+   Postgres's ``SERIAL``/``BIGSERIAL`` auto-increment column types the same
+   way (it accepts the syntax for compatibility in some versions but the
+   underlying generation strategy is different and not guaranteed to behave
+   like Postgres's sequence-backed columns). The idiomatic CockroachDB
+   primary-key patterns are:
+
+       id UUID PRIMARY KEY DEFAULT gen_random_uuid()
+       -- or --
+       id INT PRIMARY KEY DEFAULT unique_rowid()
+
+   If your schema uses ``SERIAL`` against a real CockroachDB cluster, do not
+   assume it behaves like Postgres — verify the actual column definition
+   CockroachDB creates. This adapter does not translate or rewrite DDL; it
+   only issues the DML your repository methods construct (``INSERT``,
+   ``SELECT``, ``UPDATE``, ``DELETE``) against whatever schema already
+   exists.
+
+2. **Default ``SERIALIZABLE`` isolation and client-side transaction
+   retries.** CockroachDB always runs at ``SERIALIZABLE`` isolation. Under
+   contention it can raise a retryable "transaction retry error" — SQLSTATE
+   ``40001``, with ``restart transaction`` in the message — that requires
+   the *client* to retry the entire transaction, not just the failing
+   statement. See this package's README ("CockroachDB transaction retries")
+   for the full explanation and why this adapter does not implement
+   automatic retry internally.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Generic, TypeVar
+
+import asyncpg
+
+from openframe.core.exceptions import (
+    AdapterConfigurationError,
+    AdapterConnectionError,
+    AdapterQueryError,
+    AdapterTimeoutError,
+)
+from openframe.core.ports import BaseRepository, Capability, PluginContext, PluginHealth, PluginStatus
+
+from .config import CockroachdbSettings
+from .connection import _cache_key, _pool_cache, get_cockroachdb_pool
+
+__all__ = ["CockroachdbRepository"]
+
+T = TypeVar("T")
+
+# asyncpg exceptions that indicate a broken/lost connection rather than a
+# query-level failure. Raised mid-query (e.g. the connection drops while a
+# statement is in flight), distinct from the connect-time errors handled in
+# connection.get_cockroachdb_pool(). Identical hierarchy to the Postgres
+# adapter — same driver, same wire protocol.
+_CONNECTION_ERRORS = (
+    asyncpg.ConnectionDoesNotExistError,
+    asyncpg.ConnectionFailureError,
+    asyncpg.InterfaceError,
+    asyncpg.TooManyConnectionsError,
+)
+
+
+class CockroachdbRepository(Generic[T]):
+    """
+    Generic CockroachDB repository.
+
+    Implements ``BaseRepository[T]`` structurally — no
+    inheritance from the Protocol. All asyncpg exceptions are caught and
+    re-raised as ``AdapterError`` subclasses. Every operation wraps its
+    asyncpg call in ``asyncio.timeout(settings.operation_timeout)``.
+
+    Health check: ``health()`` is the sole health check on this repository.
+    It verifies backend connectivity and returns a ``PluginHealth``
+    snapshot describing the result — never raises.
+
+    Note on primary keys: if a subclass's schema was designed for Postgres
+    and uses ``SERIAL``/``BIGSERIAL``, see the module docstring above —
+    CockroachDB's idiomatic equivalent is
+    ``UUID PRIMARY KEY DEFAULT gen_random_uuid()`` or
+    ``INT PRIMARY KEY DEFAULT unique_rowid()``.
+
+    Note on transactions: each of ``get``/``list``/``create``/``update``/
+    ``delete`` executes as an implicit single-statement transaction, so
+    CockroachDB's SQLSTATE ``40001`` "transaction retry" errors are rare in
+    practice for these methods. A caller doing explicit multi-statement
+    transactions via raw asyncpg access (``pool.acquire()`` + manual
+    ``BEGIN``/``COMMIT``) needs to implement their own retry loop around
+    that SQLSTATE — see the README's "CockroachDB transaction retries"
+    section. This adapter does not retry automatically.
+
+    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 ``CockroachdbSettings`` 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"
+
+    name:       str = "openframe-cockroachdb-repository"
+    version:    str = "0.1.0"
+    capability: Capability = Capability.PERSISTENCE
+
+    def __init__(
+        self,
+        settings: CockroachdbSettings,
+        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(
+                "CockroachdbRepository 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)
+
+    # ------------------------------------------------------------------
+    # Exception mapping helper
+    # ------------------------------------------------------------------
+
+    def _wrap_asyncpg(
+        self, exc: Exception, operation: str
+    ) -> AdapterQueryError | AdapterConnectionError:
+        """
+        Map an ``asyncpg.PostgresError`` to the appropriate ``AdapterError``
+        subclass.
+
+        Distinguishes a lost/broken connection (``AdapterConnectionError`` —
+        retryable) from an in-band query failure such as a constraint
+        violation or a CockroachDB SQLSTATE 40001 transaction-retry error
+        (``AdapterQueryError`` — not retried automatically by this adapter;
+        see the module docstring and README for why). Same distinction
+        ``PostgresRepository``/``MongoRepository``/``RedisRepository``
+        already make. Caller must ``raise ... from exc`` at the call site.
+        """
+        if isinstance(exc, _CONNECTION_ERRORS):
+            return AdapterConnectionError(
+                f"{operation} failed — connection to CockroachDB was lost: {exc}",
+                adapter=self._settings.adapter_name,
+                operation=operation,
+                cause=exc,
+            )
+        return AdapterQueryError(
+            f"{operation} failed on {self._table}: {exc}",
+            adapter=self._settings.adapter_name,
+            operation=operation,
+            cause=exc,
+        )
+
+    # ------------------------------------------------------------------
+    # 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_cockroachdb_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, asyncpg.InterfaceError) as exc:
+            raise self._wrap_asyncpg(exc, "get") 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_cockroachdb_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, asyncpg.InterfaceError) as exc:
+            raise self._wrap_asyncpg(exc, "list") 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. ``gen_random_uuid()``/``unique_rowid()`` 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_cockroachdb_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, asyncpg.InterfaceError) as exc:
+            raise self._wrap_asyncpg(exc, "create") 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_cockroachdb_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, asyncpg.InterfaceError) as exc:
+            raise self._wrap_asyncpg(exc, "update") 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_cockroachdb_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, asyncpg.InterfaceError) as exc:
+            raise self._wrap_asyncpg(exc, "delete") from exc
+
+        # asyncpg returns "DELETE N" where N is the number of deleted rows.
+        return status == "DELETE 1"
+
+    # ------------------------------------------------------------------
+    # 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.
+        """
+        key = _cache_key(self._settings)
+        pool = _pool_cache.get(key)
+        if pool is not None:
+            await pool.close()
+            _pool_cache.pop(key, None)
+
+    # ------------------------------------------------------------------
+    # BasePort (Identity + Lifecycle) interface
+    # ------------------------------------------------------------------
+
+    async def initialize(self, context: PluginContext) -> None:
+        """
+        Establish the connection pool and verify connectivity.
+
+        BasePort lifecycle entry point. Reuses the same cached pool as
+        every other method on this repository.
+
+        Args:
+            context: Plugin context. Unused — settings are provided at
+                     construction time.
+
+        Raises:
+            AdapterConnectionError: CockroachDB is unreachable.
+        """
+        await get_cockroachdb_pool(self._settings)
+        health = await self.health()
+        if health.status != PluginStatus.READY:
+            raise AdapterConnectionError(
+                health.message or "CockroachDB connectivity check failed during initialize()",
+                adapter=self._settings.adapter_name,
+                operation="initialize",
+            )
+
+    async def shutdown(self) -> None:
+        """BasePort lifecycle entry point — alias for close(). Never raises."""
+        await self.close()
+
+    async def health(self) -> PluginHealth:
+        """
+        BasePort lifecycle entry point — returns a PluginHealth snapshot.
+
+        The sole connectivity check on this repository — a low-cost
+        ``SELECT 1`` against the pool with a 5-second timeout. Never raises.
+        """
+        try:
+            pool = await get_cockroachdb_pool(self._settings)
+            await asyncio.wait_for(pool.fetchval("SELECT 1"), timeout=5.0)
+            return PluginHealth(status=PluginStatus.READY, message="")
+        except Exception as exc:  # noqa: BLE001
+            return PluginHealth(status=PluginStatus.FAILED, message=str(exc))

openframe_adapters_db_cockroachdb-0.1.0.dist-info/METADATA

@@ -0,0 +1,340 @@
+Metadata-Version: 2.5
+Name: openframe-adapters-db-cockroachdb
+Version: 0.1.0
+Summary: OpenFrame Microservice Suite — CockroachDB 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,cockroachdb,hexagonal,microservice,openframe
+Requires-Python: >=3.11
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: openframe-core<4,>=3.3
+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-cockroachdb
+
+CockroachDB database adapter for the **OpenFrame Microservice Suite**.
+
+Part of the `openframe-adapters` monorepo. Implements `BaseRepository[T]` and
+`HealthCheck` from `openframe-core` using `asyncpg` — the same driver used by
+`openframe-adapters-db-postgres`, because CockroachDB speaks the PostgreSQL
+wire protocol. This package is an adaptation of the Postgres adapter, not a
+from-scratch build; see "CockroachDB vs. Postgres differences" below for
+everything that is genuinely different.
+
+---
+
+## Installation
+
+```bash
+pip install openframe-adapters-db-cockroachdb
+```
+
+Required env var:
+
+```
+COCKROACHDB_URL=postgresql://user:password@host:26257/dbname
+```
+
+Note the scheme is still `postgresql://` — asyncpg only speaks the wire
+protocol, it has no notion of "CockroachDB" as a distinct backend. Point the
+URL at your CockroachDB node or load balancer exactly as you would a
+Postgres primary.
+
+---
+
+## Quick start
+
+### Raw dict mode
+
+```python
+from openframe.adapters.db.cockroachdb import CockroachdbSettings, CockroachdbRepository
+
+settings = CockroachdbSettings()  # reads COCKROACHDB_URL from env
+repo = CockroachdbRepository(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.cockroachdb import CockroachdbSettings, CockroachdbRepository
+
+@dataclass
+class Item:
+    id: str
+    name: str
+
+class ItemRepository(CockroachdbRepository[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 = CockroachdbSettings()
+repo = ItemRepository(settings)
+item: Item | None = await repo.get("abc-123")
+```
+
+---
+
+## Wiring into an application
+
+For a real service, wire `CockroachdbPlugin` (the `BasePort`-satisfying
+plugin class) through `ApplicationBootstrap.compose()` from `openframe-core`.
+This gives you proper lifecycle management — `initialize()` / `health()` /
+`shutdown()` — for free, instead of constructing `CockroachdbRepository`
+directly and managing the pool yourself:
+
+```python
+from openframe.core.runtime import ApplicationBootstrap
+from openframe.core.ports import Capability
+from openframe.adapters.db.cockroachdb import CockroachdbPlugin, CockroachdbSettings
+
+settings = CockroachdbSettings()  # reads COCKROACHDB_URL from env
+plugin = CockroachdbPlugin(settings, table="items", id_column="id")
+
+async with ApplicationBootstrap.compose(plugin) as app:
+    repo = app.get(Capability.PERSISTENCE)   # -> CockroachdbRepository
+    item = await repo.get("abc-123")
+# pool is closed automatically on exit (plugin.shutdown() ran)
+```
+
+`compose()` calls `plugin.initialize()` on entry and `plugin.shutdown()` on
+exit, so the pool is created, health-checked, and torn down without any
+manual lifecycle code. Requires `openframe-core>=3.3`.
+
+Reach for a subclassed `ApplicationBootstrap` (with a `configure()` method)
+only when you need per-port `config=`/`init_timeout=` or conditional
+registration order; use `app.registry` as an escape hatch for anything
+neither tier covers. The `CockroachdbRepository(settings)` construction
+shown above under "Quick start" remains valid for tests, scripts, or any
+context that doesn't need plugin lifecycle management.
+
+---
+
+## Raw driver access for niche features
+
+The adapter never hides asyncpg. Access it directly for anything the port
+does not cover:
+
+```python
+from openframe.adapters.db.cockroachdb import get_cockroachdb_pool
+
+class OrderRepository(CockroachdbRepository[Order]):
+    _table     = "orders"
+    _id_column = "id"
+
+    async def bulk_upsert(self, orders: list[Order]) -> None:
+        pool = await get_cockroachdb_pool(self._settings)
+        async with pool.acquire() as conn:
+            async with conn.transaction():
+                for o in orders:
+                    await conn.execute(
+                        "UPSERT INTO orders (id, total) VALUES ($1, $2)",
+                        o.id, o.total,
+                    )
+```
+
+---
+
+## CockroachDB vs. Postgres differences
+
+CockroachDB speaks the same wire protocol as Postgres, so connection
+pooling, the asyncpg exception hierarchy used for connection-vs-query
+classification, and health checks (`SELECT 1`) are all identical to the
+Postgres adapter. Two real differences matter at the schema/transaction
+boundary:
+
+### No `SERIAL`/`BIGSERIAL`
+
+CockroachDB does not implement Postgres's `SERIAL`/`BIGSERIAL`
+auto-increment column types the same way. If your schema uses `SERIAL`
+against a real CockroachDB cluster, it likely will not behave as you
+expect. The idiomatic CockroachDB primary-key patterns are:
+
+```sql
+-- UUID primary key (recommended default)
+id UUID PRIMARY KEY DEFAULT gen_random_uuid()
+
+-- or, if you want an integer key
+id INT PRIMARY KEY DEFAULT unique_rowid()
+```
+
+This adapter does not translate or rewrite DDL — it only issues the DML
+your repository methods construct against whatever schema already exists.
+Design your `CREATE TABLE` statements with CockroachDB's own primary-key
+conventions, not a copy-pasted Postgres schema.
+
+### CockroachDB transaction retries (SQLSTATE 40001)
+
+CockroachDB always runs at `SERIALIZABLE` isolation (there is no lower
+isolation level to opt into). Under contention this can produce a
+retryable "transaction retry error" — SQLSTATE `40001`, with
+`restart transaction` in the error message — that requires the **client**
+to retry the *entire* transaction, not just the failing statement.
+
+This adapter's basic CRUD methods (`get`/`list`/`create`/`update`/`delete`)
+each execute as an implicit single-statement transaction, so this class of
+error is rare in practice for simple single-statement operations — there is
+no multi-statement transaction for CockroachDB to need to restart.
+
+However, if you use this package's "raw driver access" pattern (above) to
+run your **own** explicit multi-statement transaction via
+`conn.transaction()`, you are responsible for retrying it on SQLSTATE
+`40001`:
+
+```python
+import asyncpg
+
+async def transfer_funds(pool, from_id: str, to_id: str, amount: int) -> None:
+    for attempt in range(5):
+        try:
+            async with pool.acquire() as conn:
+                async with conn.transaction():
+                    await conn.execute(
+                        "UPDATE accounts SET balance = balance - $1 WHERE id = $2",
+                        amount, from_id,
+                    )
+                    await conn.execute(
+                        "UPDATE accounts SET balance = balance + $1 WHERE id = $2",
+                        amount, to_id,
+                    )
+            return
+        except asyncpg.PostgresError as exc:
+            if getattr(exc, "sqlstate", None) == "40001":
+                continue  # retry the whole transaction
+            raise
+    raise RuntimeError("transfer_funds: exhausted retries on SQLSTATE 40001")
+```
+
+This adapter deliberately does **not** implement automatic retry inside its
+own CRUD methods — that would be a surprising, undocumented behavior change
+from how the Postgres adapter behaves for the same driver calls. The
+difference is documented here so callers doing their own multi-statement
+transactions know it exists and can implement the retry loop themselves.
+
+Everything else about this adapter — connection pooling, asyncpg exception
+classification, health checks — is unchanged from the Postgres adapter.
+
+---
+
+## Configuration
+
+All settings are read from environment variables.
+
+| Env var | Type | Default | Description |
+|---|---|---|---|
+| `COCKROACHDB_URL` | `str` | **required** | Full asyncpg DSN (`postgresql://` scheme) pointed at a CockroachDB cluster |
+| `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
+
+`CockroachdbRepository` implements the `HealthCheck` protocol from `openframe-core`.
+
+```python
+health = await repo.health()   # PluginHealth snapshot — the sole health check, never raises
+```
+
+---
+
+## Exception hierarchy
+
+All exceptions are `AdapterError` subclasses from `openframe.core.exceptions`.
+Raw `asyncpg` exceptions never escape the adapter.
+
+| Situation | Exception |
+|---|---|
+| Cannot connect to CockroachDB | `AdapterConnectionError` |
+| Invalid `COCKROACHDB_URL` catalog | `AdapterConfigurationError` |
+| Query failed (constraint, syntax, SQLSTATE 40001, etc.) | `AdapterQueryError` |
+| Entity not found | `AdapterNotFoundError` |
+| Operation exceeded timeout | `AdapterTimeoutError` |
+
+A CockroachDB SQLSTATE `40001` transaction-retry error surfaces as
+`AdapterQueryError` like any other in-band query failure — see "CockroachDB
+transaction retries" above for why this adapter does not retry it
+automatically, and how to retry it yourself for explicit multi-statement
+transactions.
+
+---
+
+## Development
+
+```bash
+# from the package directory
+pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+---
+
+## Protocol conformance
+
+```python
+from openframe.core.ports import BaseRepository
+from openframe.core.health import HealthCheck
+
+repo = CockroachdbRepository(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.
+
+---
+
+## Resilience — circuit breaking under sustained failure
+
+`openframe-core>=3.4` ships `openframe.core.resilience.CircuitBreakerProxy` —
+wrap the repository to short-circuit calls after repeated failures instead
+of blocking every caller until `operation_timeout` during a sustained
+outage. No adapter code changes are needed to support this — it composes
+from the outside exactly like `TracingProxy`:
+
+```python
+from openframe.core.resilience import CircuitBreakerProxy
+from openframe.core.tracing import TracingProxy
+
+repo = CircuitBreakerProxy(
+    TracingProxy(app.get(Capability.PERSISTENCE).get_repository(), prefix="repository.item"),
+    failure_threshold=5,
+    reset_timeout=30.0,
+)
+```
+
+Wrap the traced repository, not the reverse — a short-circuited call never
+reaches the adapter, so it shouldn't produce a misleading adapter span.
+
+---
+
+## License
+
+MIT

openframe_adapters_db_cockroachdb-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+openframe/adapters/db/cockroachdb/__init__.py,sha256=iVReNvzfhWeOFHg7LxmVCP-X5D71wAvmv00N0ShtPW8,1991
+openframe/adapters/db/cockroachdb/config.py,sha256=3aEOjgsLJjrRTEwih1wj1_VJlrQ00oy0AYvWWuprXC4,3043
+openframe/adapters/db/cockroachdb/connection.py,sha256=8vh9t20_gaTBSFHATQ_fJTH4D4NmtWh5AKJ9vlPlluA,5250
+openframe/adapters/db/cockroachdb/plugin.py,sha256=eRj0mBPAUWr739FhOaJMeOT0zpa8jHTgUK7f7geXOvw,9608
+openframe/adapters/db/cockroachdb/repository.py,sha256=uTV29onz6mP8J4vZtl2YF1WLXSz37enOntWYuOPrfok,20360
+openframe_adapters_db_cockroachdb-0.1.0.dist-info/METADATA,sha256=UT-HLwUPNvCXwqQp3MjqeqYqJ6L-e_l0HkHwpbq9rMk,12087
+openframe_adapters_db_cockroachdb-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openframe_adapters_db_cockroachdb-0.1.0.dist-info/RECORD,,

openframe_adapters_db_cockroachdb-0.1.0.dist-info/WHEEL

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