feat(alembic): auto-enable PostgreSQL enum migration detection

Alembic autogenerate cannot detect changes to PostgreSQL native ENUM
types (e.g. adding a value to an existing StrEnum), silently skipping
those migrations. The generated env.py templates now import
alembic-postgresql-enum inside a guarded try/except, which registers the
required autogenerate comparators as an import side effect. This is a
no-op when the package is not installed.

Adds a public `postgresql` extra so users can install the dependency
with `pip install "advanced-alchemy[postgresql]"`, documents the
behavior in the CLI usage guide, and covers the template rendering with
a test.

Closes #492

Author: hasansezertasan

advanced_alchemy/alembic/templates/asyncio/env.py

@@ -8,6 +8,15 @@
 from advanced_alchemy.base import metadata_registry
 from alembic import context
 
+try:
+    # Enables autogenerate support for PostgreSQL ``ENUM`` changes (e.g. added values).
+    # Alembic cannot detect these on its own; importing this package registers the
+    # required autogenerate comparators as a side effect. Install with the
+    # ``advanced-alchemy[postgresql]`` extra to enable.
+    import alembic_postgresql_enum  # type: ignore[import-not-found,unused-ignore]  # pyright: ignore[reportMissingImports]  # noqa: F401
+except ImportError:
+    pass
+
 if TYPE_CHECKING:
     from sqlalchemy.engine import Connection
 

advanced_alchemy/alembic/templates/sync/env.py

@@ -6,6 +6,15 @@
 from advanced_alchemy.base import metadata_registry
 from alembic import context
 
+try:
+    # Enables autogenerate support for PostgreSQL ``ENUM`` changes (e.g. added values).
+    # Alembic cannot detect these on its own; importing this package registers the
+    # required autogenerate comparators as a side effect. Install with the
+    # ``advanced-alchemy[postgresql]`` extra to enable.
+    import alembic_postgresql_enum  # type: ignore[import-not-found,unused-ignore]  # pyright: ignore[reportMissingImports]  # noqa: F401
+except ImportError:
+    pass
+
 if TYPE_CHECKING:
     from sqlalchemy.engine import Connection
 

docs/usage/cli.rst

@@ -255,6 +255,24 @@ Create a new migration revision:
    * - ``--rev-id`` TEXT
      - Specific revision ID
 
+.. note:: **PostgreSQL enum changes**
+
+   Alembic's autogenerate does not detect changes to PostgreSQL native ``ENUM``
+   types on its own (for example, adding a value to an existing ``StrEnum``).
+   Advanced Alchemy's migration templates automatically enable this detection
+   when the optional `alembic-postgresql-enum
+   <https://pypi.org/project/alembic-postgresql-enum/>`_ package is installed.
+   Install it with the ``postgresql`` extra:
+
+   .. code-block:: bash
+
+       pip install "advanced-alchemy[postgresql]"
+
+   The generated ``env.py`` imports the package inside a ``try``/``except`` block,
+   so no configuration is required — it activates only when the package is present.
+   If you initialized your migrations with an older version of Advanced Alchemy,
+   add ``import alembic_postgresql_enum`` near the top of your ``env.py`` to enable it.
+
 
 Inspection Commands
 ~~~~~~~~~~~~~~~~~~~

pyproject.toml

@@ -66,6 +66,7 @@ fsspec = ["fsspec"]
 nanoid = ["fastnanoid>=0.4.1"]
 obstore = ["obstore"]
 passlib = ["passlib[argon2]"]
+postgresql = ["alembic-postgresql-enum"]
 pwdlib = ["pwdlib[argon2]"]
 pyotp = ["pyotp"]
 uuid = ["uuid-utils>=0.6.1"]
@@ -145,7 +146,7 @@ litestar = ["litestar[cli]>=2.23.0"]
 mssql = ["aioodbc>=0.5.0", "pyodbc>=5.2.0"]
 mysql = ["asyncmy>=0.2.9"]
 oracle = ["oracledb>=2.4.1"]
-postgres = ["asyncpg>=0.29.0", "psycopg2-binary>=2.9.10", "psycopg[binary,pool]>=3.2.3"]
+postgres = ["alembic-postgresql-enum", "asyncpg>=0.29.0", "psycopg2-binary>=2.9.10", "psycopg[binary,pool]>=3.2.3"]
 sanic = ["sanic", "sanic-testing>=24.6.0", "sanic[ext]>=24.6.0"]
 spanner = ["sqlalchemy-spanner>=1.7.0"]
 sqlite = ["aiosqlite>=0.20.0"]
@@ -375,7 +376,7 @@ classmethod-decorators = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-"advanced_alchemy/alembic/templates/*/env.py" = ["INP001"]
+"advanced_alchemy/alembic/templates/*/env.py" = ["INP001", "SIM105"]
 "advanced_alchemy/repository/*.py" = ['C901', 'UP006', 'UP035']
 "advanced_alchemy/repository/memory/*.py" = ['UP006', 'UP035']
 "advanced_alchemy/service/*.py" = ["PLR0911", "UP006", "UP035"]

tests/integration/test_alembic_commands.py

@@ -234,6 +234,21 @@ async def test_alembic_init(alembic_commands: commands.AlembicCommands, tmp_proj
         assert await async_(Path(file).is_file)()
 
 
+async def test_alembic_init_renders_postgres_enum_import(
+    alembic_commands: commands.AlembicCommands, tmp_project_dir: Path
+) -> None:
+    """The generated ``env.py`` should opt into PostgreSQL enum autogenerate support.
+
+    See https://github.com/litestar-org/advanced-alchemy/issues/492.
+    """
+    from advanced_alchemy.utils.sync_tools import async_
+
+    alembic_commands.init(directory=f"{tmp_project_dir}/migrations/")
+    env_contents = await async_(Path(f"{tmp_project_dir}/migrations/env.py").read_text)()
+    assert "import alembic_postgresql_enum" in env_contents
+    assert "except ImportError:" in env_contents
+
+
 async def test_alembic_init_already(alembic_commands: commands.AlembicCommands, tmp_project_dir: Path) -> None:
     from advanced_alchemy.utils.sync_tools import async_