alchemiq

The data layer for async FastAPI microservices: Django-style models, transactional outbox, caching, and ClickHouse - built on SQLAlchemy 2.0.

30-second example

import alchemiq
from alchemiq import Model, Repository
from alchemiq.types import PK, Email

class User(Model):
    id: PK[int]
    name: str
    email: Email

alchemiq.configure("postgresql+asyncpg://user:password@localhost/mydb")
await alchemiq.create_all()

users = Repository(User)
user  = await users.create(name="Ada Lovelace", email="ada@example.com")
found = await users.get(id=user.id)
print(found.name)  # Ada Lovelace

Features

• Async PostgreSQL and ClickHouse - a single query DSL covers both backends.
• Django-flavoured models - declare fields with plain type annotations; Q objects, QuerySet chaining, order_by, limit, and offset work exactly as you would expect.
• Repository + UnitOfWork - full CRUD, bulk operations, cursor/keyset pagination, and aggregations (Count, Sum, Avg, Min, Max) out of the box.
• Soft-delete and optimistic locking - opt in per model via a Meta class.
• Signals - async pre/post hooks for create, update, and delete lifecycle events.
• Serialization - to_dict, to_schema, to_pydantic with field inclusion/exclusion.
• Outbox + Relay - atomic event capture in the same transaction, published to any broker (RabbitMQ, Kafka, NATS) via TaskIQ or FastStream.
• FastAPI integration - auto-generated CRUD router, DI-ready repository and UoW providers, Pydantic schema generation, and a /health/ready · /health/live router.
• FastStream consumer DI - inject sessions, UoW, and repositories into message handlers.
• Redis caching - per-repository cache with automatic invalidation on write.
• Migrations - Alembic wrapper for PostgreSQL; a custom engine for ClickHouse.
• Scaffolding - alchemiq init generates a production-ready layered project skeleton.
• SQLite dev/test tier - run your app's tests without Docker; PostgreSQL stays the production target.

Installation

pip install "alchemiq[all]"

Documentation

Full guide and API reference: https://alchemiq.readthedocs.io

Links

• Source: https://github.com/TrifoN-off/alchemiq
• Changelog: CHANGELOG.md
• License: MIT - see LICENSE

What's not in v1

alchemiq v1 does not include a visual admin, MySQL support, synchronous mode, multi-database routing, audit logs, geolocation fields, or file-field storage adapters. SQLite is supported as a dev/test tier - see the SQLite guide.

See the What's not in v1 guide for the full list and the reasoning behind each deferral.