qx-db 0.1.0__tar.gz

qx_db-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+.eggs/
+sdist/
+wheels/
+*.egg-link
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.env.local
+
+# Dist artifacts
+dist/

qx_db-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: qx-db
+Version: 0.1.0
+Summary: Qx database layer: SQLAlchemy 2 async, repositories, unit of work, transactional outbox
+Author: Qx Engineering
+License: MIT
+Requires-Python: >=3.14
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: qx-core
+Requires-Dist: qx-cqrs
+Requires-Dist: qx-di
+Requires-Dist: qx-observability
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30
+Description-Content-Type: text/markdown
+
+# qx-db
+
+Database layer for the Qx framework — SQLAlchemy 2 async, a generic `Repository[TEntity]`, `UnitOfWork` with domain-event routing, transactional outbox, and cursor/offset pagination.
+
+## What lives here
+
+- **`qx.db.Repository[TEntity]`** — generic async CRUD with optimistic concurrency (`version` column), soft-delete, tenant filtering, and allow-listed filter/sort fields.
+- **`qx.db.UnitOfWork`** — wraps a SQLAlchemy session; commits the aggregate write and the outbox `INSERT` in one transaction, then drains and dispatches domain events.
+- **`qx.db.OutboxRecorder` / `DefaultOutboxRecorder`** — persists `IntegrationEvent` payloads to `qx_outbox_events` for reliable delivery.
+- **`qx.db.SessionFactory`** — factory for `AsyncSession` instances; injected into repositories.
+- **`qx.db.make_metadata` / `make_registry`** — SQLAlchemy `MetaData` and `registry` helpers for imperative mapping (no declarative base).
+- **`qx.db.standard_audit_columns` / `uuid_column` / `jsonb_column`** — column helpers for consistent schema conventions.
+- **`qx.db.build_cursor_page` / `encode_cursor` / `decode_cursor`** — opaque cursor pagination utilities.
+- **`qx.db.include_outbox_table`** — attaches the `qx_outbox_events` table to your `MetaData`.
+
+## Defining a repository
+
+```python
+from qx.db import Repository
+from sqlalchemy import Table
+
+class UserRepository(Repository[User]):
+    entity_cls = User
+    table: Table  # set to your SQLAlchemy Table at class or instance level
+    filterable_fields = {"email", "name", "is_active"}
+    sortable_fields = {"created_at", "email"}
+    tenanted = False  # set True for multi-tenant tables
+```
+
+## Unit of Work
+
+```python
+from qx.db import UnitOfWork
+
+class CreateUserHandler:
+    def __init__(self, uow: UnitOfWork) -> None:
+        self._uow = uow
+
+    async def handle(self, cmd: CreateUserCommand) -> Result[UserDto]:
+        async with self._uow.begin() as ctx:
+            user_result = User.register(cmd.email, cmd.name)
+            user = unwrap(user_result)
+            await ctx.users.add(user)
+        # commit + outbox INSERT + event dispatch all happened above
+        return Result.success(UserDto.from_domain(user))
+```
+
+## Design rules
+
+- **Optimistic concurrency** — `save()` uses `WHERE id = ? AND version = ?`; returns `ConflictError` (not an exception) on mismatch.
+- **Soft-delete by default** — `list()` and `get()` exclude rows where `deleted_at IS NOT NULL` unless `include_deleted=True`.
+- **Allow-listed filters** — `filterable_fields` and `sortable_fields` are class-level sets; querying an unlisted field raises `ValueError` to prevent controller logic leaking into SQL.
+- **Imperative mapping** — domain entities are plain dataclasses with no SQLAlchemy decorators. The mapping lives in the infrastructure layer, not the domain.
+- **UUID v7** — `uuid_column()` defaults to UUID v7 primary keys for sequential B-tree index locality.

qx_db-0.1.0/README.md

@@ -0,0 +1,54 @@
+# qx-db
+
+Database layer for the Qx framework — SQLAlchemy 2 async, a generic `Repository[TEntity]`, `UnitOfWork` with domain-event routing, transactional outbox, and cursor/offset pagination.
+
+## What lives here
+
+- **`qx.db.Repository[TEntity]`** — generic async CRUD with optimistic concurrency (`version` column), soft-delete, tenant filtering, and allow-listed filter/sort fields.
+- **`qx.db.UnitOfWork`** — wraps a SQLAlchemy session; commits the aggregate write and the outbox `INSERT` in one transaction, then drains and dispatches domain events.
+- **`qx.db.OutboxRecorder` / `DefaultOutboxRecorder`** — persists `IntegrationEvent` payloads to `qx_outbox_events` for reliable delivery.
+- **`qx.db.SessionFactory`** — factory for `AsyncSession` instances; injected into repositories.
+- **`qx.db.make_metadata` / `make_registry`** — SQLAlchemy `MetaData` and `registry` helpers for imperative mapping (no declarative base).
+- **`qx.db.standard_audit_columns` / `uuid_column` / `jsonb_column`** — column helpers for consistent schema conventions.
+- **`qx.db.build_cursor_page` / `encode_cursor` / `decode_cursor`** — opaque cursor pagination utilities.
+- **`qx.db.include_outbox_table`** — attaches the `qx_outbox_events` table to your `MetaData`.
+
+## Defining a repository
+
+```python
+from qx.db import Repository
+from sqlalchemy import Table
+
+class UserRepository(Repository[User]):
+    entity_cls = User
+    table: Table  # set to your SQLAlchemy Table at class or instance level
+    filterable_fields = {"email", "name", "is_active"}
+    sortable_fields = {"created_at", "email"}
+    tenanted = False  # set True for multi-tenant tables
+```
+
+## Unit of Work
+
+```python
+from qx.db import UnitOfWork
+
+class CreateUserHandler:
+    def __init__(self, uow: UnitOfWork) -> None:
+        self._uow = uow
+
+    async def handle(self, cmd: CreateUserCommand) -> Result[UserDto]:
+        async with self._uow.begin() as ctx:
+            user_result = User.register(cmd.email, cmd.name)
+            user = unwrap(user_result)
+            await ctx.users.add(user)
+        # commit + outbox INSERT + event dispatch all happened above
+        return Result.success(UserDto.from_domain(user))
+```
+
+## Design rules
+
+- **Optimistic concurrency** — `save()` uses `WHERE id = ? AND version = ?`; returns `ConflictError` (not an exception) on mismatch.
+- **Soft-delete by default** — `list()` and `get()` exclude rows where `deleted_at IS NOT NULL` unless `include_deleted=True`.
+- **Allow-listed filters** — `filterable_fields` and `sortable_fields` are class-level sets; querying an unlisted field raises `ValueError` to prevent controller logic leaking into SQL.
+- **Imperative mapping** — domain entities are plain dataclasses with no SQLAlchemy decorators. The mapping lives in the infrastructure layer, not the domain.
+- **UUID v7** — `uuid_column()` defaults to UUID v7 primary keys for sequential B-tree index locality.

