fix-alembic-async-env-py

Modify alembic/env.py to replace async SQLAlchemy operations with sync versions.

Updated May 15, 2026
One-click install
npx skills add https://github.com/ruskibeats/t1d --skill fix-alembic-async-env-py
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: fix-alembic-async-env-py
Source: https://github.com/ruskibeats/t1d/tree/main/.pi/skills-archive/fix-alembic-async-env-py
Command: npx skills add https://github.com/ruskibeats/t1d --skill fix-alembic-async-env-py

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill resolves issues related to Alembic migrations failing with async SQLAlchemy drivers, specifically dealing with greenlet errors and crashes.

Core Features & Use Cases

  • Alembic Migration Fix: Provides steps to modify alembic/env.py for async SQLAlchemy projects to ensure compatibility with Alembic migrations.
  • Async Driver Suffix Strip: Removes async driver suffixes like +asyncpg and +aiosqlite from database URLs to prevent common Alembic failures.
  • Sync Engine Usage: Recommends using sync engines for DDL operations during migrations to avoid errors related to async environments.

Quick Start

Apply the 'fix-alembic-async-env-py' Skill to update your Alembic configuration for proper async support.

Frequently Asked Questions about fix-alembic-async-env-py

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does Alembic migration fail with greenlet errors when using async SQLAlchemy drivers?

Alembic migrations fail with greenlet errors because the async SQLAlchemy driver environment conflicts with Alembic's synchronous migration execution. Resolving this requires stripping async suffixes from database URLs and replacing async operations with sync versions.

How do I fix the alembic env.py file for async SQLAlchemy projects?

To fix the alembic env.py file for async SQLAlchemy projects, you must modify the configuration by removing async driver suffixes like +asyncpg and +aiosqlite from database URLs and use sync engines for DDL operations during migrations.

Should I use sync or async engines for Alembic database migrations?

You should use sync engines for DDL operations during Alembic migrations to avoid errors related to async environments. This involves replacing async operations with sync versions in your alembic env.py configuration.

How do I strip async driver suffixes from SQLAlchemy database URLs for Alembic?

To strip async driver suffixes from SQLAlchemy database URLs for Alembic, remove the +asyncpg and +aiosqlite suffixes from your connection strings. This prevents common Alembic failures and stabilizes the migration setup.

Can I run Alembic migrations with asyncpg without encountering crashes?

You can run Alembic migrations with asyncpg without crashes by stripping the +asyncpg suffix from the database URL and using a sync engine for DDL operations. This approach ensures compatibility and prevents greenlet errors.

What are the limitations of using sync engines for Alembic migrations in async SQLAlchemy projects?

Using sync engines for Alembic migrations in async SQLAlchemy projects limits DDL operations to synchronous execution. While this prevents greenlet errors, the application runtime still requires async drivers for concurrent database operations.