sqlalchemy-models

Skill: sqlalchemy-models

Core position

This skill creates clean, production-ready SQLAlchemy 2.x ORM models for Python backend projects.

It enforces disciplined model patterns that prevent common problems such as:

• inconsistent base/model definitions
• broken or asymmetric relationships
• circular imports
• weak typing
• migration-hostile schema definitions
• persistence and API schema concerns getting mixed together

The skill favors explicit, typed, migration-friendly ORM design and ensures model code is:

• SQLAlchemy 2.x native
• typed
• composable
• easy to migrate
• easy to review

---

Goals

Produce a model layer that:

1. Uses SQLAlchemy 2.x canonical style
2. Centralizes model infrastructure around a single DeclarativeBase
3. Defines columns and relationships with explicit typing
4. Organizes models in a predictable package structure
5. Avoids circular import traps
6. Stays compatible with Alembic autogenerate
7. Keeps ORM models separate from Pydantic/API schemas

---

Step 0 — Inspect the existing project first

Before generating anything:

1. Check whether a models/ package or existing model files already exist. If they do, extend the existing structure rather than creating a parallel one.
2. Note the existing package layout. If the project was scaffolded with fastapi-init, the package root is {pkg_name}/{pkg_name}/ — place models at {pkg_name}/models/, not app/models/.
3. Check whether a DeclarativeBase subclass already exists anywhere. If one does, adopt it rather than introducing a second base.
4. Check whether an Alembic env.py is present and how it imports Base.metadata — preserve that import path.
5. Only create new files if the relevant structure is absent.

---