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