セットアップ

インストール、init、DB 接続、最初のテーブル作成、PrismaClient のシングルトン化まで。

インストール

npm install -D prisma
npm install @prisma/client

prisma（dev）: CLI（migrate / generate / studio）
@prisma/client: 実行時に使う Client

プロジェクト初期化

npx prisma init --datasource-provider postgresql

実行されると次のものができる:

prisma/
  └── schema.prisma         # スキーマ宣言ファイル
.env                        # DATABASE_URL を書く

DATABASE_URL の書き方

PostgreSQL

DATABASE_URL="postgresql://user:password@localhost:5432/mydb?schema=public"

# Supabase
DATABASE_URL="postgresql://postgres:[PASSWORD]@db.xxxxx.supabase.co:5432/postgres"

# Connection Pool 経由（Supabase / Neon / PgBouncer）
DATABASE_URL="postgresql://...:6543/postgres?pgbouncer=true"
DIRECT_URL="postgresql://...:5432/postgres"     # migrate 用に必要

MySQL

DATABASE_URL="mysql://user:password@localhost:3306/mydb"

SQLite（学習・ローカル開発）

DATABASE_URL="file:./dev.db"

schema.prisma の最小例

datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DIRECT_URL")     // migration 用（PgBouncer 越えで必要）
}

generator client {
  provider = "prisma-client-js"
  // v6 で TypeScript 製の新 Client（Edge 対応）
  // provider = "prisma-client"
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
}

model Post {
  id       String  @id @default(cuid())
  title    String
  content  String?
  authorId String
  author   User    @relation(fields: [authorId], references: [id])
}

最初のマイグレーション

npx prisma migrate dev --name init

次の処理が実行される:

SQL マイグレーションを生成 (prisma/migrations/...)
シャドウ DB（一時 DB）で SQL を検証
本物の DB に適用
@prisma/client を再生成

Prisma Client の使用

// lib/prisma.ts
import { PrismaClient } from "@prisma/client"

export const prisma = new PrismaClient()

// app.ts
const users = await prisma.user.findMany()

Next.js / 開発時のシングルトン化

Next.js の HMR で new PrismaClient() が大量生成されると接続枯渇する。グローバルにキャッシュする定石パターン:

// lib/prisma.ts
import { PrismaClient } from "@prisma/client"

const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient }

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: ["query", "error", "warn"],
  })

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma

Prisma Studio

DB の中身を見たり編集したりできる Web GUI:

npx prisma studio
# http://localhost:5555

主要 CLI コマンド

コマンド	用途
`prisma init`	プロジェクト初期化
`prisma migrate dev`	開発: マイグレーション作成 + 適用 + generate
`prisma migrate deploy`	本番: 既存マイグレーションを適用
`prisma migrate reset`	DB を全消去 + 再適用 + seed
`prisma db push`	migration 履歴を作らずに schema を反映（プロトタイピング）
`prisma db pull`	既存 DB から schema を逆生成（イントロスペクション）
`prisma db seed`	シードスクリプト実行
`prisma generate`	Client 再生成
`prisma studio`	GUI 起動
`prisma format`	schema.prisma の整形
`prisma validate`	schema 検証

シードスクリプト

// package.json
{
  "prisma": {
    "seed": "tsx prisma/seed.ts"
  }
}

// prisma/seed.ts
import { PrismaClient } from "@prisma/client"
const prisma = new PrismaClient()

async function main() {
  await prisma.user.upsert({
    where: { email: "alice@example.com" },
    update: {},
    create: {
      email: "alice@example.com",
      name: "Alice",
      posts: { create: { title: "Hello" } },
    },
  })
}

main().finally(() => prisma.$disconnect())

ログ出力

const prisma = new PrismaClient({
  log: [
    { emit: "event", level: "query" },
    { emit: "stdout", level: "error" },
  ],
})

prisma.$on("query", (e) => {
  console.log(`${e.duration}ms ${e.query}`)
})

環境変数の取り扱い

Prisma CLI は自動で .env を読む（dotenv 不要）
Next.js は .env.local を読むので、CLI 用に .env を別途用意するか共有
本番はSecrets Manager（Vercel / Railway / AWS）

TypeScript の設定

基本的には何もしなくても動く。strict モード推奨:

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "node"
  }
}

「動作確認」の最短ルート

npx prisma init
.env に DATABASE_URL（SQLite ならそのまま使える）
schema.prisma に model を 1 つ書く
npx prisma migrate dev --name init
適当な ts ファイルで prisma.user.create({ data: { email: "..." } })
npx prisma studio でデータが入ったか確認

失敗パターン

症状	原因
P1001 Can't reach database	DATABASE_URL 誤り / FW / SSL 設定
P3014 shadow database 失敗	権限不足。ローカルで権限あるユーザを使うか`--create-only`
P1010 Permission denied	DB ユーザに CREATE 権限なし
HMR で接続増殖	シングルトンパターン
Edge / Cloudflare Workers で動かない	Driver adapter / Accelerate を使う
migrate dev が production を壊す	本番は migrate deployを使う

本番では migrate dev を使わない

migrate dev はシャドウ DB を作って実行する開発専用コマンド。本番では必ず migrate deploy を使う。

スタートのおすすめ

まず SQLite + 1 model で素振り。Prisma Client の型推論を体感したら、実プロジェクトで Postgres に切り替える。学習コストはこれで十分。