configure-alembic-async-ddl

Configuring Alembic migrations for async SQLAlchemy requires stripping the async driver suffix from the connection string for sync DDL compatibility, wiring target_metadata to your MetaData object, and using NullPool for migration connections.

Alembic fails with async FastAPI SQLAlchemy engines because DDL operations require synchronous connections. You must strip the async driver suffix from the connection string and create a sync engine specifically for executing migration operations.

Yes, psycopg2-binary is required for synchronous DDL execution. Alembic migrations need a sync database connection to apply schema changes, even when your primary application uses an async SQLAlchemy engine.

Wiring target_metadata in Alembic env.py involves pointing the variable to your actual SQLAlchemy MetaData object rather than a generic or empty one. This ensures Alembic's autogenerate feature detects the correct DDL changes for verification.

Yes, async SQLAlchemy setups support both offline and online Alembic migration modes. For online migrations, you create a sync engine using NullPool to execute DDL statements, while offline mode generates SQL scripts without a live database connection.

NullPool is used for migration connections in SQLAlchemy to prevent the connection pool from retaining database connections. This ensures clean, single-use connections for executing DDL operations during Alembic migrations without async engine conflicts.