SQLの主キー戦略をPrismaの@idにマッピングする

オートインクリメント整数、UUID、複合キーなど、異なるSQLの主キー型がPrismaの@id、@default(autoincrement())、@@idにどのように変換されるかを学びます。

Basic Models

詳細な説明

Prismaにおける主キー

すべてのPrisma modelには正確に1つの識別子が必要です。SQLデータベースはさまざまな主キー戦略をサポートしており、それぞれ異なるPrisma設定にマッピングされます。

オートインクリメント整数

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)、IDENTITY(SQL Server)はすべて@default(autoincrement())にマッピングされます。Prismaはマイグレーション生成時に方言の違いを内部的に処理します。

UUID主キー

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カラムはString@default(uuid())にマッピングされます。データベースレベルでのUUID生成を使用したい場合は、代わりに@default(dbgenerated("gen_random_uuid()"))を使用してください。

CUID / NanoID

Prismaはデフォルトとしてcuid()をネイティブにサポートしています。SQLスキーマがアプリケーション生成の文字列ID(NanoIDやCUIDで一般的)を使用している場合、コンバーターはカラムをString @id @default(cuid())にマッピングします。

複合主キー

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")
}

複合主キーは、単一フィールドの@idの代わりにmodelレベルの@@id([...])を使用します。これは多対多リレーションシップの中間テーブルで一般的です。

BigInt ID

数十億行が想定されるテーブルの場合:

id BIGSERIAL PRIMARY KEY

PrismaではBigInt @id @default(autoincrement())にマッピングされます。IDが32ビット整数の範囲を超える場合にBigIntを使用してください。

戦略の選択

戦略 メリット デメリット
オートインクリメント シンプル、ソート可能、コンパクト 予測可能、グローバルに一意でない
UUID v4 グローバルに一意、安全 大きい(36文字)、ソート不可
CUID / UUID v7 グローバルに一意、ソート可能 整数よりわずかに大きい
複合 代理カラム不要 クエリが複雑、単一識別子なし

コンバーターはSQLの主キー戦略を検出し、適切なPrismaの@default()関数を自動的に選択します。

ユースケース

オートインクリメントID、UUIDキー、中間テーブルの複合主キーが混在するデータベースを移行する場合に、コンバーターが各戦略を正しいPrismaの@idと@default設定にマッピングします。

試してみる — SQL to Prisma Schema

フルツールを開く