qx_db-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "qx-db"
+version = "0.1.0"
+description = "Qx database layer: SQLAlchemy 2 async, repositories, unit of work, transactional outbox"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Qx Engineering" }]
+dependencies = [
+    "qx-core",
+    "qx-di",
+    "qx-cqrs",
+    "qx-observability",
+    "sqlalchemy[asyncio]>=2.0.30",
+    "asyncpg>=0.30.0",
+    "alembic>=1.13.0",
+    "pydantic>=2.8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qx"]

qx_db-0.1.0/src/qx/db/__init__.py

@@ -0,0 +1,66 @@
+"""Qx database layer.
+
+Public surface — import from ``qx.db``.
+"""
+
+from __future__ import annotations
+
+from qx.db.engine import (
+    DatabaseSettings,
+    SessionFactory,
+    create_engine,
+    make_session_factory,
+    open_session,
+)
+from qx.db.mapping import (
+    jsonb_column,
+    make_metadata,
+    make_registry,
+    standard_audit_columns,
+    uuid_column,
+)
+from qx.db.outbox import (
+    OUTBOX_TABLE_NAME,
+    DefaultOutboxRecorder,
+    OutboxRecorder,
+    include_outbox_table,
+)
+from qx.db.pagination import (
+    build_cursor_page,
+    decode_cursor,
+    encode_cursor,
+)
+from qx.db.repository import Repository
+from qx.db.uow import EventDispatcher, UnitOfWork
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "OUTBOX_TABLE_NAME",
+    # Engine / sessions
+    "DatabaseSettings",
+    "DefaultOutboxRecorder",
+    "EventDispatcher",
+    # Outbox
+    "OutboxRecorder",
+    # Repository
+    "Repository",
+    "SessionFactory",
+    # UoW
+    "UnitOfWork",
+    "__version__",
+    "build_cursor_page",
+    "create_engine",
+    "decode_cursor",
+    # Pagination
+    "encode_cursor",
+    "include_outbox_table",
+    "jsonb_column",
+    # Mapping
+    "make_metadata",
+    "make_registry",
+    "make_session_factory",
+    "open_session",
+    "standard_audit_columns",
+    "uuid_column",
+]

qx_db-0.1.0/src/qx/db/engine/__init__.py

