hex-store-repository

Use when an aggregate is persisted on a nonrelational store — key-value, document or wide-column (redis, mongo, dynamo) — reached through an injected SDK client, or a derived index is kept beside the

SKILL.md

GitHub

Hex — Store Repository

Produces one repository class that adapts a domain repository protocol to a client-style datastore — any store reached through an injected SDK client rather than the shared relational bootstrap. That sentence is the whole selection rule: the store profile, not the vendor, decides that this skill applies.

A new vendor is its own infrastructure/<kind>/ package under this skill — never a fork of it (Rule 12). The pattern is fixed here (client injection, a fixed container token, record↔entity mapping, boundary translation via exception-catalog); the vendor rides in through three things and nothing else: the injected client type, the store's settings class and connection factory, and the SDK semantics that store documents. Key-value, document and wide-column stores are all one profile under that rule, and so is an index kept beside the authoritative store, which is why one skill serves them.

When to use vs. neighbours

  • The aggregate's store is the relational bootstrap store (SQLAlchemy/Postgres) → hex-persistence.
  • The protocol file (i_foo_repository.py) → hex-domain-ports.
  • A single-action ICan<Verb> port (not an aggregate's collection) → hex-capability-adapter.
  • The obligations a settings class meets (environment namespace, secrets, construction only at a composition root) → python-settings; the store's own settings class is shown here, beside the adapter that reads it.
  • The lifetime and declaration-order rules the repository's binding follows, and the base composition root it merges into → hex-wiring; the binding itself is shown here, beside the adapter.
  • Which store profile a datastore is, and the client factory that profile names → hex-conventions.
  • The catalogue exception an SDK error is translated into → exception-catalog.
  • The obligations any store's data access meets — where a driver error is translated and what its context carries, the pure mapping, which of them bind on a store with no transactions or schema → persistence.
  • An in-memory test stand-in for handler unit tests → hex-test-application-handler.
  • The integration contract test that drives this adapter against the real store → hex-test-repository-contract.

Template — redis-py, key-value form

One vendor is worked end to end so the shape is concrete; a document store (mongo, dynamo, a key-value cache) differs only in the SDK's call names and its exception root. The worked aggregate is Baz (hex-domain-model), a placeholder held by no other store, so the key-value store is its one authoritative store (rule 1). A key-value store answers only reads by key, so the adapter satisfies an IBazRepository that declares create, fetch by id and delete and nothing else (hex-domain-ports), and lives in redis/repositories/baz_repository.py (hex-conventions' protocol-derived stem).

import json
from uuid import UUID

from redis.asyncio import Redis
from redis.exceptions import RedisError

from myapp.domain.bazs import Baz
from myapp.domain.exceptions import NotFoundError, UpstreamError

__all__ = ["BazRepository"]

_KEY_PREFIX = "bazs"


def _key(id: UUID) -> str:
    return f"{_KEY_PREFIX}:{id}"


def _entity_to_record(baz: Baz) -> dict[str, str]:
    return {"id": str(baz.id), "name": baz.name}


def _record_to_entity(record: dict[str, str]) -> Baz:
    return Baz(id=UUID(record["id"]), name=record["name"])


class BazRepository:
    def __init__(self, client: Redis) -> None:
        self._client = client

    async def create(self, baz: Baz) -> None:
        try:
            await self._client.set(_key(baz.id), json.dumps(_entity_to_record(baz)))
        except RedisError as exc:
            raise UpstreamError(
                "store write failed",
                {"key": _key(baz.id)},
            ) from exc

    async def get_by_id(self, id: UUID) -> Baz:
        try:
            raw = await self._client.get(_key(id))
        except RedisError as exc:
            raise UpstreamError(
                "store read failed",
                {"key": _key(id)},
            ) from exc
        if raw is None:
            raise NotFoundError("Baz not found", {"id": str(id)})
        return _record_to_entity(json.loads(raw))

    async def delete(self, id: UUID) -> None:
        try:
            removed = await self._client.delete(_key(id))
        except RedisError as exc:
            raise UpstreamError(
                "store delete failed",
                {"key": _key(id)},
            ) from exc
        if removed == 0:
            raise NotFoundError("Baz not found", {"id": str(id)})

