SQLAlchemy

The SQLAlchemy adapter is the production relational adapter for Kernia. It uses SQLAlchemy Core against an async engine and materializes the resolved Kernia schema from core models plus plugin-contributed models.

Installation

uv add kernia kernia-sqlalchemy sqlalchemy alembic asyncpg

Use aiosqlite, asyncmy, or the relevant async driver for your database.

Server configuration

import os
from sqlalchemy.ext.asyncio import create_async_engine

from kernia import KerniaOptions
from kernia.auth import init
from kernia_sqlalchemy import sqlalchemy_adapter

engine = create_async_engine(os.environ["DATABASE_URL"], pool_pre_ping=True)
adapter = sqlalchemy_adapter(engine)

auth = init(KerniaOptions(
    database=adapter,
    secret=os.environ["KERNIA_SECRET"],
    base_url=os.environ["KERNIA_BASE_URL"],
))

Schema generation

The adapter maps Kernia logical field types to SQLAlchemy column types: strings to String(255), text to Text, dates to integer Unix seconds, JSON/list values to JSON, and booleans to Boolean.

uv run kernia generate --app app.auth:auth --output alembic/versions/0001_kernia.py
alembic upgrade head

Transactions

The adapter supports transaction contexts. Plugin flows that need atomic writes can use the adapter transaction protocol when available.

When to use it

Use SQLAlchemy for PostgreSQL, MySQL, SQLite, MSSQL, and other SQL databases supported by SQLAlchemy's async dialects. For simple tests, use the memory adapter instead.

Troubleshooting

If async operations hang, confirm you used an async driver URL such as postgresql+asyncpg://. If migrations miss plugin tables, generate from the same auth object that your server mounts.