Drizzle ORM is a TypeScript-first ORM with a schema-as-code API — the schema definition is the source of truth for both TypeScript types and SQL migrations. UUID v7 primary keys integrate cleanly: define the column with .$defaultFn(() => uuidv7()) and Drizzle calls it before every insert that omits id. See UUID v4 vs v7 for the B-tree performance rationale.
PostgreSQL schema with UUID v7
// schema.ts
import { pgTable, uuid, text, timestamp } from 'drizzle-orm/pg-core';
import { v7 as uuidv7 } from 'uuid';
export const orders = pgTable('orders', {
id: uuid('id').primaryKey().notNull().$defaultFn(() => uuidv7()),
customerId: uuid('customer_id').notNull(),
status: text('status').notNull(),
createdAt: timestamp('created_at').defaultNow().notNull(),
});
export const orderItems = pgTable('order_items', {
id: uuid('id').primaryKey().notNull().$defaultFn(() => uuidv7()),
orderId: uuid('order_id').notNull().references(() => orders.id),
name: text('name').notNull(),
});
.$defaultFn() is called by Drizzle before each INSERT — it does not set a database-level DEFAULT, so the value appears in the query parameters rather than as a server default. See UUID in Databases for the storage detail.
PostgreSQL 18 — server-side default
import { sql } from 'drizzle-orm';
export const orders = pgTable('orders', {
id: uuid('id').primaryKey().notNull().default(sql`uuidv7()`),
status: text('status').notNull(),
});
.default(sqluuidv7()) maps to DEFAULT uuidv7() in the generated CREATE TABLE DDL — the database generates UUID v7 for every INSERT, including raw SQL statements. Requires PostgreSQL 18.
Querying
import { db } from './db';
import { orders } from './schema';
import { eq, gte, and } from 'drizzle-orm';
// Insert — id is assigned by $defaultFn
const [order] = await db
.insert(orders)
.values({ customerId: '...', status: 'pending' })
.returning();
console.log(order.id); // UUID v7 string
// Find by id
const found = await db
.select()
.from(orders)
.where(eq(orders.id, order.id));
// Time-range query using UUID v7 lower bound
const lowerBound = buildUuidV7Bound(Date.now() - 3600_000); // last hour
const recent = await db
.select()
.from(orders)
.where(gte(orders.id, lowerBound))
.orderBy(orders.id);
Because Drizzle maps the uuid column to string in TypeScript, UUID v7 is handled as a plain string — no special cast needed. See Time Precision for building UUID v7 time bounds.
Branded TypeScript ID types
// types.ts
export type OrderId = string & { readonly _brand: 'OrderId' };
export type CustomerId = string & { readonly _brand: 'CustomerId' };
export const toOrderId = (s: string): OrderId => s as OrderId;
export const toCustomerId = (s: string): CustomerId => s as CustomerId;
// schema.ts — use branded type in queries
import type { OrderId } from './types';
export async function getOrder(id: OrderId) {
return db.select().from(orders).where(eq(orders.id, id));
}
Branded types catch accidental ID swaps at compile time. The full pattern including Zod validation is in TypeScript UUID Types.
Migrating from UUID v4 to v7
// Before
id: uuid('id').primaryKey().notNull().$defaultFn(() => crypto.randomUUID()),
// After — generates new migration, no column type change
id: uuid('id').primaryKey().notNull().$defaultFn(() => uuidv7()),
Run drizzle-kit generate — Drizzle sees no schema change (the $defaultFn is application-layer only) and produces an empty migration. Existing rows keep their UUID v4 values. See Zero-Downtime UUID Migration.
Further reading
- UUID v7 ORM Support in 2026
- UUID in JavaScript — full guide
- UUID in Prisma — comparison ORM
- UUID in Databases — storage and indexing
- TypeScript UUID Types — branded types
- Zero-Downtime UUID Migration
External references
Frequently asked questions
How do I use UUID v7 as a primary key in Drizzle ORM?
Define the column as uuid('id').primaryKey().notNull().$defaultFn(() => uuidv7()). The .$defaultFn() is called by Drizzle before every insert where id is not provided. For PostgreSQL 18, use .default(sql`uuidv7()`) instead to delegate generation to the database. See UUID v7 ORM Support in 2026.
Does Drizzle ORM support UUID v7 with MySQL or SQLite?
Drizzle supports .$defaultFn(() => uuidv7()) for any database — UUID v7 is generated at the application layer before the INSERT. For MySQL, store UUIDs as varchar(36) or binary(16) (more efficient). For SQLite, use text('id') with a defaultFn. See MySQL UUID Storage Best Practices.