feat: update hero model to use UUID7 and adjust related functions

Author: umbertogriffo

README.md

@@ -114,7 +114,7 @@ The code `dc` can be found in [docker_compose_cli.py](src/utils/docker_compose_c
 
 > [!NOTE]
 > To run the service with PostgreSQL backed database set `DATABASE_URL=postgresql://develop:develop_secret@db:5432/develop`
-> in .𝐞𝐧𝐯, setting db instead of localhost otherwise the service-api can't reach the database container.
+> in .𝐞𝐧𝐯, setting db instead of localhost otherwise the service-api and migration can't reach the database container.
 
 The `dc` CLI utility to run Docker Compose with specific profiles is available to start the application.
 

pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
     "sqlmodel~=0.0.27",
     "alembic>=1.17.2,<2.0.0",
     "psycopg2-binary>=2.9.10,<3.0.0",
+    "uuid-utils>=0.12.0"
 ]
 
 [dependency-groups]

…ons/2025_12_17_1007-7b56ff295e99_init.py …ons/2025_12_18_1212-438f1c13aa3b_init.pysrc/alembic/versions/2025_12_17_1007-7b56ff295e99_init.py renamed to src/alembic/versions/2025_12_18_1212-438f1c13aa3b_init.py src/alembic/versions/2025_12_17_1007-7b56ff295e99_init.py renamed to src/alembic/versions/2025_12_18_1212-438f1c13aa3b_init.py

@@ -1,8 +1,8 @@
 """init
 
-Revision ID: 7b56ff295e99
+Revision ID: 438f1c13aa3b
 Revises:
-Create Date: 2025-12-17 10:07:08.280928
+Create Date: 2025-12-18 12:12:05.956211
 
 """
 
@@ -13,7 +13,7 @@
 from alembic import op
 
 # revision identifiers, used by Alembic.
-revision: str = "7b56ff295e99"
+revision: str = "438f1c13aa3b"
 down_revision: Union[str, Sequence[str], None] = None
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
@@ -26,7 +26,7 @@ def upgrade() -> None:
         "hero",
         sa.Column("name", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
         sa.Column("age", sa.Integer(), nullable=True),
-        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("id", sa.Uuid(), nullable=False),
         sa.Column("secret_name", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
         sa.PrimaryKeyConstraint("id"),
     )

src/api/endpoints/heroes.py

@@ -3,7 +3,7 @@
 from api.deps import SessionDep, get_db_session
 from excepts import DatabaseEntryNotFound, get_error_content
 from fastapi import APIRouter, Depends, HTTPException, Query, status
-from models import Hero, HeroCreate, HeroPublic, HeroUpdate
+from models import UUID7, Hero, HeroCreate, HeroPublic, HeroUpdate
 from sqlmodel import select
 from utils.log import get_logger
 
@@ -52,7 +52,7 @@ def read_heroes(
     response_model=HeroPublic,
     dependencies=[Depends(get_db_session)],
 )
-def read_hero(hero_id: int, session: SessionDep):
+def read_hero(hero_id: UUID7, session: SessionDep):
     try:
         hero = session.get(Hero, hero_id)
         if not hero:
@@ -83,7 +83,7 @@ def read_hero(hero_id: int, session: SessionDep):
     response_model=HeroPublic,
     dependencies=[Depends(get_db_session)],
 )
-def update_hero(hero_id: int, hero: HeroUpdate, session: SessionDep):
+def update_hero(hero_id: UUID7, hero: HeroUpdate, session: SessionDep):
     try:
         hero_db = session.get(Hero, hero_id)
         if not hero_db:
@@ -118,7 +118,7 @@ def update_hero(hero_id: int, hero: HeroUpdate, session: SessionDep):
     response_description="Indicates whether the hero was successfully deleted",
     dependencies=[Depends(get_db_session)],
 )
-def delete_hero(hero_id: int, session: SessionDep):
+def delete_hero(hero_id: UUID7, session: SessionDep):
     try:
         hero = session.get(Hero, hero_id)
         if not hero:

