Enhancement: Built-in PostgreSQL Enum Migration Support using alembic-postgresql-enum

[EssaAlshammri]

Summary

First, I want to express my sincere appreciation for Litestar and all the incredible work the maintainers and contributors have put into this project. The framework has been a joy to work with.

Problem Description

When using PostgreSQL as a database with SQLAlchemy models that contain enum columns, the migration system doesn't automatically detect changes to Python enum definitions.

Current Behavior:

• Initial migration generation works perfectly with litestar database make-migrations
• Adding new enum values to existing Python enums is not detected by subsequent migration runs
• Migrations are silently skipped, leaving the database schema out of sync

Example Scenario:

Initial model definition:

class UserType(StrEnum):
    ADMIN = "admin"
    PRINCIPAL = "principal"
    DEPUTY = "deputy"
    DIRECTOR = "director"
    TEACHER = "teacher"

class User(base.BigIntAuditBase):
    __tablename__ = "user"
    
    external_id: Mapped[str] = mapped_column(unique=True, index=True)
    user_type: Mapped[UserType] = mapped_column(
        nullable=False, index=True, default=UserType.TEACHER
    )

After adding a new enum value:

class UserType(StrEnum):
    ADMIN = "admin"
    PRINCIPAL = "principal"
    DEPUTY = "deputy"
    DIRECTOR = "director"
    TEACHER = "teacher"
    STUDENT = "student"  # New enum value

Running litestar database make-migrations after this change produces no migration file.

Current Workaround

The issue can be resolved by installing the alembic-postgresql-enum package and adding import alembic_postgresql_enum to the Alembic env.py file. This enables proper PostgreSQL enum change detection.

Basic Example

No response

Drawbacks and Impact

No response

Unresolved questions

No response