@@ -0,0 +1,122 @@
+"""Async engine and session factory.
+
+Two-tier setup:
+
+- One ``AsyncEngine`` per database, registered as a singleton.
+- ``AsyncSession`` is **scoped** to a request: one session per HTTP request /
+  message / job, opened by the unit-of-work and closed on scope exit.
+
+We expose a ``DatabaseSettings`` Pydantic settings class that services pull
+their DB config from. Settings live in ``qx-core`` style (``QX_DB__*``
+env vars).
+
+The engine is configured with pool_pre_ping (so DNS / TCP-stale connections
+get caught) and a sane default pool size. NullPool is supported for serverless
+runtimes (Lambda, Fly Machines) where a connection pool fights the platform.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, ClassVar, Literal
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.pool import AsyncAdaptedQueuePool, NullPool
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+__all__ = [
+    "DatabaseSettings",
+    "SessionFactory",
+    "create_engine",
+    "make_session_factory",
+]
+
+
+PoolKind = Literal["queue", "null"]
+
+
+class DatabaseSettings(BaseSettings):
+    """Database configuration.
+
+    Env vars: ``QX_DB__URL``, ``QX_DB__POOL_SIZE``, etc.
+    """
+
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix="QX_DB__",
+        extra="ignore",
+    )
+
+    url: SecretStr = Field(
+        default=SecretStr("postgresql+asyncpg://postgres:postgres@localhost:5432/qx")
+    )
+    pool_size: int = 10
+    max_overflow: int = 10
+    pool_timeout_seconds: float = 30.0
+    pool_recycle_seconds: int = 1800  # recycle every 30 min, dodging upstream idle-cuts
+    pool_pre_ping: bool = True
+    pool_kind: PoolKind = "queue"
+    echo: bool = False
+    # Statement timeout applied via `SET LOCAL statement_timeout`; per-statement,
+    # not connection-wide, so transactions can opt out via their own SET.
+    statement_timeout_ms: int = 10_000
+
+
+def create_engine(settings: DatabaseSettings) -> AsyncEngine:
+    """Build an async engine.
+
+    The engine is a long-lived, thread-safe object. Treat it as a singleton.
+    Disposing it (``await engine.dispose()``) closes all pooled connections —
+    do that at process shutdown.
+    """
+    if settings.pool_kind == "null":
+        engine = create_async_engine(
+            settings.url.get_secret_value(),
+            poolclass=NullPool,
+            echo=settings.echo,
+            future=True,
+        )
+    else:
+        engine = create_async_engine(
+            settings.url.get_secret_value(),
+            poolclass=AsyncAdaptedQueuePool,
+            pool_size=settings.pool_size,
+            max_overflow=settings.max_overflow,
+            pool_timeout=settings.pool_timeout_seconds,
+            pool_recycle=settings.pool_recycle_seconds,
+            pool_pre_ping=settings.pool_pre_ping,
+            echo=settings.echo,
+            future=True,
+        )
+    return engine
+
+
+SessionFactory = async_sessionmaker[AsyncSession]
+
+
+def make_session_factory(engine: AsyncEngine) -> SessionFactory:
+    """Build a session factory. Singleton per engine."""
+    return async_sessionmaker(
+        bind=engine,
+        expire_on_commit=False,  # let aggregates be read after commit without re-fetch
+        autoflush=False,  # we control flushes explicitly via the UoW
+        class_=AsyncSession,
+    )
+
+
+@asynccontextmanager
+async def open_session(factory: SessionFactory) -> AsyncIterator[AsyncSession]:
+    """Open a session in an async context manager. Closes regardless of outcome."""
+    session = factory()
+    try:
+        yield session
+    finally:
+        await session.close()

qx_db-0.1.0/src/qx/db/mapping/__init__.py

@@ -0,0 +1,116 @@
+"""SQLAlchemy imperative mapping.
+
+We deliberately do **not** use declarative-style ORM (no ``DeclarativeBase``,
+no ``Mapped`` on entities). Reasons:
+
+- Keeps domain entities decoupled from SQLAlchemy. They remain plain
+  ``@dataclass``-style objects that the framework (and tests) can construct
+  trivially without an active session.
+- Lets us define multiple persistence representations of the same aggregate
+  (e.g., a write model and a denormalized read model) without inheritance
+  gymnastics.
+- Mirrors how clean-architecture-discipline services in other ecosystems
+  (Java/Spring's JPA EntityManager, .NET's EF Core Fluent API) handle the
+  domain/infrastructure boundary.
+
+The trade-off: a small amount of boilerplate per aggregate in ``mapping.py``
+files declaring ```` + ``registry.map_imperatively(Entity, table)``. Worth it.
+
+This module supplies the framework-level ``mapping_registry()`` and a few
+common column types so services stay consistent.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Integer,
+    MetaData,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PG_UUID
+from sqlalchemy.orm import registry as sa_registry
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+__all__ = [
+    "jsonb_column",
+    "make_metadata",
+    "make_registry",
+    "standard_audit_columns",
+    "uuid_column",
+]
+
+
+def make_metadata(schema: str | None = None) -> MetaData:
+    """Build a metadata object with consistent naming conventions.
+
+    Predictable index/constraint names matter for Alembic — without these,
+    autogenerate produces unstable names that flip between revisions.
+    """
+    return MetaData(
+        schema=schema,
+        naming_convention={
+            "ix": "ix_%(column_0_label)s",
+            "uq": "uq_%(table_name)s_%(column_0_name)s",
+            "ck": "ck_%(table_name)s_%(constraint_name)s",
+            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+            "pk": "pk_%(table_name)s",
+        },
+    )
+
+
+def make_registry(metadata: MetaData | None = None) -> sa_registry:
+    """Create an SQLAlchemy registry for imperative mapping."""
+    md = metadata or make_metadata()
+    return sa_registry(metadata=md)
+
+
+def standard_audit_columns(
+    *,
+    include_tenant: bool = True,
+    include_deletion: bool = True,
+) -> list[Column[Any]]:
+    """Common audit columns mirroring the ``Entity`` base fields.
+
+    Use in every aggregate table::
+
+        users =(
+            "users",
+            metadata,
+            Column("id", PG_UUID(as_uuid=True), primary_key=True),
+            Column("email"(255), nullable=False, unique=True),
+            *standard_audit_columns(),
+        )
+    """
+    cols: list[Column[Any]] = [
+        Column("created_at", DateTime(timezone=True), nullable=False),
+        Column("updated_at", DateTime(timezone=True), nullable=True),
+        Column("created_by", PG_UUID(as_uuid=True), nullable=True),
+        Column("updated_by", PG_UUID(as_uuid=True), nullable=True),
+        Column("version", Integer, nullable=False, default=1),
+    ]
+    if include_tenant:
+        cols.append(Column("tenant_id", PG_UUID(as_uuid=True), nullable=True, index=True))
+    if include_deletion:
+        cols.extend(
+            [
+                Column("deleted_at", DateTime(timezone=True), nullable=True, index=True),
+                Column("deleted_by", PG_UUID(as_uuid=True), nullable=True),
+            ]
+        )
+    return cols
+
+
+def uuid_column(name: str, *, primary_key: bool = False, **kwargs: Any) -> Column[UUID]:
+    """Conventional UUID column. Uses Postgres native UUID type."""
+    return Column(name, PG_UUID(as_uuid=True), primary_key=primary_key, **kwargs)
+
+
+def jsonb_column(name: str, **kwargs: Any) -> Column[dict[str, Any]]:
+    """Conventional JSONB column."""
+    return Column(name, JSONB, **kwargs)

qx_db-0.1.0/src/qx/db/migrations/__init__.py

