nyxa-db — batteries-included database layer for Nyxa

SQLAlchemy 2.0 models, sessions, Alembic migrations, and seeders for apps built with nyxa. Core nyxa does not depend on this package.

Recommended stack

Swap later by changing DATABASE_URL only — models, migrations, and get_session stay the same. Install nyxa-postgres for tuned pool settings and docker compose scaffolding (init --database postgres). Alternate adapters (e.g. SQLModel) are out of scope for Phase 2; apps import from nyxa_db so a future adapter package can replace the binding without rewriting controllers.

Scaffold a new app with DB wiring:

uv run nyxa init myapi --database sqlite   # or postgres | none

Install

uv add nyxa-db

Models & sessions

from typing import Annotated

from fastapi import Depends
from sqlalchemy.orm import Session

from nyxa_db import Field, Model, get_session


class User(Model):
    id: int
    name: str
    email: str = Field(unique=True)


def list_users(session: Annotated[Session, Depends(get_session)]) -> list[User]:
    _ = session  # binds request session for Model helpers
    return User.all()

Slim annotations compile to SQLAlchemy columns. Use Field(...) for unique / FK / defaults. Explicit Mapped / mapped_column still works. Model API helpers: all / find / where / create / save / paginate (requires bound session).

Relationships: HasOne / HasMany / BelongsTo / BelongsToMany, plus User.with_("notes").get() for selectinload. Docs: docs/database/relationships.mdx.

Default URL: DATABASE_URL, or SQLite at {project}/database/app.db.

CLI

uv run nyxa make:migration create_posts_table  # Schema Builder stub
uv run nyxa make:model User -m                 # model + Schema Builder migration
uv run nyxa make:model User -m --autogenerate  # model + Alembic autogenerate
uv run nyxa make:model Post -f                 # model + factory
uv run nyxa make:factory User                  # database/factories/user_factory.py
uv run nyxa make:seeder User                   # database/seeders/user_seeder.py
uv run nyxa db migrate                         # upgrade head
uv run nyxa db rollback                        # downgrade -1
uv run nyxa db status                          # URL, connection, revision
uv run nyxa db seed                            # run all seeders

First migrate / make:migration scaffolds database/migrations/ and alembic.ini when missing.

Schema Builder

Hand-written migrations (recommended) use a fluent Schema Builder / Blueprint API (compiles to Alembic). The migration owns the schema; models define the Python mapping.

from nyxa_db.schema import Schema

def upgrade() -> None:
    with Schema.create("posts") as table:
        table.increments("id")
        table.string("title")
        table.timestamps()

def downgrade() -> None:
    Schema.drop("posts")

Raw Alembic revisions and Schema Builder revisions coexist under database/migrations/versions/. Put models under src/{app}/models/ (needed for --autogenerate).

Factories

from database.factories.user_factory import UserFactory

user = UserFactory.make(email="a@example.com")       # unsaved
user = UserFactory.create(session, name="Ada")       # add + flush
users = UserFactory.create_many(session, 3)          # batch

database/factories/
  user_factory.py    # class UserFactory(Factory[User])

Subclass nyxa_db.Factory, set model, and implement definition().

Seeders

database/seeders/
  user_seeder.py    # def run(session) or async def run(session)

Each module exposing run(session) is imported and executed with a short-lived session (committed on success). Example playground seeder inserts one sample user.