src/models.py

@@ -1,4 +1,47 @@
+from typing import Annotated, Literal
+
+import uuid_utils.compat as uuid
+from pydantic import GetPydanticSchema
+from pydantic_core import core_schema
 from sqlmodel import Field, SQLModel
+from uuid_utils.compat import UUID
+
+
+# TODO: Remove this function when Pydantic adds native support for UUID7
+#       https://github.com/pydantic/pydantic-extra-types/issues/204
+def validate_uuid(val, version: Literal[1, 3, 4, 5, 6, 7, 8]) -> UUID:
+    # Convert string to UUID if needed
+    if isinstance(val, str):
+        try:
+            val = UUID(val)
+        except (ValueError, AttributeError):
+            raise ValueError(f"Invalid UUID format: {val}")
+    if not isinstance(val, UUID):
+        raise ValueError(f"Expected a UUID, got {type(val)}")
+    if val.version != version:
+        raise ValueError(f"Expected a UUID{version}, got UUID{val.version}")
+    return val
+
+
+UUID7 = Annotated[
+    UUID,
+    GetPydanticSchema(
+        get_pydantic_core_schema=lambda _,
+        handler: core_schema.with_info_plain_validator_function(
+            lambda val, info: validate_uuid(
+                UUID(val) if info.mode == "json" else val, version=7
+            ),
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda val, info: str(val) if info.mode == "json" else val,
+                info_arg=True,
+            ),
+        ),
+        get_pydantic_json_schema=lambda _, handler: {
+            **handler(core_schema.str_schema()),
+            "format": "uuid7",
+        },
+    ),
+]
 
 
 class HeroBase(SQLModel):
@@ -13,8 +56,8 @@ class HeroBase(SQLModel):
 class Hero(HeroBase, table=True):
     """Database model for Hero with the extra fields that are not always in the other models."""
 
-    id: int | None = Field(
-        default=None,
+    id: UUID7 = Field(
+        default_factory=uuid.uuid7,
         title="Hero ID",
         description="The unique identifier for the hero.",
         primary_key=True,
@@ -27,7 +70,7 @@ class Hero(HeroBase, table=True):
 class HeroPublic(HeroBase):
     """Public model for Hero without sensitive information."""
 
-    id: int
+    id: UUID7
 
 
 class HeroCreate(HeroBase):

tests/api/endpoints/test_heroes.py

@@ -51,11 +51,11 @@ def test_read_heroes(session: Session, client_with_db: TestClient):
     assert data[0]["name"] == hero_1.name
     assert "secret_name" not in data[0].keys()
     assert data[0]["age"] == hero_1.age
-    assert data[0]["id"] == hero_1.id
+    assert data[0]["id"] == str(hero_1.id)
     assert data[1]["name"] == hero_2.name
     assert "secret_name" not in data[1].keys()
     assert data[1]["age"] == hero_2.age
-    assert data[1]["id"] == hero_2.id
+    assert data[1]["id"] == str(hero_2.id)
 
 
 def test_read_hero(session: Session, client_with_db: TestClient):
@@ -70,7 +70,7 @@ def test_read_hero(session: Session, client_with_db: TestClient):
     assert data["name"] == hero_1.name
     assert "secret_name" not in data.keys()
     assert data["age"] == hero_1.age
-    assert data["id"] == hero_1.id
+    assert data["id"] == str(hero_1.id)
 
 
 def test_update_hero(session: Session, client_with_db: TestClient):
@@ -85,7 +85,7 @@ def test_update_hero(session: Session, client_with_db: TestClient):
     assert data["name"] == "Deadpuddle"
     assert "secret_name" not in data.keys()
     assert data["age"] is None
-    assert data["id"] == hero_1.id
+    assert data["id"] == str(hero_1.id)
 
 
 def test_delete_hero(session: Session, client_with_db: TestClient):