@@ -0,0 +1,104 @@
+"""Alembic integration helpers.
+
+Services own their migration directory; the framework only supplies the
+boilerplate to make ``alembic`` aware of the async engine and the framework's
+naming conventions.
+
+Typical service ``alembic/env.py`` calls into here::
+
+    from qx.db.migrations import run_async_migrations
+    from myservice.persistence import metadata
+
+    run_async_migrations(metadata)
+
+We don't ship an opinionated ``alembic.ini`` because version locations and
+script templates are service-specific. The CLI scaffold (``qx`` CLI)
+generates them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from alembic import context
+from sqlalchemy import MetaData
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+__all__ = ["run_async_migrations"]
+
+
+def run_async_migrations(
+    metadata: MetaData,
+    *,
+    compare_type: bool = True,
+    compare_server_default: bool = True,
+    include_schemas: bool = False,
+) -> None:
+    """Run Alembic migrations against an async engine.
+
+    Call from ``alembic/env.py``. Picks up the connection URL from the
+    ``alembic.ini`` ``sqlalchemy.url`` (which services typically set from
+    ``QX_DB__URL``).
+
+    ``compare_type`` and ``compare_server_default`` are on by default so
+    autogenerate catches the largest class of schema drift.
+    """
+    cfg = context.config
+    if context.is_offline_mode():
+        context.configure(
+            url=cfg.get_main_option("sqlalchemy.url"),
+            target_metadata=metadata,
+            compare_type=compare_type,
+            compare_server_default=compare_server_default,
+            include_schemas=include_schemas,
+            literal_binds=True,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+        return
+
+    asyncio.run(_run_online(cfg, metadata, compare_type, compare_server_default, include_schemas))
+
+
+async def _run_online(
+    cfg: Any,
+    metadata: MetaData,
+    compare_type: bool,
+    compare_server_default: bool,
+    include_schemas: bool,
+) -> None:
+    section = cfg.get_section(cfg.config_ini_section) or {}
+    engine = async_engine_from_config(
+        section,
+        prefix="sqlalchemy.",
+        future=True,
+    )
+    async with engine.connect() as conn:
+        await conn.run_sync(
+            _do_migrations,
+            metadata,
+            compare_type,
+            compare_server_default,
+            include_schemas,
+        )
+    await engine.dispose()
+
+
+def _do_migrations(
+    connection: Connection,
+    metadata: MetaData,
+    compare_type: bool,
+    compare_server_default: bool,
+    include_schemas: bool,
+) -> None:
+    context.configure(
+        connection=connection,
+        target_metadata=metadata,
+        compare_type=compare_type,
+        compare_server_default=compare_server_default,
+        include_schemas=include_schemas,
+    )
+    with context.begin_transaction():
+        context.run_migrations()

qx_db-0.1.0/src/qx/db/outbox/__init__.py

@@ -0,0 +1,147 @@
+"""Transactional outbox.
+
+The outbox is the textbook pattern for atomic state-change + event-publishing:
+
+1. The application writes the aggregate change and inserts a row into
+   ``outbox_events`` in the **same SQL transaction**. Either both succeed or
+   both roll back.
+2. A separate ``OutboxRelay`` worker polls the table, publishes pending rows
+   to the message broker (NATS JetStream), and marks them as published.
+
+This module supplies:
+
+- The ``outbox_events`` Table definition (services include it in their
+  metadata via ``include_outbox_table(metadata)``).
+- The ``OutboxRecorder`` which serializes ``IntegrationEvent`` instances and
+  inserts them in the UoW's transaction.
+- The relay worker itself lives in ``qx-events`` — it depends on a
+  broker, and we keep the database package broker-agnostic.
+
+Schema choice: store the full event envelope as JSONB plus a few denormalized
+columns we'll want to query/index (event_name, occurred_at, tenant_id). This
+lets you do `SELECT * FROM outbox_events WHERE event_name = 'user.registered'
+AND published_at IS NULL` without parsing JSON.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from uuid import uuid4
+
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Index,
+    Integer,
+    MetaData,
+    String,
+    Table,
+    text,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PG_UUID
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from qx.core import IntegrationEvent
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+__all__ = [
+    "OUTBOX_TABLE_NAME",
+    "DefaultOutboxRecorder",
+    "OutboxRecorder",
+    "include_outbox_table",
+]
+
+
+OUTBOX_TABLE_NAME = "qx_outbox_events"
+
+
+def include_outbox_table(metadata: MetaData) -> Table:
+    """Register the outbox table in the given metadata.
+
+    Services call this once during their mapping setup so Alembic picks up the
+    table in autogenerated revisions.
+    """
+    return Table(
+        OUTBOX_TABLE_NAME,
+        metadata,
+        Column("id", PG_UUID(as_uuid=True), primary_key=True),
+        Column("event_name", String(255), nullable=False),
+        Column("event_version", Integer, nullable=False, default=1),
+        Column("payload", JSONB, nullable=False),
+        Column("occurred_at", DateTime(timezone=True), nullable=False),
+        Column("correlation_id", PG_UUID(as_uuid=True), nullable=True),
+        Column("causation_id", PG_UUID(as_uuid=True), nullable=True),
+        Column("tenant_id", PG_UUID(as_uuid=True), nullable=True),
+        Column("published_at", DateTime(timezone=True), nullable=True),
+        Column("attempts", Integer, nullable=False, default=0),
+        Column("last_error", String(2048), nullable=True),
+        Index(f"ix_{OUTBOX_TABLE_NAME}_pending", "published_at", "occurred_at"),
+        Index(f"ix_{OUTBOX_TABLE_NAME}_event_name", "event_name"),
+    )
+
+
+@runtime_checkable
+class OutboxRecorder(Protocol):
+    """Protocol the UoW uses to write integration events to the outbox.
+
+    Kept abstract so test cases and alternative storage (e.g., outbox-as-Kafka-
+    log for very high throughput) can swap in.
+    """
+
+    async def record(
+        self,
+        session: AsyncSession,
+        events: Sequence[IntegrationEvent],
+    ) -> None: ...
+
+
+class DefaultOutboxRecorder:
+    """Inserts rows into the PostgreSQL outbox table inside the current transaction."""
+
+    def __init__(self, table_name: str = OUTBOX_TABLE_NAME) -> None:
+        self._table = table_name
+
+    async def record(
+        self,
+        session: AsyncSession,
+        events: Sequence[IntegrationEvent],
+    ) -> None:
+        if not events:
+            return
+        rows = [
+            {
+                "id": str(uuid4()),
+                "event_name": ev.event_name,
+                "event_version": ev.event_version,
+                "payload": json.dumps(ev.envelope()),
+                "occurred_at": ev.occurred_at,
+                "correlation_id": str(ev.correlation_id) if ev.correlation_id else None,
+                "causation_id": str(ev.causation_id) if ev.causation_id else None,
+                "tenant_id": str(ev.tenant_id) if ev.tenant_id else None,
+                "published_at": None,
+                "attempts": 0,
+                "last_error": None,
+            }
+            for ev in events
+        ]
+        # We use an inline INSERT to keep this module free of a Table dep on
+        # the live MetaData (the service owns the metadata; we just write).
+        await session.execute(
+            text(
+                f"""
+                INSERT INTO {self._table}
+                    (id, event_name, event_version, payload, occurred_at,
+                     correlation_id, causation_id, tenant_id, published_at,
+                     attempts, last_error)
+                VALUES
+                    (:id, :event_name, :event_version, CAST(:payload AS JSONB),
+                     :occurred_at, :correlation_id, :causation_id, :tenant_id,
+                     :published_at, :attempts, :last_error)
+                """
+            ),
+            rows,
+        )

