{"id":3328,"library":"alembic-postgresql-enum","title":"Alembic PostgreSQL Enum","description":"alembic-postgresql-enum provides autogenerate support for the creation, alteration, and deletion of PostgreSQL enums within Alembic migration scripts. It addresses limitations where Alembic's default autogenerate often fails to detect and generate migrations for enum value changes (like deletions or reordering). The library is actively maintained, with the latest version 1.10.0 released in February 2026.","status":"active","version":"1.10.0","language":"en","source_language":"en","source_url":"https://github.com/harmonicai/alembic-postgresql-enum","tags":["alembic","postgresql","enum","migrations","sqlalchemy","autogenerate"],"install":[{"cmd":"pip install alembic-postgresql-enum","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core migration framework that this library extends.","package":"alembic","optional":false},{"reason":"ORM used to define database models and enum types.","package":"SQLAlchemy","optional":false},{"reason":"PostgreSQL adapter for SQLAlchemy.","package":"psycopg2-binary","optional":true}],"imports":[{"note":"Import at the top of migrations/env.py to enable autogeneration features.","symbol":"alembic_postgresql_enum","correct":"import alembic_postgresql_enum"},{"note":"Used for manual enum migrations within migration scripts, although autogeneration usually handles this.","symbol":"EnumMigration","correct":"from alembic_postgresql_enum import EnumMigration"},{"note":"Used in conjunction with EnumMigration to specify affected columns for manual migrations.","symbol":"Column","correct":"from alembic_postgresql_enum import Column"}],"quickstart":{"code":"import os\nimport enum\nfrom sqlalchemy import Column, Integer\nfrom sqlalchemy.dialects import postgresql\nfrom sqlalchemy.orm import declarative_base\n\n# This is a simplified example. In a real Alembic setup,\n# you would define your models and then run 'alembic revision --autogenerate'\n# after importing alembic_postgresql_enum in env.py\n\nBase = declarative_base()\n\nclass ResourceState(enum.Enum):\n    ACTIVE = 'active'\n    INACTIVE = 'inactive'\n    ARCHIVED = 'archived'\n\nclass Resource(Base):\n    __tablename__ = 'resources'\n    id = Column(Integer, primary_key=True)\n    state = Column(postgresql.ENUM(ResourceState, name='resource_state'), nullable=False)\n\n# To simulate a change for autogeneration (e.g., adding a new enum value):\n# 1. Initially define ResourceState with just ACTIVE and INACTIVE.\n# 2. Run alembic revision --autogenerate. A migration will be created for the initial enum.\n# 3. Add 'ARCHIVED' to ResourceState (as shown above).\n# 4. Ensure 'import alembic_postgresql_enum' is at the top of your migrations/env.py.\n# 5. Run alembic revision --autogenerate again.\n#    The library should now generate an 'op.sync_enum_values' call to add 'ARCHIVED'.\n\nprint(\"Alembic-PostgreSQL-Enum quickstart concept: Define your SQLAlchemy models with PostgreSQL ENUMs.\")\nprint(\"Ensure 'import alembic_postgresql_enum' is added to your migrations/env.py.\")\nprint(\"Modify your enum definition (add, remove, rename values), then run 'alembic revision --autogenerate'.\")\nprint(\"The library will generate the necessary SQL for enum synchronization.\")","lang":"python","description":"This example demonstrates how to define a SQLAlchemy model with a PostgreSQL ENUM. The core functionality of `alembic-postgresql-enum` is activated by importing the library at the top of your `migrations/env.py` file. After doing so, any changes to your Python enum definitions (like adding, removing, or renaming values) will be automatically detected by `alembic revision --autogenerate`, generating the appropriate `op.sync_enum_values` calls to synchronize the database enum type."},"warnings":[{"fix":"Add `import alembic_postgresql_enum` to `migrations/env.py`.","message":"For `alembic-postgresql-enum` to automatically detect enum changes and generate migrations, you *must* include `import alembic_postgresql_enum` at the very top of your `migrations/env.py` file.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rely on the library's autogenerated migrations. If writing manual SQL for complex enum changes, consider using `with op.get_context().begin_transaction():` and subsequent commits if required by PostgreSQL, or temporarily convert columns to `TEXT` type during migration if non-transactional enum changes are problematic.","message":"When modifying enum values (especially deleting or renaming), be aware that PostgreSQL's `ALTER TYPE` statements for enums have specific transactional limitations. Historically, `ALTER TYPE ... ADD VALUE` cannot be used until the transaction is committed, which can lead to issues if not handled correctly. `alembic-postgresql-enum` attempts to manage this, but manual SQL operations might still encounter it.","severity":"gotcha","affected_versions":"All versions (due to PostgreSQL behavior)"},{"fix":"Set `detect_enum_values_changes=False` or `ignore_enum_values_order=True` in your `env.py` if value order changes should not trigger a migration.","message":"By default, the order of enum values matters in PostgreSQL. If `alembic-postgresql-enum` detects a reordering of values, it will generate a migration. If you wish to ignore changes in enum value order, you can set the `ignore_enum_values_order` flag to `True` in your configuration.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all enum definitions and migration helpers (including the library itself) explicitly qualify schema for ENUM types. Review generated SQL for `CREATE TYPE` statements.","message":"PostgreSQL ENUM types created via raw SQL statements (`op.execute(\"CREATE TYPE ...\")`) without explicit schema qualification can end up in the `public` schema, even if tables and other objects respect a configured schema. While `alembic-postgresql-enum` aims to manage enums properly, ensure your setup (especially if mixing with raw SQL) correctly applies schema to enums.","severity":"gotcha","affected_versions":"Potentially older versions or specific configurations when not relying solely on autogeneration."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}