{"id":8820,"library":"alembic-autogenerate-enums","title":"Alembic Autogenerate Enums","description":"alembic-autogenerate-enums is a Python library that provides an Alembic hook to automatically handle the upgrading and downgrading of enum values in database migrations. It simplifies managing changes to SQLAlchemy `Enum` types, particularly when adding, removing, or reordering enum members. The current version is 0.1.2, and it appears to have a low but steady release cadence, focusing on stability and compatibility with older SQLAlchemy versions.","status":"active","version":"0.1.2","language":"en","source_language":"en","source_url":"https://github.com/dskkato/alembic-autogenerate-enums","tags":["alembic","sqlalchemy","enums","migrations","autogenerate","database"],"install":[{"cmd":"pip install alembic-autogenerate-enums","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core dependency for Alembic migration functionality. Requires >=1.4.0.","package":"alembic","optional":false},{"reason":"Core dependency for database ORM and enum types. Requires >=1.3.0,<2.0.0.","package":"SQLAlchemy","optional":false}],"imports":[{"note":"Use this class as the SQLAlchemy type in your models for enums you want to be autogenerated.","symbol":"ColumnEnum","correct":"from alembic_autogenerate_enums import ColumnEnum"},{"note":"Use this function in your alembic/env.py to get the autogenerate hook.","symbol":"create_api","correct":"from alembic_autogenerate_enums import create_api"}],"quickstart":{"code":"from alembic import context\nfrom alembic_autogenerate_enums import create_api\nfrom sqlalchemy import create_engine, MetaData\n\n# Assuming these are defined elsewhere in your env.py\n# target_metadata = Base.metadata or some other SQLAlchemy MetaData object\n# config = context.config # Alembic configuration object\n\n# Placeholder for database connection and target_metadata\nDATABASE_URL = os.environ.get('DATABASE_URL', 'sqlite:///:memory:')\nconnectable = create_engine(DATABASE_URL)\ntarget_metadata = MetaData() # Replace with your actual target_metadata\n\n# --- The key integration part in env.py ---\n\n# 1. Create the API instance\napi = create_api()\n\n# 2. Integrate the API into context.configure\ndef run_migrations_online():\n    with connectable.connect() as connection:\n        context.configure(\n            connection=connection,\n            target_metadata=target_metadata,\n            api=api, # Pass the API instance here!\n            # include_object=include_object, # Optional, if you have one\n            # process_revision_directives=process_revision_directives # Optional, if you have one\n        )\n\n        with context.begin_transaction():\n            context.run_migrations()\n\n# Call the function if running online\n# if context.is_offline_mode():\n#     run_migrations_offline()\n# else:\n#     run_migrations_online()\n\n# Example model using ColumnEnum\nimport enum\nfrom sqlalchemy.orm import declarative_base, Mapped, mapped_column\nfrom sqlalchemy import String\n\nBase = declarative_base()\n\nclass UserStatus(enum.Enum):\n    ACTIVE = 'active'\n    INACTIVE = 'inactive'\n    PENDING = 'pending'\n\nclass User(Base):\n    __tablename__ = 'users'\n    id: Mapped[int] = mapped_column(primary_key=True)\n    status: Mapped[UserStatus] = mapped_column(ColumnEnum(UserStatus, values_callable=lambda x: [m.value for m in x]))\n\nprint(\"Alembic Autogenerate Enums setup snippet ready for integration into env.py.\")","lang":"python","description":"To enable automatic enum migration, you need to integrate `create_api()` into your `alembic/env.py` file by passing the `api` instance to `context.configure()`. Additionally, ensure that your SQLAlchemy `Enum` columns in your models use `alembic_autogenerate_enums.ColumnEnum` for the library to track changes effectively. The `values_callable` argument is crucial for `ColumnEnum` to correctly extract enum values."},"warnings":[{"fix":"Ensure your `env.py` has `api = create_api()` and then `context.configure(..., api=api, ...)`.","message":"The autogenerate hook will not function unless `api=api` is explicitly passed to `alembic.context.configure()` in your `env.py` file. Forgetting this step is a common setup error.","severity":"gotcha","affected_versions":"0.1.x"},{"fix":"Replace `SQLAlchemy.Enum` with `alembic_autogenerate_enums.ColumnEnum` in your models for enums you want to manage automatically.","message":"The specific enum value detection and migration capabilities are tied to using the library's `ColumnEnum` type in your SQLAlchemy models. Standard `SQLAlchemy.Enum` types might not be fully supported by the autogeneration hook for value changes.","severity":"gotcha","affected_versions":"0.1.x"},{"fix":"Review the order of operations and ensure the `api` hook's `process_revision_directives` method is applied either before or after your custom directives as appropriate, or integrated by wrapping the existing `process_revision_directives` with the `api.process_revision_directives`.","message":"If you have existing custom logic in `process_revision_directives` within `env.py`, ensure the `alembic-autogenerate-enums` API is called correctly and doesn't interfere with or override your custom processing.","severity":"gotcha","affected_versions":"0.1.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your `env.py` has `api = create_api()` and then `context.configure(..., api=api, ...)`.","cause":"The `api` argument was not correctly passed to `context.configure` in `env.py`, or a typo exists.","error":"AttributeError: 'EnvironmentContext' object has no attribute 'api'"},{"fix":"Verify that your SQLAlchemy `Enum` columns are defined using `alembic_autogenerate_enums.ColumnEnum` (with a `values_callable`) and that the `api` hook is correctly configured in `env.py` by passing `api=api` to `context.configure`.","cause":"The library's `ColumnEnum` type is not being used in the model definition, or the `api` hook is not correctly integrated into `env.py`.","error":"Alembic `autogenerate` command does not detect enum value changes, even after setting up the library."},{"fix":"Ensure your `ColumnEnum` definition includes `values_callable=lambda x: [m.value for m in x]` (or a similar function that returns a list of string values) to correctly extract the enum members.","cause":"This error often occurs when `ColumnEnum` is not provided with a `values_callable` or if the `values_callable` itself is incorrectly defined, preventing the enum values from being properly iterated or compared.","error":"TypeError: 'UserStatus' object is not iterable"}]}