The key prefix is the adapter's container token, fixed in code (rule 5). The settings class the store's connection factory reads, in infrastructure/redis/redis_settings.py, follows python-settings; the URL is a secret because it carries the password.

from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict

__all__ = ["RedisSettings"]


class RedisSettings(BaseSettings):
    model_config = SettingsConfigDict(
        env_prefix="MYAPP_REDIS_",
        env_file=".env",  # only where the project keeps a dotenv file for development
        extra="ignore",
        hide_input_in_errors=True,
    )

    url: SecretStr

The connection factory, in infrastructure/redis/connection.py, is complete glue named for the datastore, never a stub (hex-conventions block B):

from redis.asyncio import Redis

from .redis_settings import RedisSettings

__all__ = ["create_baz_store_client"]


def create_baz_store_client(settings: RedisSettings) -> Redis:
    return Redis.from_url(settings.url.get_secret_value())

Another vendor changes the client class, its import and the constructor keywords, never the name or the completeness.

The binding, an add-on to the base composition root in hex-wiring's CONTAINER.md, which binds no client store. A project that keeps Baz here merges the first two classes into the base's providers of the same name and adds BazsProvider() to the create_container list: the settings provider, the client built once by the connection factory above and closed after its yield, and the repository bound to its port per operation, like every repository (hex-wiring).

from collections.abc import AsyncIterator

from dishka import Provider, Scope, provide
from redis.asyncio import Redis

from myapp.domain.bazs import IBazRepository
from myapp.infrastructure.redis import RedisSettings, create_baz_store_client
from myapp.infrastructure.redis.repositories import BazRepository


class SettingsProvider(Provider):
    scope = Scope.APP

    @provide
    def redis_settings(self) -> RedisSettings:
        return RedisSettings()


class InfrastructureProvider(Provider):
    scope = Scope.APP

    @provide
    async def baz_store_client(self, settings: RedisSettings) -> AsyncIterator[Redis]:
        client = create_baz_store_client(settings)
        yield client
        await client.aclose()


class BazsProvider(Provider):
    scope = Scope.REQUEST

    baz_repository = provide(BazRepository, provides=IBazRepository)

Other bindings

The key-value form is the one worked binding; every other client-style store is the same two files with different SDK names. What changes, and what does not:

  • Document / wide-column stores (mongo, dynamo, cassandra) — the key-value form, with the container token being a collection or table name instead of a key prefix, and the record a native document rather than a JSON string. Mapping helpers, translation and thinness are unchanged.
  • A search index — vector or full-text (a vector store, OpenSearch) — a derived projection of the aggregate, never its authoritative store (Rule 1), so it satisfies a narrower port of its own shaped by what the index answers (hex-domain-ports) — typically an upsert, a query returning scored pairs (Rule 3) and a delete by the field the projection is keyed on. Client injection, the fixed container token, the entity rebuilt from the stored payload (Rule 8), translation and ownership are unchanged. An index inside the relational database (pgvector) is reached through the shared engine, so it is hex-persistence.
  • Object stores (s3, gcs, azure blob) — a bucket is a container token like any other, but a blob is usually a single-action capability rather than an aggregate's collection, so check hex-capability-adapter first.

Each of these is one infrastructure/<kind>/ package under the client-style profile (hex-conventions). None of them is a second copy of this skill.

Rules

File layout

src/myapp/infrastructure/<store-kind>/   # the profile's kind token — infrastructure groups by technology
├── __init__.py
├── connection.py             # create_<store>_client(settings) — shown in the template above
├── <store-kind>_settings.py  # the store's settings class, in the module named for that class (RedisSettings → redis_settings.py) — shown in the template above
└── repositories/
    ├── __init__.py           # package wiring — python-packaging
    └── baz_repository.py     # this skill writes this file — the stem is the port's (`hex-conventions`)