qx_db-0.1.0/src/qx/db/pagination/__init__.py

@@ -0,0 +1,66 @@
+"""Cursor pagination helpers.
+
+We use **keyset pagination**: the cursor encodes the sort key + tiebreaker
+(id) of the last row in the previous page. The next query becomes ``WHERE
+(sort_key, id) > (last_sort_key, last_id) ORDER BY sort_key, id LIMIT N``.
+
+Cursors are base64'd JSON internally. Clients treat them as opaque tokens —
+they should never parse them. This lets us evolve the cursor format (add
+fields, change sort key) without breaking clients.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from qx.core import CursorPage
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from qx.core.types.pagination import Sort
+
+__all__ = ["build_cursor_page", "decode_cursor", "encode_cursor"]
+
+
+def encode_cursor(values: dict[str, Any]) -> str:
+    raw = json.dumps(values, default=_serialize, separators=(",", ":")).encode()
+    return base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def decode_cursor(cursor: str) -> dict[str, Any]:
+    pad = "=" * (-len(cursor) % 4)
+    raw = base64.urlsafe_b64decode(cursor + pad).decode()
+    return json.loads(raw)  # type: ignore[no-any-return]
+
+
+def _serialize(o: Any) -> Any:
+    if isinstance(o, datetime):
+        return o.isoformat()
+    return str(o)
+
+
+def build_cursor_page(
+    items: Sequence[Any],
+    *,
+    limit: int,
+    sort: Sequence[Sort],
+    cursor_fields: Sequence[str],
+) -> CursorPage[Any]:
+    """Build a ``CursorPage`` from query results.
+
+    The caller fetches ``limit + 1`` rows; if ``len(items) > limit`` we trim
+    and emit a cursor pointing at the last yielded row. This is the textbook
+    "fetch one extra to know if there's a next page" trick.
+    """
+    has_next = len(items) > limit
+    yielded = list(items[:limit])
+    next_cursor: str | None = None
+    if has_next and yielded:
+        last = yielded[-1]
+        cursor_payload = {f: getattr(last, f, None) for f in cursor_fields}
+        next_cursor = encode_cursor(cursor_payload)
+    return CursorPage(items=yielded, next_cursor=next_cursor, has_next=has_next)

qx_db-0.1.0/src/qx/db/repository/__init__.py

@@ -0,0 +1,281 @@
+"""Generic Repository base class.
+
+Repositories are the boundary between domain code and persistence. They:
+
+- Accept and return domain entities/aggregates (never raw rows).
+- Translate filter/sort/pagination shapes into SQL.
+- Honor tenant isolation (when the entity is tenanted).
+- Honor soft-delete by default (callers can opt in to including deleted).
+- Pull domain events out of aggregates on save and hand them to the unit of work
+  (which routes them to in-process handlers and/or the outbox).
+
+This base implements the boring 80%. Aggregate-specific repositories subclass
+and add domain-flavored finders (``find_by_email``, ``find_active_admins``,
+etc.). Avoid generic ``find(where=...)`` APIs leaking up — they couple HTTP
+controllers to SQL syntax and prevent the repo from validating queries.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
+
+from qx.core import (
+    ConflictError,
+    Entity,
+    Filter,
+    NotFoundError,
+    OffsetPage,
+    OffsetPagination,
+    Result,
+    current_context,
+    utcnow,
+)
+from sqlalchemy import Column, Table, delete, func, select, update
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from uuid import UUID
+
+    from qx.core.types.pagination import FilterOp, Sort
+    from sqlalchemy.ext.asyncio import AsyncSession
+    from sqlalchemy.sql import ColumnElement, Select
+
+__all__ = ["Repository"]
+
+
+TEntity = TypeVar("TEntity", bound=Entity[Any])
+
+
+class Repository[TEntity: Entity[Any]]:
+    """Base repository with typed CRUD against a single aggregate table.
+
+    Subclass and supply the entity type and table at class-definition time::
+
+        class UserRepository(Repository[User]):
+            entity_cls = User
+            table = users_table
+            # Allow-list of filterable fields. Reject anything else.
+            filterable_fields = {"email", "name", "is_admin"}
+            sortable_fields = {"created_at", "email"}
+    """
+
+    entity_cls: type[TEntity]
+    table: Table
+    filterable_fields: ClassVar[set[str]] = set()
+    sortable_fields: ClassVar[set[str]] = {"created_at"}
+
+    # Subclasses can override to disable tenant filtering for global-scoped tables.
+    tenanted: bool = True
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    # ============================================================
+    # Reads
+    # ============================================================
+
+    async def get(
+        self,
+        id: UUID,
+        *,
+        include_deleted: bool = False,
+    ) -> Result[TEntity]:
+        stmt = select(self.table).where(self.table.c.id == id)
+        stmt = self._scope_query(stmt, include_deleted=include_deleted)
+        row = (await self._session.execute(stmt)).mappings().first()
+        return Result.from_optional(
+            self._row_to_entity(row) if row else None,
+            on_none=NotFoundError(
+                code=f"{self.entity_cls.__name__.lower()}.not_found",
+                message=f"{self.entity_cls.__name__} {id} not found",
+                details={"id": str(id)},
+            ),
+        )
+
+    async def exists(self, id: UUID) -> bool:
+        stmt = select(func.count()).select_from(self.table).where(self.table.c.id == id)
+        stmt = self._scope_query(stmt, include_deleted=False)
+        return ((await self._session.execute(stmt)).scalar() or 0) > 0
+
+    async def list(
+        self,
+        pagination: OffsetPagination = OffsetPagination(),  # noqa: B008
+        *,
+        include_deleted: bool = False,
+    ) -> OffsetPage[TEntity]:
+        stmt = select(self.table)
+        stmt = self._scope_query(stmt, include_deleted=include_deleted)
+        stmt = self._apply_filters(stmt, pagination.filters)
+        stmt = self._apply_sort(stmt, pagination.sort)
+
+        count_stmt = select(func.count()).select_from(stmt.subquery())
+        total = (await self._session.execute(count_stmt)).scalar() or 0
+
+        stmt = stmt.limit(pagination.page_size).offset(pagination.offset)
+        rows = (await self._session.execute(stmt)).mappings().all()
+        items = [self._row_to_entity(r) for r in rows]
+        return OffsetPage(
+            items=items,
+            page=pagination.page,
+            page_size=pagination.page_size,
+            total=int(total),
+        )
+
+    # ============================================================
+    # Writes
+    # ============================================================
+
+    async def add(self, entity: TEntity) -> Result[TEntity]:
+        """Insert a new aggregate. Sets created_at/created_by from context."""
+        ctx = current_context()
+        values = self._entity_to_dict(entity)
+        values.setdefault("created_at", utcnow())
+        values.setdefault("created_by", ctx.user_id)
+        if self.tenanted and "tenant_id" not in values:
+            values["tenant_id"] = ctx.tenant_id
+        values.setdefault("version", 1)
+        await self._session.execute(self.table.insert().values(**values))
+        return Result.success(entity)
+
+    async def save(self, entity: TEntity) -> Result[TEntity]:
+        """Update an existing aggregate with optimistic concurrency on ``version``."""
+        ctx = current_context()
+        current_version = entity.version
+        values = self._entity_to_dict(entity)
+        values["version"] = current_version + 1
+        values["updated_at"] = utcnow()
+        values["updated_by"] = ctx.user_id
+        stmt = (
+            update(self.table)
+            .where(self.table.c.id == values["id"], self.table.c.version == current_version)
+            .values(**values)
+        )
+        result = await self._session.execute(stmt)
+        if result.rowcount == 0:  # type: ignore[attr-defined]
+            return Result.failure(
+                ConflictError(
+                    code=f"{self.entity_cls.__name__.lower()}.version_conflict",
+                    message=(
+                        f"{self.entity_cls.__name__} {entity.id} was modified concurrently "
+                        f"(expected version {current_version})."
+                    ),
+                    details={"id": str(entity.id), "version": current_version},
+                )
+            )
+        entity.version = current_version + 1
+        return Result.success(entity)
+
+    async def soft_delete(self, id: UUID) -> Result[None]:
+        ctx = current_context()
+        stmt = (
+            update(self.table)
+            .where(
+                self.table.c.id == id,
+                self.table.c.deleted_at.is_(None),
+            )
+            .values(deleted_at=utcnow(), deleted_by=ctx.user_id)
+        )
+        result = await self._session.execute(stmt)
+        if result.rowcount == 0:  # type: ignore[attr-defined]
+            return Result.failure(
+                NotFoundError(
+                    code=f"{self.entity_cls.__name__.lower()}.not_found",
+                    message=f"{self.entity_cls.__name__} {id} not found or already deleted",
+                )
+            )
+        return Result.success(None)
+
+    async def hard_delete(self, id: UUID) -> Result[None]:
+        """Physical delete. Avoid except for GDPR / right-to-be-forgotten paths."""
+        stmt = delete(self.table).where(self.table.c.id == id)
+        result = await self._session.execute(stmt)
+        if result.rowcount == 0:  # type: ignore[attr-defined]
+            return Result.failure(
+                NotFoundError(
+                    code=f"{self.entity_cls.__name__.lower()}.not_found",
+                    message=f"{self.entity_cls.__name__} {id} not found",
+                )
+            )
+        return Result.success(None)
+
+    # ============================================================
+    # Internals — subclasses can override
+    # ============================================================
+
+    def _row_to_entity(self, row: Any) -> TEntity:
+        """Default: pass-through to the entity constructor.
+
+        Subclasses override when the table schema doesn't match the entity
+        shape (renamed columns, JSON-packed value objects, etc.).
+        """
+        return self.entity_cls(**dict(row))
+
+    def _entity_to_dict(self, entity: TEntity) -> dict[str, Any]:
+        """Default: shallow vars(). Override for non-trivial mappings."""
+        result = {k: v for k, v in vars(entity).items() if not k.startswith("_")}
+        return result
+
+    def _scope_query(self, stmt: Select[Any], *, include_deleted: bool) -> Select[Any]:
+        if not include_deleted and "deleted_at" in self.table.c:
+            stmt = stmt.where(self.table.c.deleted_at.is_(None))
+        if self.tenanted and "tenant_id" in self.table.c:
+            tid = current_context().tenant_id
+            # No tenant in context means service-internal call; don't filter.
+            # Production deployments should enforce a tenant via middleware.
+            if tid is not None:
+                stmt = stmt.where(self.table.c.tenant_id == tid)
+        return stmt
+
+    def _apply_filters(self, stmt: Select[Any], filters: Sequence[Filter]) -> Select[Any]:
+        for f in filters:
+            if f.field not in self.filterable_fields:
+                # Silently dropping a filter is a security hazard. Refuse.
+                raise ValueError(
+                    f"Field {f.field!r} is not filterable on "
+                    f"{self.entity_cls.__name__} (allow-list: {sorted(self.filterable_fields)})"
+                )
+            col: Column[Any] = self.table.c[f.field]
+            stmt = stmt.where(_apply_op(col, f.op, f.value))
+        return stmt
+
+    def _apply_sort(self, stmt: Select[Any], sorts: Sequence[Sort]) -> Select[Any]:
+        sortable = self.sortable_fields | {"created_at"}
+        order_cols: list[Any] = []
+        for s in sorts:
+            if s.field not in sortable:
+                raise ValueError(f"Field {s.field!r} is not sortable on {self.entity_cls.__name__}")
+            col = self.table.c[s.field]
+            order_cols.append(col.desc() if s.direction == "desc" else col.asc())
+        # Always include id as a stable tiebreaker for deterministic pagination.
+        order_cols.append(self.table.c.id.asc())
+        return stmt.order_by(*order_cols)
+
+
+def _apply_op(col: ColumnElement[Any], op: FilterOp, value: Any) -> ColumnElement[bool]:  # noqa: PLR0911, PLR0912
+    if op == "eq":
+        return col == value  # type: ignore[no-any-return]
+    if op == "neq":
+        return col != value  # type: ignore[no-any-return]
+    if op == "in":
+        return col.in_(value)
+    if op == "not_in":
+        return ~col.in_(value)
+    if op == "gt":
+        return col > value  # type: ignore[no-any-return]
+    if op == "gte":
+        return col >= value  # type: ignore[no-any-return]
+    if op == "lt":
+        return col < value  # type: ignore[no-any-return]
+    if op == "lte":
+        return col <= value  # type: ignore[no-any-return]
+    if op == "contains":
+        return col.ilike(f"%{value}%")
+    if op == "starts_with":
+        return col.ilike(f"{value}%")
+    if op == "ends_with":
+        return col.ilike(f"%{value}")
+    if op == "is_null":
+        return col.is_(None)
+    if op == "is_not_null":
+        return col.is_not(None)
+    raise ValueError(f"Unsupported filter op: {op}")

