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.

// 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

External references

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.