Form

  1. Names and module structure follow naming and python-packaging; technology placement follows hex-architecture and hex-conventions. An aggregate has exactly one authoritative store, the one its writes go to (persistence rule 3) — unlike a capability port that several vendors may implement. A derived projection of the same aggregate on a second store (an index over Foo, see ## Other bindings) sits behind its own narrower port, which is why the repository file stem is protocol-derived for client stores; see hex-conventions.
  2. The adapter satisfies its protocol structurally (hex-architecture rule 7).
  3. Method signatures match the protocol exactly, including async mode, keyword-only markers, and compound return shapes — a compound return is returned whole, never reduced to the entity with the rest discarded.

Client & settings

  1. Inject the SDK client — and the settings class only when rule 5 puts a value there. Both come from containers.py; the client is built once by the datastore's create_<store>_client(settings) factory and bound at process lifetime (hex-wiring). Never construct a client inline in a method, and never swap the injected client type for a different flavor of the SDK.
  2. The container token is fixed in code unless deployments differ. The store's collection, key prefix, index or bucket name is a module constant in the adapter; it becomes a settings field, read once in __init__, only when deployments genuinely point one code base at different names. Stash nothing else the methods do not need.

Records ↔ entities

  1. Private, pure mapping helpers (_record_to_entity / _entity_to_record, and the key builder beside them; module functions by python-packaging rule 2, pure by persistence rule 8). Where rule 5 makes the prefix a setting, the key builder takes it as a parameter. IDs serialize as strings unless the SDK is UUID-native. Annotate the SDK's own record type on the parameter and narrow with isinstance or typing.cast — never object plus a row of # type: ignore[attr-defined]. An inline ignore is python-style's last resort, for code the checker is wrong about that cannot be restated (its type suppressions); an adapter is the one place the vendor type is allowed, so the code can always be restated and there is nothing to silence.
  2. The record shape is persistence rule 10's; the aggregate's access patterns and the store's semantics guide it.
  3. An entity is reconstructed from its own stored data. Never substitute query-side values for stored ones (e.g. an entity rebuilt from a record is built from the record's fields, never patched with the key or the arguments the caller looked it up by); when the read path doesn't consume a stored field, omit it explicitly rather than faking it.

Exception translation

  1. Boundary exception translation, including SDKs without a single exception root, follows exception-catalog.
  2. Error selection follows exception-catalog. An absent record on get_by_id is not an SDK error — detect it (a None, an empty result, a zero count) and fail.
  3. Exception context follows exception-catalog; the templates show the store-specific inputs.

Vendor & semantics

  1. Vendor semantics come from the SDK, not from this skill. Query API, filter DSL, batching (its limit; the obligation is persistence rule 21), consistency options — read them from the SDK's own documentation. A new vendor is its own package under this skill — never a fork of it (the same way hex-capability-adapter serves every vendor with one skill).
  2. No provisioning (persistence rule 14) — a bucket included.
  3. Ordering is explicit (persistence rule 18) — an explicit sort key, or the store's documented result order.
  4. No retries, no caching, no domain reasoning, no logging. Same thinness contract as every adapter (see hex-capability-adapter's adapters-are-thin rules); a repository never logs by persistence rule 22, and which layer does is hex-architecture's.

Inlined typing / import rules

  • Domain imports absolute (from myapp.domain.bazs import Baz); a sibling module of the store's package relative (from ..redis_settings import RedisSettings, where rule 5 puts a value there). Never import the protocol the adapter satisfies (hex-architecture rule 7).
  • SDK types stay inside the adapter; method signatures use domain types or primitives only.
  • Raw SDK payloads may be dict[str, Any] / object at the immediate boundary — convert to the domain type in the mapping helper, never return them.
  • No from __future__ import annotations. Full annotations on every method.

Package wiring

For repositories/__init__.py, follow python-packaging; package placement follows hex-architecture.

Hard stops

  • The aggregate's store is the relational bootstrap store — reached through a shared engine rather than an injected client — or the request is for SQL, SQLAlchemy or a Table → stop, use hex-persistence.
  • Asked for atomicity across this store and another (two stores in one transaction) → stop, use hex-application for handler compensation; there is no cross-store transaction.
  • The port is a single-action capability (ICan<Verb>), not an aggregate's collection → stop, use hex-capability-adapter.