python-cqrs 4.11.0__tar.gz → 4.13.0__tar.gz

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.11.0
+Version: 4.13.0
 Summary: Event-Driven Architecture Framework for Distributed Systems
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>, Dmitry Kutlubaev <kutlubaev00@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
@@ -42,7 +42,8 @@ Requires-Dist: requests==2.*; extra == "dev"
 Requires-Dist: pytest~=7.4.2; extra == "dev"
 Requires-Dist: pytest-asyncio~=0.21.1; extra == "dev"
 Requires-Dist: pytest-env==0.6.2; extra == "dev"
-Requires-Dist: cryptography==48.0.1; extra == "dev"
+Requires-Dist: alembic>=1.13.0; extra == "dev"
+Requires-Dist: cryptography==50.0.0; extra == "dev"
 Requires-Dist: asyncmy==0.2.9; extra == "dev"
 Requires-Dist: asyncpg>=0.29.0; extra == "dev"
 Requires-Dist: redis>=5.0.0; extra == "dev"
@@ -52,8 +53,9 @@ Requires-Dist: fastapi==0.109.*; extra == "examples"
 Requires-Dist: faststream[kafka]==0.5.28; extra == "examples"
 Requires-Dist: faker>=37.12.0; extra == "examples"
 Requires-Dist: uvicorn==0.32.0; extra == "examples"
-Requires-Dist: aiohttp==3.14.1; extra == "examples"
+Requires-Dist: aiohttp==3.14.3; extra == "examples"
 Requires-Dist: protobuf>=4.25.8; extra == "examples"
+Requires-Dist: aiosqlite>=0.20.0; extra == "examples"
 Provides-Extra: kafka
 Requires-Dist: aiokafka==0.10.0; extra == "kafka"
 Requires-Dist: retry-async==0.1.*; extra == "kafka"
