{"id":158,"library":"alembic","title":"Alembic","description":"Database migration tool for SQLAlchemy. Manages schema versioning via migration scripts. Current version: 1.18.4 (Mar 2026). Tightly coupled to SQLAlchemy — version mismatch causes silent failures. SQLAlchemy 1.3 dropped in Alembic 1.15. Python 3.8 dropped in Alembic 1.15. The #1 footgun: autogenerate generates empty migrations when target_metadata is not correctly set in env.py.","status":"active","version":"1.18.4","language":"python","source_language":"en","source_url":"https://github.com/sqlalchemy/alembic","tags":["alembic","sqlalchemy","migrations","database","python","schema"],"install":[{"cmd":"pip install alembic","lang":"bash","label":"Python"}],"dependencies":[{"reason":"Required. Alembic 1.15+ requires SQLAlchemy >= 1.4. SQLAlchemy 2.0 fully supported.","package":"sqlalchemy","optional":false},{"reason":"Required for migration script templates. Installed automatically.","package":"Mako","optional":false}],"imports":[{"note":"The single most common Alembic mistake. If target_metadata = None in env.py, autogenerate produces empty migration files. Must import your models and set target_metadata = Base.metadata.","wrong":"# In alembic/env.py\ntarget_metadata = None  # default — autogenerate generates EMPTY migrations","symbol":"env.py target_metadata","correct":"# In alembic/env.py — MUST import your models for autogenerate to work\nfrom myapp.models import Base  # import all models so metadata is populated\ntarget_metadata = Base.metadata\n\n# If models are in multiple files, import them all:\nfrom myapp.models.user import User\nfrom myapp.models.post import Post\n# then:\ntarget_metadata = Base.metadata"},{"note":"Must run 'alembic upgrade head' before running --autogenerate again. Error: 'Target database is not up to date' means DB is behind the migration chain.","wrong":"# Wrong: running autogenerate before DB is up to date\nalembic revision --autogenerate -m 'add column'  # fails if DB not at head","symbol":"alembic init + upgrade","correct":"# CLI commands — run from project root\nalembic init alembic          # create alembic directory\nalembic revision --autogenerate -m 'initial'  # generate migration\nalembic upgrade head           # apply all pending migrations\nalembic downgrade -1           # roll back one migration\nalembic history                # show migration history\nalembic current                # show current DB version"}],"quickstart":{"code":"# 1. Install and init\n# pip install alembic sqlalchemy\n# alembic init alembic\n\n# 2. Edit alembic/env.py — add your models:\n# from myapp.models import Base\n# target_metadata = Base.metadata\n\n# 3. Edit alembic.ini — set database URL:\n# sqlalchemy.url = postgresql://user:pass@localhost/mydb\n\n# 4. Generate first migration\n# alembic revision --autogenerate -m 'initial schema'\n\n# 5. Apply migration\n# alembic upgrade head\n\n# Migration file (alembic/versions/xxx_initial_schema.py):\nfrom alembic import op\nimport sqlalchemy as sa\n\ndef upgrade():\n    op.create_table(\n        'users',\n        sa.Column('id', sa.Integer, primary_key=True),\n        sa.Column('username', sa.String(50), nullable=False),\n        sa.Column('email', sa.String(120), nullable=False),\n    )\n\ndef downgrade():\n    op.drop_table('users')","lang":"python","description":"Alembic setup and first migration workflow."},"warnings":[{"fix":"In env.py: import your models then set target_metadata = Base.metadata","message":"target_metadata = None in env.py causes autogenerate to produce completely empty migration files. This is the default after 'alembic init'. Must be changed to Base.metadata.","severity":"breaking","affected_versions":"all"},{"fix":"Run 'alembic upgrade head' first, then run --autogenerate.","message":"'Target database is not up to date' error when running --autogenerate. DB must be at head before generating new migrations.","severity":"breaking","affected_versions":"all"},{"fix":"Use SQLAlchemy >= 1.4 and Python >= 3.9 with Alembic 1.15+","message":"SQLAlchemy 1.3 support dropped in Alembic 1.15. Python 3.8 support dropped in Alembic 1.15.","severity":"breaking","affected_versions":">= 1.15"},{"fix":"Always run 'alembic check' and manually review generated migration files before applying.","message":"Autogenerate cannot detect everything. It misses: stored procedures, views, partial indexes (pre-1.12), CHECK constraints, column defaults (in some cases). Always manually review generated migrations.","severity":"gotcha","affected_versions":"all"},{"fix":"Run 'alembic merge heads -m merge' to create a merge migration. Then 'alembic upgrade head'.","message":"Multiple heads error: 'Multiple head revisions are present' when two migrations both point to the same parent. Happens when multiple developers generate migrations from the same base.","severity":"gotcha","affected_versions":"all"},{"fix":"Import all model files in env.py before target_metadata = Base.metadata.","message":"Autogenerate generates 'create table' for all tables instead of 'add column' when models are not imported before autogenerate runs. Models must be imported in env.py so SQLAlchemy metadata is populated.","severity":"gotcha","affected_versions":"all"},{"fix":"In env.py: config.set_main_option('sqlalchemy.url', os.environ['DATABASE_URL'])","message":"alembic.ini sqlalchemy.url hardcodes the database URL. For production, override it in env.py using environment variables.","severity":"gotcha","affected_versions":"all"},{"fix":"Always use a virtual environment (e.g., `python -m venv .venv`) to install Python packages to avoid permission issues and system package manager conflicts. Avoid running pip commands with `sudo` unless absolutely necessary for system-wide tools, which is generally not recommended for application dependencies.","message":"Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead.","severity":"gotcha","affected_versions":"all"},{"fix":"It is recommended to use a virtual environment or run pip as a non-root user. If running as root is intentional, use the `--root-user-action` option to suppress this warning.","message":"Running pip as root can lead to broken permissions and conflicts with the system package manager, potentially rendering the system unusable.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'1':40 '1.15':32,38 '1.18.4':15 '1.3':28 '2026':17 '3.8':34 'alemb':1,31,37,55 'autogener':42 'caus':24 'correct':51 'coupl':19 'current':13 'databas':2,58 'drop':29,35 'empti':44 'env.py':54 'failur':26 'footgun':41 'generat':43 'manag':7 'mar':16 'metadata':48 'migrat':3,11,45,57 'mismatch':23 'python':33,59 'schema':8,60 'script':12 'set':52 'silent':25 'sqlalchemi':6,21,27,56 'target':47 'tight':18 'tool':4 'version':9,14,22 'via':10","created_at":"2026-03-24T18:37:56.803125+00:00","updated_at":"2026-04-15T19:52:13.711771+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":80,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"1.19.1","cli_name":"alembic","cli_version":"alembic 1.18.4","type":"library","homepage":"https://alembic.sqlalchemy.org","github":"https://github.com/sqlalchemy/alembic","docs":"https://alembic.sqlalchemy.org/en/latest/","changelog":"https://alembic.sqlalchemy.org/en/latest/changelog.html","pypi":"https://pypi.org/project/alembic/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-27","last_verified":"2026-08-26","next_check":"2026-07-04","install_tag":"verified"}}