SQLModel is built on SQLAlchemy and Pydantic, designed for use with FastAPI. UUID v7 primary keys provide time-ordered identifiers that work across SQLModel’s dual role as database model and API schema — the same UUID column serves FastAPI response serialization and PostgreSQL cursor pagination. See UUID in Python for the Python UUID ecosystem.
Install dependencies
pip install sqlmodel asyncpg uuid6 fastapi uvicorn
Model definition with UUID v7
from uuid import UUID
from typing import Optional
from sqlmodel import SQLModel, Field, Column
from sqlalchemy.dialects.postgresql import UUID as PgUUID
from uuid6 import uuid7 # pip install uuid6
class OrderBase(SQLModel):
customer_id: UUID
status: str = "pending"
total: float
class Order(OrderBase, table=True):
# Client-side UUID v7 default — encodes creation time
id: UUID = Field(
default_factory=uuid7,
primary_key=True,
)
class OrderCreate(OrderBase):
pass
class OrderRead(OrderBase):
id: UUID
PostgreSQL server-side default (alternative)
from sqlalchemy import text, Column
from sqlalchemy.dialects.postgresql import UUID as PgUUID
class Order(SQLModel, table=True):
# Server-side default — requires pg_uuidv7 extension
id: Optional[UUID] = Field(
default=None,
sa_column=Column(
PgUUID(as_uuid=True),
server_default=text("uuid_generate_v7()"),
primary_key=True,
)
)
customer_id: UUID
status: str = "pending"
total: float
Async database setup
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker
from sqlmodel import SQLModel
import os
engine = create_async_engine(os.environ["DATABASE_URL"], echo=False)
AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
async def init_db():
async with engine.begin() as conn:
await conn.run_sync(SQLModel.metadata.create_all)
async def get_db():
async with AsyncSessionLocal() as session:
yield session
FastAPI endpoints with cursor pagination
from fastapi import FastAPI, Depends, Query
from sqlmodel import select
from sqlalchemy.ext.asyncio import AsyncSession
from typing import Optional
from uuid import UUID
app = FastAPI()
@app.post("/orders", response_model=OrderRead, status_code=201)
async def create_order(order: OrderCreate, db: AsyncSession = Depends(get_db)):
db_order = Order.from_orm(order) # UUID v7 assigned by default_factory
db.add(db_order)
await db.commit()
await db.refresh(db_order)
return db_order
@app.get("/orders")
async def list_orders(
customer_id: UUID,
cursor: Optional[str] = Query(default=None),
limit: int = Query(default=20, le=100),
db: AsyncSession = Depends(get_db),
):
statement = (
select(Order)
.where(Order.customer_id == customer_id)
)
if cursor:
# UUID v7 lexicographic > cursor = created after cursor
statement = statement.where(Order.id > UUID(cursor))
statement = (
statement
.order_by(Order.id) # UUID v7 sort = chronological
.limit(limit + 1)
)
result = await db.execute(statement)
rows = result.scalars().all()
has_more = len(rows) > limit
data = rows[:limit] if has_more else rows
next_cursor = str(data[-1].id) if has_more else None
return {"data": data, "next_cursor": next_cursor}
Extract creation time from UUID v7
from uuid6 import UUID as UUID6
import datetime
def extract_timestamp(uuid_v7: str) -> datetime.datetime:
"""Extract creation time from UUID v7 string."""
hex_str = uuid_v7.replace("-", "")
ms = int(hex_str[:12], 16) # top 48 bits = Unix milliseconds
return datetime.datetime.fromtimestamp(ms / 1000, tz=datetime.timezone.utc)
# Example
order_id = "018fbe3a-4c5d-7b12-8f3e-1a2b3c4d5e6f"
created_at = extract_timestamp(order_id)
print(f"Order created: {created_at.isoformat()}")
Alembic migration note
SQLModel uses SQLAlchemy under the hood. UUID v7 columns appear as standard uuid columns in PostgreSQL migrations — no special handling needed:
# Generated Alembic migration
def upgrade() -> None:
op.create_table(
"order",
sa.Column("id", sa.UUID(), server_default=sa.text("uuid_generate_v7()"),
nullable=False),
sa.Column("customer_id", sa.UUID(), nullable=False),
sa.Column("status", sa.VARCHAR(), nullable=False),
sa.Column("total", sa.Float(), nullable=False),
sa.PrimaryKeyConstraint("id"),
)
Further reading
- UUID in Python — Generation and Validation
- UUID v7 for Cursor Pagination
- UUID v7 in Drizzle + PostgreSQL
- UUID in Databases — Storage and Indexing
External references
Frequently asked questions
How do I define a UUID v7 primary key in SQLModel?
Use Field(default_factory=uuid7, primary_key=True) where uuid7 is a function returning a uuid.UUID. Install the uuid6 package: from uuid6 import uuid7. SQLModel maps uuid.UUID to PostgreSQL uuid or SQLite TEXT automatically. See UUID in Python for UUID generation options.
How does UUID v7 cursor pagination work in SQLModel with FastAPI?
In the SQLModel/SQLAlchemy query layer, filter with select(Model).where(Model.id > cursor).order_by(Model.id). UUID v7 is lexicographically ordered, so id > cursor equals created_after(cursor). Return the last row's id as the next cursor in the FastAPI response. See UUID v7 for Cursor Pagination.
Can I use a PostgreSQL server-side UUID v7 default with SQLModel?
Yes. Use Field(sa_column=Column(UUID, server_default=text("uuid_generate_v7()"), primary_key=True)) with the pg_uuidv7 extension installed. This delegates UUID generation to PostgreSQL and keeps the Python model clean. See UUID v7 in Drizzle + PostgreSQL for the pg_uuidv7 extension setup.