@@ -108,6 +110,7 @@ Dynamic: license-file
 ## Table of Contents
 
 - [Overview](#overview)
+- [When NOT to use python-cqrs](#when-not-to-use-python-cqrs)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Request and Response Types](#request-and-response-types)
@@ -150,10 +153,21 @@ project ([documentation](https://akhundmurad.github.io/diator/)) with several en
 
 - **Typing:** Pydantic [v2.*](https://docs.pydantic.dev/2.8/) and `IRequest`/`IResponse` interfaces — use Pydantic-based, dataclass-based, or custom Request/Response implementations.
 - **Broker:** Kafka via [aiokafka](https://github.com/aio-libs/aiokafka).
+- **Storage:** SQLAlchemy-based Outbox and Saga storage on MySQL/MariaDB and PostgreSQL.
 - **Integration:** Ready for integration with FastAPI and FastStream.
 - **Documentation:** Built-in Mermaid diagram generation (Sequence and Class diagrams).
 - **Protobuf:** Interface-level support for converting Notification events to Protobuf and back.
 
+## When NOT to use python-cqrs
+
+CQRS, Outbox, and Saga are tools for specific problems — not a default for every service.
+
+- **Prefer a local DB transaction** for single-service CRUD (one database, no broker, no compensation).
+- **Use [Transactional Outbox](#transactional-outbox)** when you dual-write to a database **and** a message broker. Commit the business row and the outbox row together; a publisher drains the outbox later.
+- **Use [Saga](#saga-pattern)** when a multi-step flow crosses service/database boundaries and a later step must be compensated if it fails.
+
+Do not add a Saga for a single `UPDATE` in one service, and do not use a Saga as a substitute for Outbox. Full write-up: [When NOT to use python-cqrs](docs/when_not_to_use.md).
+
 ## Installation
 
 **Python 3.10+** is required.
@@ -860,10 +874,19 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
 A complete example can be found in
 the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/save_events_into_outbox.py)
 
-> [!TIP]
-> You can specify the name of the Outbox table using the environment variable `OUTBOX_SQLA_TABLE`.
-> By default, it is set to `outbox`.
+A runnable FastAPI flow (route → command → transactional outbox → publisher stub) is in
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_outbox.py)
 
+> [!TIP]
+> The Outbox table is named `outbox` by default. To rename it, or to attach the model to your own declarative
+> base, use `cqrs.rebind_outbox_model(OutboxModel, Base, table_name="my_outbox_table")` at startup — before
+> `create_all()`, before generating migrations and before the first query.
+> [!TIP]
+> `SqlAlchemyOutboxedEventRepository` works on **MySQL/MariaDB** and **PostgreSQL**: the outbox columns are
+> rendered with dialect-aware types (`BINARY(16)` on MySQL, `UUID`/`BYTEA` on PostgreSQL), with a portable
+> `BLOB` fallback for other dialects. Switching databases is a DSN change only — see the
+> [Database Support](https://mkdocs.python-cqrs.dev/outbox/databases/) docs for the DDL, the Alembic recipe and
+> how to register a native type for your own database.
 > [!TIP]
 > If you use the protobuf events you should specify `OutboxedEventRepository`
 > by [protobuf serialize](https://github.com/vadikko2/python-cqrs/blob/master/src/cqrs/serializers/protobuf.py). A complete example can be found in
@@ -1019,6 +1042,9 @@ async def join_metting(
 A complete example can be found in
 the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_integration.py)
 
+End-to-end command + outbox sample (business row and outbox event in one transaction, plus a publisher stub):
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_outbox.py)
+
 ### Kafka events consuming
 
 If you build interaction by events over broker like `Kafka`, you can to implement an event consumer on your

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/README.md

@@ -43,6 +43,7 @@
 ## Table of Contents
 
 - [Overview](#overview)
+- [When NOT to use python-cqrs](#when-not-to-use-python-cqrs)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Request and Response Types](#request-and-response-types)
@@ -85,10 +86,21 @@ project ([documentation](https://akhundmurad.github.io/diator/)) with several en
 
 - **Typing:** Pydantic [v2.*](https://docs.pydantic.dev/2.8/) and `IRequest`/`IResponse` interfaces — use Pydantic-based, dataclass-based, or custom Request/Response implementations.
 - **Broker:** Kafka via [aiokafka](https://github.com/aio-libs/aiokafka).
+- **Storage:** SQLAlchemy-based Outbox and Saga storage on MySQL/MariaDB and PostgreSQL.
 - **Integration:** Ready for integration with FastAPI and FastStream.
 - **Documentation:** Built-in Mermaid diagram generation (Sequence and Class diagrams).
 - **Protobuf:** Interface-level support for converting Notification events to Protobuf and back.
 
+## When NOT to use python-cqrs
+
+CQRS, Outbox, and Saga are tools for specific problems — not a default for every service.
+
+- **Prefer a local DB transaction** for single-service CRUD (one database, no broker, no compensation).
+- **Use [Transactional Outbox](#transactional-outbox)** when you dual-write to a database **and** a message broker. Commit the business row and the outbox row together; a publisher drains the outbox later.
+- **Use [Saga](#saga-pattern)** when a multi-step flow crosses service/database boundaries and a later step must be compensated if it fails.
+
+Do not add a Saga for a single `UPDATE` in one service, and do not use a Saga as a substitute for Outbox. Full write-up: [When NOT to use python-cqrs](docs/when_not_to_use.md).
+
 ## Installation
 
 **Python 3.10+** is required.
@@ -795,10 +807,19 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
 A complete example can be found in
 the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/save_events_into_outbox.py)
 
-> [!TIP]
-> You can specify the name of the Outbox table using the environment variable `OUTBOX_SQLA_TABLE`.
-> By default, it is set to `outbox`.
+A runnable FastAPI flow (route → command → transactional outbox → publisher stub) is in
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_outbox.py)
 
+> [!TIP]
+> The Outbox table is named `outbox` by default. To rename it, or to attach the model to your own declarative
+> base, use `cqrs.rebind_outbox_model(OutboxModel, Base, table_name="my_outbox_table")` at startup — before
+> `create_all()`, before generating migrations and before the first query.
+> [!TIP]
+> `SqlAlchemyOutboxedEventRepository` works on **MySQL/MariaDB** and **PostgreSQL**: the outbox columns are
+> rendered with dialect-aware types (`BINARY(16)` on MySQL, `UUID`/`BYTEA` on PostgreSQL), with a portable
+> `BLOB` fallback for other dialects. Switching databases is a DSN change only — see the
+> [Database Support](https://mkdocs.python-cqrs.dev/outbox/databases/) docs for the DDL, the Alembic recipe and
+> how to register a native type for your own database.
 > [!TIP]
 > If you use the protobuf events you should specify `OutboxedEventRepository`
 > by [protobuf serialize](https://github.com/vadikko2/python-cqrs/blob/master/src/cqrs/serializers/protobuf.py). A complete example can be found in
@@ -954,6 +975,9 @@ async def join_metting(
 A complete example can be found in
 the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_integration.py)
 
+End-to-end command + outbox sample (business row and outbox event in one transaction, plus a publisher stub):
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_outbox.py)
+
 ### Kafka events consuming
 
 If you build interaction by events over broker like `Kafka`, you can to implement an event consumer on your

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/pyproject.toml

@@ -4,8 +4,8 @@ requires = ["setuptools>=42", "wheel"]
 
 [project]
 authors = [
-  {name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru"},
-  {name = "Dmitry Kutlubaev", email = "kutlubaev00@mail.ru"}
+  { name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru" },
+  { name = "Dmitry Kutlubaev", email = "kutlubaev00@mail.ru" },
 ]
 classifiers = [
   "Development Status :: 4 - Beta",
@@ -14,7 +14,7 @@ classifiers = [
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
-  "Programming Language :: Python :: 3.13"
+  "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
   "dataclass-wizard==0.*",
@@ -24,14 +24,14 @@ dependencies = [
   "pydantic==2.*",
   "sqlalchemy[asyncio]==2.0.*",
   "python-dotenv==1.*",
-  "typing-extensions>=4.0"
+  "typing-extensions>=4.0",
 ]
 description = "Event-Driven Architecture Framework for Distributed Systems"
-maintainers = [{name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru"}]
+maintainers = [{ name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru" }]
 name = "python-cqrs"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "4.11.0"
+version = "4.13.0"
 
 [project.optional-dependencies]
 aiobreaker = ["aiobreaker>=0.3.0"]
@@ -45,27 +45,29 @@ dev = [
   "pytest-cov>=4.0.0",
   "pytest-codspeed==4.2.0",
   # Tests
-  "aio-pika==9.3.0",  # from rabbit
-  "aiokafka==0.10.0",  # from kafka
-  "retry-async==0.1.*", # from kafka
-  "requests==2.*",  # from aiokafka
+  "aio-pika==9.3.0",        # from rabbit
+  "aiokafka==0.10.0",       # from kafka
+  "retry-async==0.1.*",     # from kafka
+  "requests==2.*",          # from aiokafka
   "pytest~=7.4.2",
   "pytest-asyncio~=0.21.1",
   "pytest-env==0.6.2",
-  "cryptography==48.0.1",
+  "alembic>=1.13.0",  # from outbox migrations tests
+  "cryptography==50.0.0",
   "asyncmy==0.2.9",
   "asyncpg>=0.29.0",
   "redis>=5.0.0",
   # Circuit breaker for tests
-  "aiobreaker>=0.3.0"  # from aiobreaker
+  "aiobreaker>=0.3.0", # from aiobreaker
 ]
 examples = [
   "fastapi==0.109.*",
   "faststream[kafka]==0.5.28",
   "faker>=37.12.0",
   "uvicorn==0.32.0",
-  "aiohttp==3.14.1",
+  "aiohttp==3.14.3",
   "protobuf>=4.25.8",
+  "aiosqlite>=0.20.0",
 ]
 kafka = ["aiokafka==0.10.0", "retry-async==0.1.*"]
 rabbit = ["aio-pika==9.3.0"]

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/src/cqrs/__init__.py

@@ -54,6 +54,14 @@ from cqrs.saga.step import (
     SagaStepHandler,
     SagaStepResult,
 )
+from cqrs.sqlalchemy_types import (
+    Binary16,
+    DialectAwareType,
+    DialectTypeHandler,
+    JSONType,
+    PayloadBinary,
+    UUIDBinary,
+)
 
 __all__ = (
     "ICircuitBreaker",
@@ -108,4 +116,10 @@ __all__ = (
     "ContextT",
     "SagaMermaid",
     "CoRMermaid",
+    "DialectAwareType",
+    "DialectTypeHandler",
+    "UUIDBinary",
+    "Binary16",
+    "JSONType",
+    "PayloadBinary",
 )

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/src/cqrs/events/event_emitter.py

@@ -1,3 +1,4 @@
+import asyncio
 import functools
 import logging
 import typing
@@ -169,22 +170,32 @@ class EventEmitter:
                 type(event).__name__,
             )
             return ()
+
+        results = await asyncio.gather(
+            *(self._process_single_handler(event, item) for item in handlers_types),
+            return_exceptions=True,
+        )
+
         follow_ups: list[IEvent] = []
-        for handler_item in handlers_types:
-            if isinstance(handler_item, EventHandlerFallback):
-                follow_ups.extend(
-                    await self._handle_with_fallback(event, handler_item),
+        for handler_item, res in zip(handlers_types, results):
+            if isinstance(res, Exception):
+                handler_name = (
+                    handler_item.primary.__name__
+                    if isinstance(handler_item, EventHandlerFallback)
+                    else handler_item.__name__
                 )
-                continue
-            handler_type = handler_item
-            handler: _H = await self._container.resolve(handler_type)
-            logger.debug(
-                "Handling Event(%s) via event handler(%s)",
-                type(event).__name__,
-                handler_type.__name__,
-            )
-            await handler.handle(event)
-            follow_ups.extend(list(handler.events))
+                logger.exception(
+                    "Error occurred while processing domain event %s in handler %s: %s",
+                    type(event).__name__,
+                    handler_name,
+                    res,
+                    exc_info=res,
+                )
+            elif isinstance(res, BaseException):
+                raise res
+            else:
+                follow_ups.extend(res)
+
         return follow_ups
 
     @emit.register(INotificationEvent)
@@ -192,3 +203,22 @@ class EventEmitter:
         """Emit notification event: send to message broker; no follow-ups."""
         await self._send_to_broker(event)
         return ()
+
+    async def _process_single_handler(
+        self,
+        event: IDomainEvent,
+        handler_item: typing.Union[typing.Type[_H], EventHandlerFallback],
+    ) -> typing.Sequence[IEvent]:
+        """Process a single event handler and return its follow-up events."""
+        if isinstance(handler_item, EventHandlerFallback):
+            return await self._handle_with_fallback(event, handler_item)
+
+        handler_type = handler_item
+        handler: _H = await self._container.resolve(handler_type)
+        logger.debug(
+            "Handling Event(%s) via event handler(%s)",
+            type(event).__name__,
+            handler_type.__name__,
+        )
+        await handler.handle(event)
+        return list(handler.events)

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/src/cqrs/outbox/sqlalchemy.py

@@ -15,7 +15,8 @@ try:
     from sqlalchemy import func
     from sqlalchemy.orm import Mapped, mapped_column, DeclarativeMeta, registry
     from sqlalchemy.ext.asyncio import session as sql_session
-    from sqlalchemy.dialects import postgresql
+
+    from cqrs import sqlalchemy_types
 except ImportError:
     raise ImportError(
         "You are trying to use SQLAlchemy outbox implementation, "
@@ -35,37 +36,10 @@ DEFAULT_OUTBOX_TABLE_NAME = "outbox"
 MAX_FLUSH_COUNTER_VALUE = 5
 
 
-class BinaryUUID(sqlalchemy.TypeDecorator):
-    """Stores the UUID as a native UUID in Postgres and as BINARY(16) in other databases (MySQL)."""
-
-    impl = sqlalchemy.BINARY(16)
-    cache_ok = True
-
-    def load_dialect_impl(self, dialect):
-        if dialect.name == "postgresql":
-            return dialect.type_descriptor(postgresql.UUID())
-        else:
-            return dialect.type_descriptor(sqlalchemy.BINARY(16))
-
-    def process_bind_param(self, value, dialect):
-        if value is None:
-            return value
-        if isinstance(value, str):
-            value = uuid.UUID(value)
-        if dialect.name == "postgresql":
-            return value  # asyncpg works with uuid.UUID
-        if isinstance(value, uuid.UUID):
-            return value.bytes  # For MySQL return 16 bytes
-        return value
-
-    def process_result_value(self, value, dialect):
-        if value is None:
-            return value
-        if dialect.name == "postgresql":
-            return value  # asyncpg return uuid.UUID
-        if isinstance(value, bytes):
-            return uuid.UUID(bytes=value)  # From MySQL got bytes, make UUID
-        return value
+# Deprecated name of cqrs.sqlalchemy_types.UUIDBinary — kept importable for
+# backward compatibility (e.g. already generated Alembic migrations).
+# Prefer cqrs.sqlalchemy_types.UUIDBinary in new code.
+BinaryUUID = sqlalchemy_types.UUIDBinary
 
 
 class OutboxModel(Base):
@@ -87,12 +61,12 @@ class OutboxModel(Base):
         comment="Identity",
     )
     event_id: Mapped[uuid.UUID] = mapped_column(
-        BinaryUUID,
+        sqlalchemy_types.UUIDBinary,
         nullable=False,
         comment="Event idempotency id",
     )
     event_id_bin: Mapped[bytes] = mapped_column(
-        sqlalchemy.BINARY(16),
+        sqlalchemy_types.Binary16,
         nullable=False,
         comment="Event idempotency id in 16 bit presentation",
     )
@@ -126,7 +100,7 @@ class OutboxModel(Base):
         comment="Event creation timestamp",
     )
     payload: Mapped[bytes] = mapped_column(
-        sqlalchemy.LargeBinary,
+        sqlalchemy_types.PayloadBinary,
         nullable=False,
         comment="Event payload",
     )
@@ -177,13 +151,14 @@ class OutboxModel(Base):
 
     @classmethod
     def status_sorting_case(cls) -> sqlalchemy.Case:
+        # Conditions instead of a `value=` mapping: only a comparison with the
+        # column binds the statuses through the Enum type. As plain mapping keys
+        # they are sent as enum values ("new"), which PostgreSQL rejects because
+        # its `eventstatus` type holds member names ("NEW").
         return sqlalchemy.case(
-            {
-                repository.EventStatus.NEW: 1,
-                repository.EventStatus.NOT_PRODUCED: 2,
-                repository.EventStatus.PRODUCED: 3,
-            },
-            value=cls.event_status,
+            (cls.event_status == repository.EventStatus.NEW, 1),
+            (cls.event_status == repository.EventStatus.NOT_PRODUCED, 2),
+            (cls.event_status == repository.EventStatus.PRODUCED, 3),
             else_=4,
         )
 

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/src/cqrs/saga/storage/sqlalchemy.py

@@ -17,6 +17,8 @@ try:
     from sqlalchemy.exc import SQLAlchemyError
     from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
     from sqlalchemy.orm import registry
+
+    from cqrs.sqlalchemy_types import JSONType
 except ImportError:
     raise ImportError(
         "You are trying to use SQLAlchemy saga storage implementation, "
@@ -63,7 +65,7 @@ class SagaExecutionModel(Base):
         comment="Current status of the saga",
     )
     context = sqlalchemy.Column(
-        sqlalchemy.JSON,
+        JSONType,
         nullable=False,
         comment="Serialized context",
     )

python_cqrs-4.13.0/src/cqrs/sqlalchemy_types.py

@@ -0,0 +1,237 @@
+"""Dialect-aware SQLAlchemy types shared by the library models.
+
+The module generalizes the trick used by the outbox model: a single Python type
+is rendered as the most suitable native type of the current dialect. Mapping
+between a dialect and its DDL type/value conversion is kept in a per-class
+registry, so support for a new DBMS is one `register_dialect` call away.
+"""
+
+import dataclasses
+import typing
+import uuid
+
+try:
+    import sqlalchemy
+
+    from sqlalchemy.dialects import mysql, postgresql
+except ImportError:
+    raise ImportError(
+        "You are trying to use SQLAlchemy types, "
+        "but 'sqlalchemy' is not installed. "
+        "Please install it using: pip install python-cqrs[sqlalchemy]",
+    ) from None
+
+__all__ = (
+    "Binary16",
+    "DialectAwareType",
+    "DialectTypeHandler",
+    "JSONType",
+    "PayloadBinary",
+    "UUIDBinary",
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class DialectTypeHandler:
+    """Describes how a type lives in a particular dialect.
+
+    Attributes:
+        type_factory: builds the dialect native type used in DDL and binding.
+        bind: converts a Python value into the dialect representation.
+        result: converts a value fetched from the database into a Python one.
+    """
+
+    type_factory: typing.Callable[[typing.Any], typing.Any]
+    bind: typing.Callable[[typing.Any], typing.Any] | None = None
+    result: typing.Callable[[typing.Any], typing.Any] | None = None
+
+
+class DialectAwareType(sqlalchemy.TypeDecorator):
+    """Base class for types resolved through a per-dialect registry.
+
+    Subclasses declare a `default_handler` used as a portable fallback and
+    register dialect specific handlers via `register_dialect`. Every subclass
+    owns its registry, so registrations never leak between types.
+    """
+
+    impl = sqlalchemy.LargeBinary
+    cache_ok = True
+
+    default_handler: typing.ClassVar[DialectTypeHandler]
+    _handlers: typing.ClassVar[typing.Dict[typing.Text, DialectTypeHandler]] = {}
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+        # Each subclass owns its registry, otherwise a registration made for one
+        # type would leak into all the others.
+        cls._handlers = dict(cls._handlers)
+
+    @classmethod
+    def register_dialect(
+        cls,
+        dialect_name: typing.Text,
+        handler: DialectTypeHandler,
+    ) -> None:
+        """Registers (or overrides) the handler used for `dialect_name`."""
+        cls._handlers[dialect_name] = handler
+
+    @classmethod
+    def get_handler(cls, dialect_name: typing.Text) -> DialectTypeHandler:
+        """Returns the handler for `dialect_name` or the portable fallback."""
+        return cls._handlers.get(dialect_name, cls.default_handler)
+
+    def load_dialect_impl(self, dialect):
+        handler = self.get_handler(dialect.name)
+        return dialect.type_descriptor(handler.type_factory(dialect))
+
+    def process_bind_param(self, value, dialect):
+        if value is None:
+            return value
+        handler = self.get_handler(dialect.name)
+        if handler.bind is None:
+            return value
+        return handler.bind(value)
+
+    def process_result_value(self, value, dialect):
+        if value is None:
+            return value
+        handler = self.get_handler(dialect.name)
+        if handler.result is None:
+            return value
+        return handler.result(value)
+
+
+def _as_uuid(value: typing.Any) -> typing.Any:
+    if isinstance(value, str):
+        return uuid.UUID(value)
+    return value
+
+
+def _as_bytes(value: typing.Any) -> typing.Any:
+    value = _as_uuid(value)
+    if isinstance(value, uuid.UUID):
+        return value.bytes
+    return value
+
+
+def _as_uuid_from_bytes(value: typing.Any) -> typing.Any:
+    if isinstance(value, bytes):
+        return uuid.UUID(bytes=value)
+    return value
+
+
+class UUIDBinary(DialectAwareType):
+    """`uuid.UUID` stored as a native UUID in PostgreSQL and as BINARY(16) elsewhere."""
+
+    default_handler = DialectTypeHandler(
+        type_factory=lambda dialect: sqlalchemy.LargeBinary(16),
+        bind=_as_bytes,
+        result=_as_uuid_from_bytes,
+    )
+
+
+UUIDBinary.register_dialect(
+    "postgresql",
+    DialectTypeHandler(
+        # asyncpg works with uuid.UUID, no conversion is needed.
+        type_factory=lambda dialect: postgresql.UUID(as_uuid=True),
+        bind=_as_uuid,
+    ),
+)
+UUIDBinary.register_dialect(
+    "mysql",
+    DialectTypeHandler(
+        type_factory=lambda dialect: mysql.BINARY(16),
+        bind=_as_bytes,
+        result=_as_uuid_from_bytes,
+    ),
+)
+UUIDBinary.register_dialect("mariadb", UUIDBinary.get_handler("mysql"))
+
+
+class Binary16(DialectAwareType):
+    """Raw 16 bytes: BYTEA in PostgreSQL, BINARY(16) in MySQL, LargeBinary(16) elsewhere."""
+
+    default_handler = DialectTypeHandler(
+        type_factory=lambda dialect: sqlalchemy.LargeBinary(16),
+        bind=_as_bytes,
+    )
+
+
+Binary16.register_dialect(
+    "postgresql",
+    DialectTypeHandler(
+        type_factory=lambda dialect: postgresql.BYTEA(),
+        bind=_as_bytes,
+    ),
+)
+Binary16.register_dialect(
+    "mysql",
+    DialectTypeHandler(
+        type_factory=lambda dialect: mysql.BINARY(16),
+        bind=_as_bytes,
+    ),
+)
+Binary16.register_dialect("mariadb", Binary16.get_handler("mysql"))
+
+
+class JSONType(DialectAwareType):
+    """JSON document rendered as plain `JSON` on every dialect.
+
+    The default handler intentionally repeats `sqlalchemy.JSON`, so switching a
+    column to this type does not change the generated DDL anywhere. It only adds
+    an extension point: a project that wants a native PostgreSQL `JSONB` enables
+    it with a single registration, without touching the library models.
+
+    ```python
+    from sqlalchemy.dialects import postgresql
+    from cqrs.sqlalchemy_types import DialectTypeHandler, JSONType
+
+    JSONType.register_dialect(
+        "postgresql",
+        DialectTypeHandler(type_factory=lambda dialect: postgresql.JSONB()),
+    )
+    ```
+
+    No value conversion is performed: serialization stays the responsibility of
+    the dialect level JSON type, exactly as with `sqlalchemy.JSON`.
+    """
+
+    impl = sqlalchemy.JSON
+    cache_ok = True
+
+    default_handler = DialectTypeHandler(
+        type_factory=lambda dialect: sqlalchemy.JSON(),
+    )
+
+
+class PayloadBinary(DialectAwareType):
+    """Binary blob of an arbitrary length rendered as plain `LargeBinary` everywhere.
+
+    The default handler intentionally repeats `sqlalchemy.LargeBinary` without a
+    length, so switching a column to this type keeps the DDL identical on every
+    dialect (`BYTEA` in PostgreSQL, `BLOB` in MySQL and SQLite). It only adds an
+    extension point for a DBMS the library knows nothing about: Microsoft SQL
+    Server, for instance, maps `LargeBinary` to the deprecated `IMAGE`, which a
+    project fixes with a single registration.
+
+    ```python
+    from sqlalchemy.dialects import mssql
+    from cqrs.sqlalchemy_types import DialectTypeHandler, PayloadBinary
+
+    PayloadBinary.register_dialect(
+        "mssql",
+        DialectTypeHandler(type_factory=lambda dialect: mssql.VARBINARY("max")),
+    )
+    ```
+
+    No value conversion is performed: the column holds `bytes` and they are
+    passed to the driver as is.
+    """
+
+    impl = sqlalchemy.LargeBinary
+    cache_ok = True
+
+    default_handler = DialectTypeHandler(
+        type_factory=lambda dialect: sqlalchemy.LargeBinary(),
+    )

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/src/python_cqrs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.11.0
+Version: 4.13.0
 Summary: Event-Driven Architecture Framework for Distributed Systems
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>, Dmitry Kutlubaev <kutlubaev00@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>
@@ -42,7 +42,8 @@ Requires-Dist: requests==2.*; extra == "dev"
 Requires-Dist: pytest~=7.4.2; extra == "dev"
 Requires-Dist: pytest-asyncio~=0.21.1; extra == "dev"
 Requires-Dist: pytest-env==0.6.2; extra == "dev"
-Requires-Dist: cryptography==48.0.1; extra == "dev"
+Requires-Dist: alembic>=1.13.0; extra == "dev"
+Requires-Dist: cryptography==50.0.0; extra == "dev"
 Requires-Dist: asyncmy==0.2.9; extra == "dev"
 Requires-Dist: asyncpg>=0.29.0; extra == "dev"
 Requires-Dist: redis>=5.0.0; extra == "dev"
@@ -52,8 +53,9 @@ Requires-Dist: fastapi==0.109.*; extra == "examples"
 Requires-Dist: faststream[kafka]==0.5.28; extra == "examples"
 Requires-Dist: faker>=37.12.0; extra == "examples"
 Requires-Dist: uvicorn==0.32.0; extra == "examples"
-Requires-Dist: aiohttp==3.14.1; extra == "examples"
+Requires-Dist: aiohttp==3.14.3; extra == "examples"
 Requires-Dist: protobuf>=4.25.8; extra == "examples"
+Requires-Dist: aiosqlite>=0.20.0; extra == "examples"
 Provides-Extra: kafka
 Requires-Dist: aiokafka==0.10.0; extra == "kafka"
 Requires-Dist: retry-async==0.1.*; extra == "kafka"
@@ -108,6 +110,7 @@ Dynamic: license-file
 ## Table of Contents
 
 - [Overview](#overview)
+- [When NOT to use python-cqrs](#when-not-to-use-python-cqrs)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Request and Response Types](#request-and-response-types)
@@ -150,10 +153,21 @@ project ([documentation](https://akhundmurad.github.io/diator/)) with several en
 
 - **Typing:** Pydantic [v2.*](https://docs.pydantic.dev/2.8/) and `IRequest`/`IResponse` interfaces — use Pydantic-based, dataclass-based, or custom Request/Response implementations.
 - **Broker:** Kafka via [aiokafka](https://github.com/aio-libs/aiokafka).
+- **Storage:** SQLAlchemy-based Outbox and Saga storage on MySQL/MariaDB and PostgreSQL.
 - **Integration:** Ready for integration with FastAPI and FastStream.
 - **Documentation:** Built-in Mermaid diagram generation (Sequence and Class diagrams).
 - **Protobuf:** Interface-level support for converting Notification events to Protobuf and back.
 
+## When NOT to use python-cqrs
+
+CQRS, Outbox, and Saga are tools for specific problems — not a default for every service.
+
+- **Prefer a local DB transaction** for single-service CRUD (one database, no broker, no compensation).
+- **Use [Transactional Outbox](#transactional-outbox)** when you dual-write to a database **and** a message broker. Commit the business row and the outbox row together; a publisher drains the outbox later.
+- **Use [Saga](#saga-pattern)** when a multi-step flow crosses service/database boundaries and a later step must be compensated if it fails.
+
+Do not add a Saga for a single `UPDATE` in one service, and do not use a Saga as a substitute for Outbox. Full write-up: [When NOT to use python-cqrs](docs/when_not_to_use.md).
+
 ## Installation
 
 **Python 3.10+** is required.
@@ -860,10 +874,19 @@ class JoinMeetingCommandHandler(cqrs.RequestHandler[JoinMeetingCommand, None]):
 A complete example can be found in
 the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/save_events_into_outbox.py)
 
-> [!TIP]
-> You can specify the name of the Outbox table using the environment variable `OUTBOX_SQLA_TABLE`.
-> By default, it is set to `outbox`.
+A runnable FastAPI flow (route → command → transactional outbox → publisher stub) is in
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_outbox.py)
 
+> [!TIP]
+> The Outbox table is named `outbox` by default. To rename it, or to attach the model to your own declarative
+> base, use `cqrs.rebind_outbox_model(OutboxModel, Base, table_name="my_outbox_table")` at startup — before
+> `create_all()`, before generating migrations and before the first query.
+> [!TIP]
+> `SqlAlchemyOutboxedEventRepository` works on **MySQL/MariaDB** and **PostgreSQL**: the outbox columns are
+> rendered with dialect-aware types (`BINARY(16)` on MySQL, `UUID`/`BYTEA` on PostgreSQL), with a portable
+> `BLOB` fallback for other dialects. Switching databases is a DSN change only — see the
+> [Database Support](https://mkdocs.python-cqrs.dev/outbox/databases/) docs for the DDL, the Alembic recipe and
+> how to register a native type for your own database.
 > [!TIP]
 > If you use the protobuf events you should specify `OutboxedEventRepository`
 > by [protobuf serialize](https://github.com/vadikko2/python-cqrs/blob/master/src/cqrs/serializers/protobuf.py). A complete example can be found in
@@ -1019,6 +1042,9 @@ async def join_metting(
 A complete example can be found in
 the [documentation](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_integration.py)
 
+End-to-end command + outbox sample (business row and outbox event in one transaction, plus a publisher stub):
+[fastapi_outbox.py](https://github.com/vadikko2/python-cqrs/blob/master/examples/fastapi_outbox.py)
+
 ### Kafka events consuming
 
 If you build interaction by events over broker like `Kafka`, you can to implement an event consumer on your

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/src/python_cqrs.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/cqrs/generic_utils.py
 src/cqrs/mediator.py
 src/cqrs/producer.py
 src/cqrs/response.py
+src/cqrs/sqlalchemy_types.py
 src/cqrs/types.py
 src/cqrs/adapters/__init__.py
 src/cqrs/adapters/amqp.py

{python_cqrs-4.11.0 → python_cqrs-4.13.0}/src/python_cqrs.egg-info/requires.txt

@@ -25,7 +25,8 @@ requests==2.*
 pytest~=7.4.2
 pytest-asyncio~=0.21.1
 pytest-env==0.6.2
-cryptography==48.0.1
+alembic>=1.13.0
+cryptography==50.0.0
 asyncmy==0.2.9
 asyncpg>=0.29.0
 redis>=5.0.0
@@ -36,8 +37,9 @@ fastapi==0.109.*
 faststream[kafka]==0.5.28
 faker>=37.12.0
 uvicorn==0.32.0
-aiohttp==3.14.1
+aiohttp==3.14.3
 protobuf>=4.25.8
+aiosqlite>=0.20.0
 
 [kafka]
 aiokafka==0.10.0