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

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.