qx_db-0.1.0/src/qx/db/uow/__init__.py

@@ -0,0 +1,154 @@
+"""Unit of Work.
+
+Drives the transactional boundary around a command. Responsibilities:
+
+1. Open an ``AsyncSession`` from the factory.
+2. Begin a transaction.
+3. Track aggregates loaded/added so their pending domain events can be drained.
+4. On commit: drain events, dispatch in-process handlers inside the transaction,
+   write integration events to the outbox table (atomic with state change).
+5. Commit. On any failure, roll back; pending events are discarded.
+
+Usage::
+
+    async with uow_factory() as uow:
+        repo = UserRepository(uow.session)
+        user = User.create(...)
+        await repo.add(user)
+        await uow.commit()
+        # events have now been dispatched/outboxed; transaction committed.
+
+The dispatcher abstraction (``EventDispatcher``) is a protocol so the
+unit-of-work doesn't pull a hard dependency on the mediator. The wiring layer
+(usually ``qx.bootstrap``) provides the concrete implementation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from qx.core import AggregateRoot, DomainEvent, IntegrationEvent, current_context
+
+if TYPE_CHECKING:
+    from qx.db.engine import SessionFactory
+    from qx.db.outbox import OutboxRecorder
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+__all__ = ["EventDispatcher", "UnitOfWork"]
+
+
+@runtime_checkable
+class EventDispatcher(Protocol):
+    """Protocol the UoW uses to dispatch in-process domain events.
+
+    Concretely implemented over the mediator's ``publish`` in service bootstrap.
+    Kept as a protocol here to keep ``qx-db`` independent of
+    ``qx-cqrs`` at the type level (it's still in deps for testing
+    convenience).
+    """
+
+    async def publish(self, event: DomainEvent) -> None: ...
+
+
+class UnitOfWork:
+    """Transactional unit-of-work scoped to one logical operation."""
+
+    def __init__(
+        self,
+        session_factory: SessionFactory,
+        dispatcher: EventDispatcher | None,
+        outbox: OutboxRecorder | None = None,
+    ) -> None:
+        self._factory = session_factory
+        self._dispatcher = dispatcher
+        self._outbox = outbox
+        self._session: AsyncSession | None = None
+        self._tracked: list[AggregateRoot[Any]] = []
+        self._committed = False
+        self._rolled_back = False
+
+    @property
+    def session(self) -> AsyncSession:
+        if self._session is None:
+            raise RuntimeError("UnitOfWork session accessed outside of `async with` block")
+        return self._session
+
+    def track(self, aggregate: AggregateRoot[Any]) -> None:
+        """Register an aggregate so its domain events get drained on commit.
+
+        Repositories that follow ``qx-db`` conventions call this from
+        ``add`` and ``save`` automatically. Aggregates loaded for read can also
+        be tracked if their events need to be dispatched (rare).
+        """
+        if aggregate not in self._tracked:
+            self._tracked.append(aggregate)
+
+    async def commit(self) -> None:
+        """Drain events, route to in-process + outbox, then commit the SQL transaction.
+
+        All event work happens **inside** the open transaction. If the dispatcher
+        fails (an in-process handler raised), or the outbox insert fails, the
+        commit doesn't happen — the whole unit-of-work rolls back. This is the
+        outbox pattern's atomic guarantee.
+        """
+        if self._session is None:
+            raise RuntimeError("UnitOfWork.commit called outside async with block")
+        if self._committed or self._rolled_back:
+            return
+
+        # Drain events from every tracked aggregate.
+        domain_events: list[DomainEvent] = []
+        integration_events: list[IntegrationEvent] = []
+        for agg in self._tracked:
+            for ev in agg.pull_events():
+                # Stamp correlation/tenant from the active request context so
+                # downstream consumers can correlate. Aggregates don't see the
+                # request context directly — UoW is the right place to enrich.
+                ctx = current_context()
+                enriched = ev.model_copy(
+                    update={
+                        "correlation_id": ev.correlation_id or ctx.correlation_id,
+                        "tenant_id": ev.tenant_id or ctx.tenant_id,
+                        "actor_id": ev.actor_id or ctx.user_id,
+                    }
+                )
+                if isinstance(enriched, IntegrationEvent):
+                    integration_events.append(enriched)
+                elif isinstance(enriched, DomainEvent):
+                    domain_events.append(enriched)
+
+        # Dispatch in-process domain events first (still inside txn).
+        if self._dispatcher is not None:
+            for ev in domain_events:
+                await self._dispatcher.publish(ev)
+
+        # Write integration events to outbox (still inside txn).
+        if self._outbox is not None and integration_events:
+            await self._outbox.record(self._session, integration_events)
+
+        await self._session.commit()
+        self._committed = True
+
+    async def rollback(self) -> None:
+        if self._session is None or self._rolled_back or self._committed:
+            return
+        await self._session.rollback()
+        self._rolled_back = True
+
+    async def __aenter__(self) -> UnitOfWork:
+        self._session = self._factory()
+        await self._session.begin()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        try:
+            if exc is not None:
+                await self.rollback()
+            elif not self._committed and not self._rolled_back:
+                # No explicit commit — implicit rollback. Forces callers to be
+                # deliberate; silent commits on `async with` exit hide bugs.
+                await self.rollback()
+        finally:
+            if self._session is not None:
+                await self._session.close()
+                self._session = None

qx_db-0.1.0/tests/test_db_unit.py

@@ -0,0 +1,77 @@
+"""Tests for qx-db pure logic (cursor encode/decode, outbox table shape).
+
+The repository / UoW / outbox-relay integration tests live under
+``tests/integration`` and require Docker (testcontainers). Those run in CI
+against a real Postgres; here we keep the unit tests fast.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from qx.core.types.pagination import Sort
+from qx.db.outbox import OUTBOX_TABLE_NAME, include_outbox_table
+from qx.db.pagination import (
+    build_cursor_page,
+    decode_cursor,
+    encode_cursor,
+)
+from sqlalchemy import MetaData
+
+
+def test_cursor_roundtrip_strings() -> None:
+    payload = {"id": str(uuid4()), "created_at": "2024-01-01T00:00:00+00:00"}
+    cursor = encode_cursor(payload)
+    decoded = decode_cursor(cursor)
+    assert decoded == payload
+
+
+def test_cursor_handles_datetime() -> None:
+    payload = {"created_at": datetime(2024, 1, 1, tzinfo=UTC)}
+    cursor = encode_cursor(payload)
+    decoded = decode_cursor(cursor)
+    assert decoded["created_at"].startswith("2024-01-01")
+
+
+def test_cursor_is_opaque_text() -> None:
+    cursor = encode_cursor({"id": "x"})
+    # Should be safe to put in a URL — base64url, no padding.
+    assert "=" not in cursor
+    assert "/" not in cursor
+
+
+def test_build_cursor_page_returns_trimmed_items_and_cursor() -> None:
+    from types import SimpleNamespace  # noqa: PLC0415
+
+    rows = [
+        SimpleNamespace(id=str(i), created_at=datetime(2024, 1, i + 1, tzinfo=UTC))
+        for i in range(6)
+    ]
+    page = build_cursor_page(
+        rows,
+        limit=5,
+        sort=(Sort(field="created_at", direction="asc"),),
+        cursor_fields=("created_at", "id"),
+    )
+    assert len(page.items) == 5
+    assert page.has_next is True
+    assert page.next_cursor is not None
+
+
+def test_build_cursor_page_no_next_when_under_limit() -> None:
+    from types import SimpleNamespace  # noqa: PLC0415
+
+    rows = [SimpleNamespace(id=str(i)) for i in range(3)]
+    page = build_cursor_page(rows, limit=5, sort=(), cursor_fields=("id",))
+    assert page.has_next is False
+    assert page.next_cursor is None
+
+
+def test_outbox_table_registers_in_metadata() -> None:
+    md = MetaData()
+    table = include_outbox_table(md)
+    assert OUTBOX_TABLE_NAME in md.tables
+    assert "event_name" in table.c
+    assert "payload" in table.c
+    assert "published_at" in table.c