feat: add sort_order to mixin columns for consistent table layout (#581)

Add sort_order to mixin columns for consistent table layout

- Add sort_order=-100 to primary key columns (id) across all mixins
- Add sort_order=3001 to sentinel column
- Add sort_order=3002 to created_at audit column
- Add sort_order=3003 to updated_at audit column

This ensures consistent column ordering in generated tables:
primary keys first, user columns in middle, audit/sentinel columns last.

Author: glendonyeo

advanced_alchemy/mixins/audit.py

@@ -12,12 +12,14 @@ class AuditColumns:
     created_at: Mapped[datetime.datetime] = mapped_column(
         DateTimeUTC(timezone=True),
         default=lambda: datetime.datetime.now(datetime.timezone.utc),
+        sort_order=3002,
     )
     """Date/time of instance creation."""
     updated_at: Mapped[datetime.datetime] = mapped_column(
         DateTimeUTC(timezone=True),
         default=lambda: datetime.datetime.now(datetime.timezone.utc),
         onupdate=lambda: datetime.datetime.now(datetime.timezone.utc),
+        sort_order=3003,
     )
     """Date/time of instance last update."""
 

advanced_alchemy/mixins/bigint.py

@@ -35,6 +35,7 @@ def id(cls) -> Mapped[int]:
             BigIntIdentity,
             Sequence(f"{cls.__tablename__}_id_seq", **seq_kwargs),  # type: ignore[attr-defined]
             primary_key=True,
+            sort_order=-100,
         )
 
 
@@ -53,4 +54,5 @@ def id(cls) -> Mapped[int]:
             BigIntIdentity,
             Identity(start=1, increment=1),
             primary_key=True,
+            sort_order=-100,
         )

advanced_alchemy/mixins/nanoid.py

@@ -25,5 +25,5 @@ def __init_subclass__(cls, **kwargs: Any) -> None:
         if not NANOID_INSTALLED and not cls.__module__.startswith("advanced_alchemy"):  # pragma: no cover
             logger.warning("`fastnanoid` not installed, falling back to `uuid4` for NanoID generation.")
 
-    id: Mapped[str] = mapped_column(default=nanoid, primary_key=True)
+    id: Mapped[str] = mapped_column(default=nanoid, primary_key=True, sort_order=-100)
     """Nano ID Primary key column."""

advanced_alchemy/mixins/sentinel.py

@@ -30,5 +30,6 @@ def _sentinel(cls) -> Mapped[int]:
             insert_sentinel=True,
             use_existing_column=True,
             nullable=True,
+            sort_order=3001,
             **cls._sentinel_kwargs,
         )

advanced_alchemy/mixins/uuid.py

@@ -26,7 +26,7 @@
 class UUIDPrimaryKey(SentinelMixin):
     """UUID Primary Key Field Mixin."""
 
-    id: Mapped[UUID] = mapped_column(default=uuid4, primary_key=True)
+    id: Mapped[UUID] = mapped_column(default=uuid4, primary_key=True, sort_order=-100)
     """UUID Primary key column."""
 
 
@@ -39,7 +39,7 @@ def __init_subclass__(cls, **kwargs: Any) -> None:
         if not UUID_UTILS_INSTALLED and not cls.__module__.startswith("advanced_alchemy"):  # pragma: no cover
             logger.warning("`uuid-utils` not installed, falling back to `uuid4` for UUID v6 generation.")
 
-    id: Mapped[UUID] = mapped_column(default=uuid6, primary_key=True)
+    id: Mapped[UUID] = mapped_column(default=uuid6, primary_key=True, sort_order=-100)
     """UUID Primary key column."""
 
 
@@ -52,5 +52,5 @@ def __init_subclass__(cls, **kwargs: Any) -> None:
         if not UUID_UTILS_INSTALLED and not cls.__module__.startswith("advanced_alchemy"):  # pragma: no cover
             logger.warning("`uuid-utils` not installed, falling back to `uuid4` for UUID v7 generation.")
 
-    id: Mapped[UUID] = mapped_column(default=uuid7, primary_key=True)
+    id: Mapped[UUID] = mapped_column(default=uuid7, primary_key=True, sort_order=-100)
     """UUID Primary key column."""