DEV Community

Muhammad Atif Iqbal
Muhammad Atif Iqbal

Posted on

2 1 1 1 1

Cheat sheet of 'Alembic' commands

Here’s a complete cheat sheet of Alembic commands you'll use for managing database migrations in your project — especially useful since you’re using PostgreSQL + Alembic for version-controlled schema changes.


📦 Alembic Basics

🧱 1. Initialize Alembic

Run this once to set up Alembic in your project:

alembic init alembic
Enter fullscreen mode Exit fullscreen mode

🛠️ 2. Configure alembic.ini and env.py

  • In alembic.ini, set your database URL:
sqlalchemy.url = postgresql+asyncpg://user:pass@localhost/db
Enter fullscreen mode Exit fullscreen mode

⚠️ If you're using async SQLAlchemy, the URL above is fine, but you’ll need to tweak env.py. Let me know if you want the async-ready version of env.py.


🚀 Migration Commands

📌 3. Create a new migration script (autogenerate)

This compares your models and the DB, then generates a migration file:

alembic revision --autogenerate -m "create users table"
Enter fullscreen mode Exit fullscreen mode
  • You can also create an empty migration:
alembic revision -m "initial setup"
Enter fullscreen mode Exit fullscreen mode

🧱 4. Apply Migrations

Run migrations and apply changes to the database:

alembic upgrade head
Enter fullscreen mode Exit fullscreen mode

To upgrade to a specific revision:

alembic upgrade <revision_id>
Enter fullscreen mode Exit fullscreen mode

🔁 5. Downgrade Migrations

Revert last migration:

alembic downgrade -1
Enter fullscreen mode Exit fullscreen mode

To downgrade to a specific revision:

alembic downgrade <revision_id>
Enter fullscreen mode Exit fullscreen mode

🧾 6. View Current DB Revision

alembic current
Enter fullscreen mode Exit fullscreen mode

🕵️‍♂️ 7. Check History of Migrations

alembic history
Enter fullscreen mode Exit fullscreen mode

🔍 8. Show Detailed Info of a Migration

alembic show <revision_id>
Enter fullscreen mode Exit fullscreen mode

🔄 Bonus: Stamp DB without applying migrations

Useful if you want Alembic to think the DB is up-to-date without actually running the migration:

alembic stamp head
Enter fullscreen mode Exit fullscreen mode

⚙️ Common Structure Recap

Your alembic/ folder will contain:

alembic/
  versions/
    20240420_create_users_table.py
  env.py          # Main config (load metadata, engine)
alembic.ini       # Connection settings
Enter fullscreen mode Exit fullscreen mode

🔥 Pro Tip (for async users):

If you’re using asyncpg + async SQLAlchemy, you must modify env.py to support async migrations. Would you like a ready-to-use env.py file for async migrations?

AWS Q Developer image

Build your favorite retro game with Amazon Q Developer CLI in the Challenge & win a T-shirt!

Feeling nostalgic? Build Games Challenge is your chance to recreate your favorite retro arcade style game using Amazon Q Developer’s agentic coding experience in the command line interface, Q Developer CLI.

Participate Now

Top comments (0)

Build gen AI apps that run anywhere with MongoDB Atlas

Build gen AI apps that run anywhere with MongoDB Atlas

MongoDB Atlas bundles vector search and a flexible document model so developers can build, scale, and run gen AI apps without juggling multiple databases. From LLM to semantic search, Atlas streamlines AI architecture. Start free today.

Start Free

👋 Kindness is contagious

Discover fresh viewpoints in this insightful post, supported by our vibrant DEV Community. Every developer’s experience matters—add your thoughts and help us grow together.

A simple “thank you” can uplift the author and spark new discussions—leave yours below!

On DEV, knowledge-sharing connects us and drives innovation. Found this useful? A quick note of appreciation makes a real impact.

Okay