Map SQL Primary Key Strategies to Prisma @id

Primary Keys in Prisma

Every Prisma model requires exactly one identifier. SQL databases support various primary key strategies, and each maps to a different Prisma configuration.

Auto-Increment Integer

CREATE TABLE posts (
  id SERIAL PRIMARY KEY,
  title VARCHAR(255) NOT NULL
);

model Post {
  id    Int    @id @default(autoincrement())
  title String

  @@map("posts")
}

SERIAL (PostgreSQL), AUTO_INCREMENT (MySQL), and IDENTITY (SQL Server) all map to @default(autoincrement()). Prisma handles the dialect differences internally when generating SQL migrations.

UUID Primary Key

CREATE TABLE accounts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(255) NOT NULL
);

model Account {
  id   String @id @default(uuid())
  name String

  @@map("accounts")
}

UUID columns map to String with @default(uuid()). If you prefer database-level UUID generation, use @default(dbgenerated("gen_random_uuid()")) instead.

CUID / NanoID

Prisma natively supports cuid() as a default. If your SQL schema uses application-generated string IDs (common with NanoID or CUID), the converter maps the column to String @id @default(cuid()).

Composite Primary Key

CREATE TABLE order_items (
  order_id INTEGER NOT NULL,
  product_id INTEGER NOT NULL,
  quantity INTEGER NOT NULL DEFAULT 1,
  PRIMARY KEY (order_id, product_id)
);

model OrderItem {
  orderId   Int
  productId Int
  quantity  Int @default(1)

  @@id([orderId, productId])
  @@map("order_items")
}

Composite primary keys use @@id([...]) at the model level instead of @id on a single field. This is common for junction tables in many-to-many relationships.

BigInt IDs

For tables expecting billions of rows:

id BIGSERIAL PRIMARY KEY

Maps to BigInt @id @default(autoincrement()) in Prisma. Use BigInt when your IDs exceed the 32-bit integer range.

Choosing a Strategy

Strategy	Pros	Cons
Auto-increment	Simple, sortable, compact	Predictable, not globally unique
UUID v4	Globally unique, secure	Large (36 chars), not sortable
CUID / UUID v7	Globally unique, sortable	Slightly larger than integers
Composite	No surrogate column needed	Complex queries, no single identifier

The converter detects the SQL primary key strategy and selects the appropriate Prisma @default() function automatically.