dbwarden-fastapi 0.1.0

FastAPI runtime hooks for DBWarden.

dbwarden-fastapi

FastAPI runtime integration for DBWarden.

dbwarden-fastapi is an official DBWarden plugin. It is discovered automatically through its dbwarden.plugins entry point and loaded without a consent prompt once installed.

What It Provides

Value hooks that back DBWarden's FastAPI helpers:

• session_factory, sync_session_factory: async and sync SQLAlchemy session dependencies.
• clickhouse_session_factory, clickhouse_sync_session_factory: async and sync ClickHouse client dependencies.
• lifespan: an application lifespan that runs migrations or schema checks on startup and disposes engines on shutdown.
• health_routes: liveness, readiness, and per-database health endpoints.
• migration_routes: status and migrate endpoints for operational control.

Each hook imports FastAPI and DBWarden internals lazily inside its own body, so installing the package pulls in nothing heavy and importing it has no side effects.

Install

dbwarden plugin add dbwarden-fastapi

plugin add verifies the package provenance (a PyPI PEP 740 attestation from the official repository) before installing. You can also install it directly with your package manager:

uv add dbwarden-fastapi
# or
pip install dbwarden-fastapi

FastAPI itself is expected to be a dependency of your application; install it alongside this plugin.

Use

DBWarden loads the plugin automatically. Confirm it is present:

dbwarden plugin list

Then wire the FastAPI helpers into your app. They resolve through this plugin when it is installed and fall back to core defaults when it is not:

from fastapi import Depends, FastAPI
from sqlalchemy.ext.asyncio import AsyncSession

from dbwarden.extensions.fastapi import (
    DBWardenHealthRouter,
    DBWardenRouter,
    dbwarden_lifespan,
    get_session,
)

app = FastAPI(lifespan=lambda app: dbwarden_lifespan(mode="check"))
app.include_router(DBWardenHealthRouter(), prefix="/health")
app.include_router(DBWardenRouter(), prefix="/dbwarden")


@app.get("/users")
async def users(session: AsyncSession = Depends(get_session("primary"))):
    ...

Development

pip install -e . pytest
pytest -q

The test suite is the DBWarden conformance suite plus plugin-specific checks. See the DBWarden plugin docs.

License

MIT