Getting Started
Execution Workflow
- Confirm prerequisites: Python 3.9+, SQLAlchemy 2.x, and whether the project needs sync or async database access.
- Install
advanced-alchemy, or advanced-alchemy[cli] if database migration commands are required.
- Choose the correct config pair:
SQLAlchemyAsyncConfig plus AsyncSessionConfig or SQLAlchemySyncConfig plus SyncSessionConfig.
- Start with one model, one repository, and one service before wiring framework-specific plugins or middleware.
- Decide early whether the app will use Litestar, FastAPI, Flask, or standalone SQLAlchemy patterns.
Implementation Rules
- Prefer the smallest viable setup before adding service layers, framework helpers, or multiple binds.
- Keep session configuration explicit, especially
expire_on_commit=False in request-driven applications.
- Choose sync versus async once per integration boundary and avoid mixing styles casually.
- Keep the first CRUD path runnable end-to-end before introducing migrations, seeding, or custom types.
Example Pattern
from advanced_alchemy.config import AsyncSessionConfig, SQLAlchemyAsyncConfig
alchemy_config = SQLAlchemyAsyncConfig(
connection_string="sqlite+aiosqlite:///app.db",
session_config=AsyncSessionConfig(expire_on_commit=False),
create_all=True,
)
Validation Checklist
- Confirm the selected config class matches the driver and execution style.
- Confirm metadata creation or migrations can see the same models as runtime code.
- Confirm a repository or service can open a session and perform one basic read or write.
- Confirm framework integration is deferred until the underlying SQLAlchemy setup works.
Cross-Skill Handoffs
- Use
advanced-alchemy-modeling for base classes, mixins, and relationships.
- Use
advanced-alchemy-repositories and advanced-alchemy-services once CRUD is working.
- Use
advanced-alchemy-litestar, advanced-alchemy-fastapi, or advanced-alchemy-flask for framework wiring.
- Use
advanced-alchemy-cli and advanced-alchemy-database-seeding after the base setup is stable.
Advanced Alchemy References
