Alembic PostgreSQL Enum

Warnings

• gotcha 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.
  Fix: Add `import alembic_postgresql_enum` to `migrations/env.py`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install alembic-postgresql-enum Install stable version

Imports

• 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.

Quickstart

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.")