Prisma is the most popular TypeScript ORM. This guide covers UUID v7 configuration for new projects, migration from UUID v4, branded TypeScript ID types for type safety, and multi-database considerations. Background on why UUID v7 outperforms v4 as a primary key: UUID in Databases.
New project — PostgreSQL 18 (recommended)
// schema.prisma
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
generator client {
provider = "prisma-client-js"
}
model Order {
id String @id @default(dbgenerated("uuidv7()")) @db.Uuid
createdAt DateTime @default(now())
status String
items OrderItem[]
}
model OrderItem {
id String @id @default(dbgenerated("uuidv7()")) @db.Uuid
orderId String @db.Uuid
order Order @relation(fields: [orderId], references: [id])
name String
}
dbgenerated("uuidv7()") delegates generation to PostgreSQL 18’s built-in uuidv7() function. Every insert — via Prisma, raw SQL, or database migrations — gets a UUID v7 automatically. Requires PostgreSQL 18 or the pg_uuidv7 extension on earlier versions.
App-layer generation (any database)
model Order {
id String @id @db.Uuid
status String
}
// orders.service.ts
import { PrismaClient } from '@prisma/client';
import { v7 as uuidv7 } from 'uuid';
const prisma = new PrismaClient();
async function createOrder(status: string) {
return prisma.order.create({
data: { id: uuidv7(), status },
});
}
Pass id: uuidv7() explicitly on every create call. Works with PostgreSQL, MySQL, SQLite, and SQL Server. See UUID v7 ORM Support in 2026 for database-specific notes.
Prisma extension for automatic UUID v7
import { PrismaClient } from '@prisma/client';
import { v7 as uuidv7 } from 'uuid';
const prisma = new PrismaClient().$extends({
query: {
$allModels: {
async create({ args, query }) {
if (!args.data.id) args.data.id = uuidv7();
return query(args);
},
},
},
});
This extension automatically injects UUID v7 on every create() call where id is not provided — eliminating the need to remember to pass id at the call site.
Branded TypeScript ID types
// types.ts
type OrderId = string & { readonly _brand: 'OrderId' };
type UserId = string & { readonly _brand: 'UserId' };
const toOrderId = (raw: string): OrderId => raw as OrderId;
const toUserId = (raw: string): UserId => raw as UserId;
// ❌ Compile error — cannot pass UserId where OrderId expected
async function getOrder(id: OrderId) { /* ... */ }
const uid = toUserId(uuidv7());
getOrder(uid); // TypeScript error
Branded types catch accidental ID mix-ups at compile time with zero runtime overhead. See TypeScript UUID Types for the full pattern with Zod validation.
Migrating from UUID v4 to v7
Existing rows keep their UUID v4 values — the uuid column type stores both identically. Change only new inserts:
// Before
await prisma.order.create({ data: { id: crypto.randomUUID(), status } });
// After
await prisma.order.create({ data: { id: uuidv7(), status } });
Or change the schema default for PostgreSQL 18:
// Before
id String @id @default(uuid()) @db.Uuid
// After — run prisma migrate deploy
id String @id @default(dbgenerated("uuidv7()")) @db.Uuid
For a full zero-downtime dual-column migration, see Zero-Downtime UUID v4 to v7 Migration.
Further reading
- UUID in Databases
- UUID v7 ORM Support in 2026
- TypeScript UUID Types
- Zero-Downtime UUID Migration
- PostgreSQL 18 Ships Native UUID v7
- UUID in JavaScript
External references
- Prisma @default documentation
- Prisma Client extensions — query
- pg_uuidv7 extension for PostgreSQL 14–17
- RFC 9562 — UUID standard
- uuid npm package
Frequently asked questions
What is the best way to use UUID v7 in Prisma?
On PostgreSQL 18, use @default(dbgenerated("uuidv7()")) @db.Uuid — the database generates UUID v7 server-side so every insert path (Prisma, raw SQL, migrations) gets a v7 value automatically. On older PostgreSQL or other databases, use .$defaultFn(() => uuidv7()) in your Prisma Client calls or a custom Prisma extension. See UUID v7 ORM Support in 2026.
How do I migrate a Prisma model from UUID v4 to v7 without downtime?
The Prisma schema change is one line — replace @default(uuid()) with @default(dbgenerated("uuidv7()")) and run prisma migrate deploy. Existing rows keep their UUID v4 values; only new inserts use v7. The PostgreSQL uuid column type stores both versions identically. For a full dual-column migration strategy, see Zero-Downtime UUID v4 to v7 Migration.