Registry /
database / alembic-postgresql-enum
Install & Compatibility
Where this runs
tested against v1.10.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.164s · 46.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 1.062s · 45MB
45MB installed
● package 45MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
alembic_postgresql_enum
✓ import alembic_postgresql_enum
Import at the top of migrations/env.py to enable autogeneration features.
EnumMigration
✓ from alembic_postgresql_enum import EnumMigration
Used for manual enum migrations within migration scripts, although autogeneration usually handles this.
Column
✓ from alembic_postgresql_enum import Column
Used in conjunction with EnumMigration to specify affected columns for manual migrations.
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.
import os
import enum
from sqlalchemy import Column, Integer
from sqlalchemy.dialects import postgresql
from sqlalchemy.orm import declarative_base
# This is a simplified example. In a real Alembic setup,
# you would define your models and then run 'alembic revision --autogenerate'
# after importing alembic_postgresql_enum in env.py
Base = declarative_base()
class ResourceState(enum.Enum):
ACTIVE = 'active'
INACTIVE = 'inactive'
ARCHIVED = 'archived'
class Resource(Base):
__tablename__ = 'resources'
id = Column(Integer, primary_key=True)
state = Column(postgresql.ENUM(ResourceState, name='resource_state'), nullable=False)
# To simulate a change for autogeneration (e.g., adding a new enum value):
# 1. Initially define ResourceState with just ACTIVE and INACTIVE.
# 2. Run alembic revision --autogenerate. A migration will be created for the initial enum.
# 3. Add 'ARCHIVED' to ResourceState (as shown above).
# 4. Ensure 'import alembic_postgresql_enum' is at the top of your migrations/env.py.
# 5. Run alembic revision --autogenerate again.
# The library should now generate an 'op.sync_enum_values' call to add 'ARCHIVED'.
print("Alembic-PostgreSQL-Enum quickstart concept: Define your SQLAlchemy models with PostgreSQL ENUMs.")
print("Ensure 'import alembic_postgresql_enum' is added to your migrations/env.py.")
print("Modify your enum definition (add, remove, rename values), then run 'alembic revision --autogenerate'.")
print("The library will generate the necessary SQL for enum synchronization.")
Debug
Known issues
gotchaFor `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.fixAdd `import alembic_postgresql_enum` to `migrations/env.py`.
affects: All versions
gotchaWhen 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.fixRely 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.
affects: All versions (due to PostgreSQL behavior)
gotchaBy 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.fixSet `detect_enum_values_changes=False` or `ignore_enum_values_order=True` in your `env.py` if value order changes should not trigger a migration.
affects: All versions
gotchaPostgreSQL 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.fixEnsure all enum definitions and migration helpers (including the library itself) explicitly qualify schema for ENUM types. Review generated SQL for `CREATE TYPE` statements.
affects: Potentially older versions or specific configurations when not relying solely on autogeneration.
Errors
Common errors & fixes
sqlalchemy.exc.ProgrammingError: (psycopg2.errors.DatatypeMismatch) column "status" cannot be cast automatically to type statusenum
HINT: You might need to specify "USING status::statusenum".
This error occurs when altering an ENUM column without specifying how to cast existing values to the new ENUM type.
fixUse the 'postgresql_using' parameter in 'op.alter_column' to define the casting, e.g., 'op.alter_column('table_name', 'column_name', type_=new_enum_type, postgresql_using='column_name::text::new_enum_type')'. sqlalchemy.exc.CompileError: Postgresql ENUM type requires a name
This error occurs when defining a PostgreSQL ENUM type without specifying a 'name' parameter.
fixEnsure that the ENUM type is defined with a 'name', e.g., 'sa.Enum('value1', 'value2', name='enum_name')'. DuplicateObject: "myenum" already exists
This error occurs when attempting to create an ENUM type that already exists in the database.
fixUse the 'create_type=False' parameter when defining the ENUM to prevent re-creation, e.g., 'sa.Enum('A', 'B', 'C', name='myenum', create_type=False)'. sqlalchemy.exc.NotSupportedError: (psycopg2.errors.FeatureNotSupported) cannot alter type of a column used by a view or rule
DETAIL: rule _RETURN on view custom_table_view depends on column "custom_enum_type"
This error occurs when trying to alter an ENUM type that is used by a view, which PostgreSQL does not support directly.
fixDrop the dependent view before altering the ENUM type and recreate it afterward, ensuring to handle any dependencies appropriately.
alembic revision --autogenerate generates empty migration for enum changes
Alembic's default autogenerate feature does not inherently detect changes to PostgreSQL ENUM types (like adding, removing, or reordering values) in SQLAlchemy models, leading to empty migration files when enum definitions are altered.
fixInstall `alembic-postgresql-enum` (`pip install alembic-postgresql-enum`) and add `import alembic_postgresql_enum` to the top of your `env.py` file to enable detection of enum changes.
Upgrade
Version history
1.10.0latest on PyPI · released Feb 23, 2026
Audit
Dependencies
alembicrequiredCore migration framework that this library extends.
SQLAlchemyrequiredORM used to define database models and enum types.
psycopg2-binaryoptionalPostgreSQL adapter for SQLAlchemy.