Change organization PK to auto-increment integer

Replace the UUID primary key on the organizations table with an
auto-incrementing integer. The id field is now treated as an internal
implementation detail: it remains in the domain model and ORM layer
but is removed from all public-facing API response models (client
and handler models). Includes an Alembic migration to drop and
recreate the column.

Author: jonathansick

alembic/versions/20260311_0000_a1b2c3d4e5f6_change_organization_id_to_integer.py

@@ -0,0 +1,43 @@
+"""Change organization id from UUID to auto-incrementing integer.
+
+Revision ID: a1b2c3d4e5f6
+Revises: cf3b3f99916b
+Create Date: 2026-03-11 00:00:00.000000+00:00
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "a1b2c3d4e5f6"
+down_revision: str | None = "cf3b3f99916b"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    # Early development — no production data to migrate.
+    # Drop the UUID column and recreate as auto-incrementing integer.
+    op.drop_constraint("organizations_pkey", "organizations", type_="primary")
+    op.drop_column("organizations", "id")
+    op.add_column(
+        "organizations",
+        sa.Column(
+            "id",
+            sa.Integer(),
+            sa.Identity(always=False),
+            nullable=False,
+        ),
+    )
+    op.create_primary_key("organizations_pkey", "organizations", ["id"])
+
+
+def downgrade() -> None:
+    op.drop_constraint("organizations_pkey", "organizations", type_="primary")
+    op.drop_column("organizations", "id")
+    op.add_column(
+        "organizations",
+        sa.Column("id", sa.Uuid(), nullable=False),
+    )
+    op.create_primary_key("organizations_pkey", "organizations", ["id"])

client/src/docverse/client/models/organizations.py

@@ -5,7 +5,6 @@
 from datetime import datetime, timedelta
 from enum import StrEnum
 from typing import Annotated, Any
-from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
@@ -91,8 +90,6 @@ class Organization(BaseModel):
 
     self_url: str = Field(description="URL to this organization resource.")
 
-    id: UUID = Field(description="Unique identifier for the organization.")
-
     slug: str = Field(description="URL-safe identifier for the organization.")
 
     title: str = Field(description="Display title for the organization.")

src/docverse/dbschema/organization.py

@@ -2,11 +2,10 @@
 
 from __future__ import annotations
 
-import uuid
 from datetime import datetime
 from typing import Any
 
-from sqlalchemy import DateTime, Enum, Index, Integer, String, Text, Uuid
+from sqlalchemy import DateTime, Enum, Index, Integer, String, Text
 from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column
 from sqlalchemy.sql import func
@@ -21,8 +20,8 @@ class SqlOrganization(Base):
 
     __tablename__ = "organizations"
 
-    id: Mapped[uuid.UUID] = mapped_column(
-        Uuid, primary_key=True, default=uuid.uuid4
+    id: Mapped[int] = mapped_column(
+        Integer, primary_key=True, autoincrement=True
     )
 
     slug: Mapped[str] = mapped_column(String(64), unique=True, nullable=False)

src/docverse/domain/organization.py

@@ -4,7 +4,6 @@
 
 from datetime import datetime, timedelta
 from typing import Any
-from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -16,7 +15,7 @@ class Organization(BaseModel):
 
     model_config = ConfigDict(from_attributes=True)
 
-    id: UUID = Field(description="Unique identifier for the organization.")
+    id: int = Field(description="Unique identifier for the organization.")
 
     slug: str = Field(description="URL-safe identifier for the organization.")
 

src/docverse/handlers/admin/models.py

@@ -20,7 +20,6 @@ def from_domain(cls, domain: OrganizationDomain, request: Request) -> Self:
             self_url=str(
                 request.url_for("get_organization", org_slug=domain.slug)
             ),
-            id=domain.id,
             slug=domain.slug,
             title=domain.title,
             base_domain=domain.base_domain,

tests/handlers/admin_test.py

@@ -24,7 +24,7 @@ async def test_create_organization(client: AsyncClient) -> None:
     assert data["url_scheme"] == "subdomain"
     assert data["root_path_prefix"] == "/"
     assert data["purgatory_retention"] == 2592000
-    assert data["id"] is not None
+    assert "id" not in data
     assert data["date_created"] is not None
     assert data["date_updated"] is not None
     assert data["self_url"].endswith("/admin/orgs/test-org")