quadkit-sql

SQL database abstractions for Quadkit Framework — Postgres, MySQL, SQLite with migrations, repositories, and query building.

Overview

quadkit-sql provides an async SQLAlchemy ORM layer with the repository pattern, unit-of-work, connection pooling, multi-database support, Alembic migrations, and optional HMAC audit checksums. All database operations are wired through DatabaseProviderProtocol in the DI container.

Full documentation: docs.quadkit.dev

Install

uv add quadkit quadkit-sql

# With async PostgreSQL driver
uv add "quadkit-sql[postgres]"

# With async MySQL driver
uv add "quadkit-sql[mysql]"

# With SQLite async driver
uv add "quadkit-sql[sqlite]"

Quick Start

from quadkit import Application, StandardModule
from quadkit.di.module import Module, module
from quadkit.sql import DatabaseModule
from quadkit.sql.config import DatabaseConfig


@module(
    imports=[
        DatabaseModule.configure(
            DatabaseConfig(url="postgresql+asyncpg://user:pass@localhost/mydb")
        )
    ]
)
class AppModule(Module):
    pass


async def main() -> None:
    async with Application.boot(modules=[AppModule]) as app:
        from quadkit.contracts.data.sql.database import DatabaseProviderProtocol

        db = await app.container.resolve(DatabaseProviderProtocol)
        result = await db.execute_query("SELECT 1")


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

Configuration

Zero-config usage: Call DatabaseModule.configure() with no arguments to use all defaults (SQLite).

Option 1 — YAML file

# application.yaml
sql:
  backend:
    url: "${QK_SQL__BACKEND__URL}"
  pool:
    min_size: 2
    max_size: 10
    timeout: 30
  operations:
    echo: false

Option 2 — Profiles + Environment Variables (recommended)

export QK_SQL__BACKEND__URL=postgresql+asyncpg://user:pass@host/db
export QK_SQL__POOL__MAX_SIZE=20
export QK_SQL__POOL__TIMEOUT=60

Option 3 — Python

from quadkit.sql import DatabaseModule
from quadkit.sql.config import DatabaseConfig

DatabaseModule.configure(
    DatabaseConfig(
        url="postgresql+asyncpg://user:pass@localhost/mydb",
    )
)

Config reference

Module Factory Methods

Key Features

• Repository pattern — SQLRepository base class with find, create, update, delete, count
• Unit of work — AbstractUnitOfWork tracks changes and publishes domain events on commit
• Multi-database — NamedDatabaseConfig for multiple backends resolved via Annotated[DatabaseProviderProtocol, Named("analytics")]
• Connection pooling — SQLAlchemy async pool with configurable min/max size
• Alembic migrations — optional, run on boot only when enable_migrations=True (off by default)
• HMAC audit checksums — optional signing of write operations for integrity verification
• Production security — blocks default passwords (:password@, :postgres@, etc.) when QK_ENV=production

Testing

from quadkit import Application
from quadkit.sql import DatabaseModule
from quadkit.sql.config import DatabaseConfig


async def test_repository():
    async with Application.boot(
        modules=[
            DatabaseModule.stub(DatabaseConfig(url="sqlite+aiosqlite:///:memory:"))
        ]
    ) as app:
        db = await app.container.resolve(DatabaseProviderProtocol)
        # run your test queries

Key Source Files