Prismaの大きな役割3つ
| 機能 | 役割 |
|---|---|
| Prisma Client | TypeScriptからDBを操作 |
| Prisma Migrate | DB構造を変更・管理 |
| Prisma Studio | DBの中身をGUIで確認・編集 |
prisma migrate dev
prisma generate
schema.prisma
/ \
/ \
↓ ↓
migrate dev generate
↓ ↓
PostgreSQL Prisma Client
流れ
mkdir prisma-practice
cd prisma-practice
npm init -y
npm install -D typescript tsx @types/node
npm install -D prisma
npm install @prisma/client @prisma/adapter-pg pg
npx prisma init
# schema.prisma を編集
# 例:
# model Child {
# id Int @id @default(autoincrement())
# name String
# birthday DateTime
# createdAt DateTime @default(now())
# }
# マイグレーションを作成・DBに反映
npx prisma migrate dev --name init
# Prisma Client を生成
npx prisma generate
schema.prismaを理解する
schema.prismaの例
model Child {
id Int @id @default(autoincrement())
name String
birthday DateTime
nickname String?
createdAt DateTime @default(now()) @map("created_at")
@@map("children")
}
上のschema.prismaをSQLになおすと。
CREATE TABLE children (
id INTEGER GENERATED ... PRIMARY KEY,
name TEXT NOT NULL,
birthday TIMESTAMP NOT NULL,
nickname TEXT,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
?はNULLを許容するかどうか
name String # NULLを許容しない
name String? # NULLを許容する
prismaの型
| Prisma | 意味 |
|---|---|
Int |
整数 |
BigInt |
大きな整数 |
Float |
浮動小数点 |
Decimal |
固定精度の数値 |
String |
文字列 |
Boolean |
true / false |
DateTime |
日付・時刻 |
Json |
JSON |
Bytes |
バイナリ |
代表的な制約
| Prisma | 意味 |
|---|---|
model Child |
モデル(DBテーブルに対応) |
name String |
NULL不可の文字列 |
name String? |
NULL可の文字列 |
@id |
PRIMARY KEY |
@unique |
UNIQUE |
@default() |
DEFAULT |
autoincrement() |
自動採番 |
now() |
現在日時 |
@map() |
DBカラム名を変える |
@@map() |
DBテーブル名を変える |
@mapと@@map
@map
@mapはPrisma側のフィールド名とDB側のカラム名を分離するための機能。
TypeScriptではcreatedAt、
PostgreSQLではcreated_atという名前のカラムにしたいとき、次のように書く。
createdAt DateTime @map("created_at")
@@map
@@mapはPrisma側のモデル名とDB側のテーブル名を分離するための機能。
TypeScriptではChild、
PostgreSQLではchildrenという名前のテーブルにしたいとき、次のように書く。
model Child {
id Int @id @default(autoincrement())
name String
@@map("children")
}
マイグレーション
npx prisma migrate dev
schemaの変更を検出
↓
migration生成
↓
DBへ適用
npx prisma migrate deploy
本番環境へすでに作成済みのmigrationを実行する.
npx prisma migrate reset
開発DBを削除・再作成してmigrationを最初から適用する。
基本的に開発環境用。
今のDB
↓
削除
↓
空のDB
↓
migration 1
↓
migration 2
↓
migration 3
npx prisma db push
migration履歴を作らずにschema.prismaの状態をDBへ直接反映する。
ちょっとモデルを試したいときなどに使う。
本格的な開発には向かない。
Prisma Client
Prisma Clientは、
schema.prisma をもとに自動生成される、TypeScriptからDBを操作するためのクライアント。
schema.prisma
↓
npx prisma generate
↓
Prisma Clientが生成される
↓
TypeScriptから使う
DB操作
| 関数 | 意味 | 主な使い方 |
|---|---|---|
create() |
1件追加する | 新しいレコードを作成する |
createMany() |
複数件追加する | 複数レコードをまとめて作成する |
findMany() |
複数件取得する | 条件に一致するレコードを一覧で取得する |
findUnique() |
一意な条件で1件取得する |
@id や @unique で1件取得する |
findFirst() |
条件に一致する最初の1件を取得する | 一意ではない条件から1件だけ取得する |
update() |
1件更新する | 一意な条件で対象を指定して更新する |
updateMany() |
複数件更新する | 条件に一致する複数レコードを更新する |
upsert() |
あれば更新、なければ追加する | 存在に応じてUPDATEまたはINSERTする |
delete() |
1件削除する | 一意な条件で対象を削除する |
deleteMany() |
複数件削除する | 条件に一致する複数レコードを削除する |
count() |
件数を数える | 条件に一致するレコード数を取得する |
aggregate() |
集計する | 最大・最小・平均・合計・件数などを取得する |
groupBy() |
グループごとに集計する | SQLの GROUP BY 相当 |
create()
await prisma.child.create({
data: {
name: "太郎",
birthday: new Date("2025-01-01"),
},
});
createMany()
await prisma.child.createMany({
data: [
{
name: "太郎",
birthday: new Date("2025-01-01"),
},
{
name: "花子",
birthday: new Date("2025-02-01"),
},
],
});
findMany()
const children = await prisma.child.findMany({
where: {
name: "太郎",
},
});
findUnique()
const child = await prisma.child.findUnique({
where: {
id: 1,
},
});
findFirst()
const child = await prisma.child.findFirst({
where: {
name: "太郎",
},
});
update()
await prisma.child.update({
where: {
id: 1,
},
data: {
name: "次郎",
},
});
updateMany()
await prisma.child.updateMany({
where: {
name: "太郎",
},
data: {
name: "次郎",
},
});
upsert()
await prisma.child.upsert({
where: {
id: 1,
},
update: {
name: "次郎",
},
create: {
name: "太郎",
birthday: new Date("2025-01-01"),
},
});
delete()
await prisma.child.delete({
where: {
id: 1,
},
});
deleteMany()
await prisma.child.deleteMany({
where: {
name: "太郎",
},
});
count()
const count = await prisma.child.count({
where: {
name: "太郎",
},
});
aggregate()
const result = await prisma.child.aggregate({
_count: true,
_max: {
id: true,
},
});
groupBy()
const result = await prisma.child.groupBy({
by: ["name"],
_count: {
_all: true,
},
});
whereまとめ
where: {
フィールド名: {
条件演算子: 値,
},
}
where: {
id: {
gte: 10,
},
}
| SQL | Prisma |
|---|---|
name = '太郎' |
name: "太郎" |
name <> '太郎' |
name: { not: "太郎" } |
id > 10 |
id: { gt: 10 } |
id >= 10 |
id: { gte: 10 } |
id < 10 |
id: { lt: 10 } |
id <= 10 |
id: { lte: 10 } |
id IN (1,2,3) |
id: { in: [1,2,3] } |
LIKE '%郎%' |
contains: "郎" |
LIKE '太%' |
startsWith: "太" |
LIKE '%郎' |
endsWith: "郎" |
IS NULL |
field: null |
IS NOT NULL |
field: { not: null } |
BETWEEN |
gte + lte
|
AND |
条件を並べる / AND
|
OR |
OR: [...] |
NOT |
NOT: {...} |
等しい equals
// 省略形
const children = await prisma.child.findMany({
where: {
name: "太郎",
},
});
// 明示的
const children = await prisma.child.findMany({
where: {
name: {
equals: "太郎",
},
},
});
等しくない: not
const children = await prisma.child.findMany({
where: {
name: {
not: "太郎",
},
},
});
より大きい: gt
const children = await prisma.child.findMany({
where: {
id: {
gt: 10,
}
}
})
以上: gte
const children = await prisma.child.findMany({
where: {
id: {
gte: 10,
},
},
});
より小さい: lt
const children = await prisma.child.findMany({
where: {
id: {
lt: 10,
},
},
});
以下: lte
const children = await prisma.child.findMany({
where: {
id: {
lte: 10,
},
},
});
IN
const children = await prisma.child.findMany({
where: {
id: {
in: [1, 3, 5],
},
},
});
NOT IN
const children = await prisma.child.findMany({
where: {
id: {
notIn: [1, 3, 5],
},
},
});
contains
const children = await prisma.child.findMany({
where: {
name: {
contains: "郎",
},
},
});
startWith
const children = await prisma.child.findMany({
where: {
name: {
startsWith: "太",
},
},
});
endWith
const children = await prisma.child.findMany({
where: {
name: {
endsWith: "郎",
},
},
});
AND
単純なAND
// 基本形
where: {
条件1,
条件2,
}
const children = await prisma.child.findMany({
where: {
name: "太郎",
id: {
gte: 10,
},
},
});
明示的なAND
const children = await prisma.child.findMany({
where: {
AND: [
{
name: "太郎",
},
{
id: {
gte: 10,
},
},
],
},
});
OR
const children = await prisma.child.findMany({
where: {
OR: [
{
name: "太郎",
},
{
name: "花子",
},
],
},
});
NOT
const children = await prisma.child.findMany({
where: {
NOT: {
name: "太郎",
},
},
});
範囲指定
const children = await prisma.child.findMany({
where: {
id: {
gte: 10,
lte: 20,
},
},
});
NULLを検索する
// nullを検索
const children = await prisma.child.findMany({
where: {
nickname: null,
},
});
// null以外を検索
const children = await prisma.child.findMany({
where: {
nickname: {
not: null,
},
},
});
日付の条件
const children = await prisma.child.findMany({
where: {
birthday: {
gte: new Date("2025-01-01"),
},
},
});
件を組み合わせる
条件: 名前に「郎」を含み、idが10以上、かつ名前が「次郎」ではない。
const children = await prisma.child.findMany({
where: {
name: {
contains: "郎",
not: "次郎",
},
id: {
gte: 10,
},
},
});
リレーションまとめ
例
model Child {
id Int @id @default(autoincrement())
name String
events Event[]
@@map("children")
}
model Event {
id Int @id @default(autoincrement())
childId Int @map("child_id")
type String
child Child @relation(fields: [childId], references: [id], onDelete: Cascade)
@@map("events")
}
// 値を取得
const child = await prisma.child.findUnique({
where: {
id: 1,
},
include: {
events: true,
},
});
// 結果
{
id: 1,
name: "太郎",
events: [
{
id: 1,
childId: 1,
type: "ミルク"
},
{
id: 2,
childId: 1,
type: "睡眠"
}
]
}
onDelete
| 指定 | 意味 |
|---|---|
Cascade |
親を削除すると子も削除 |
Restrict |
子が存在すると親を削除できない |
SetNull |
親削除時に外部キーをNULLにする |
NoAction |
DB側の制約に従う |
子の登録方法
// 外部キーを直接指定
await prisma.event.create({
data: {
childId: 1,
type: "ミルク",
},
});
// 既存のChildと関連付ける書き方
await prisma.event.create({
data: {
type: "ミルク",
child: {
connect: {
id: 1,
},
},
},
});
include
Child 本体に加えて、関連する events も返る。
const child = await prisma.child.findUnique({
where: {
id: 1,
},
include: {
events: true,
},
});
select
取得するフィールドを絞る。
// シンプルなselect
const child = await prisma.child.findUnique({
where: {
id: 1,
},
select: {
id: true,
name: true,
},
});
// 関連先のフィールドも搾れる
const child = await prisma.child.findUnique({
where: {
id: 1,
},
select: {
id: true,
name: true,
events: {
select: {
id: true,
type: true,
},
},
},
});
some
条件に一致する関連データが1件以上あるものを探す。
// ミルクのEventを1件以上持つChildを探す。
const children = await prisma.child.findMany({
where: {
events: {
some: {
type: "ミルク",
},
},
},
});
some
条件に一致する関連データが1件もないものを探す。
// ミルクのEventを1件も持たないChild
const children = await prisma.child.findMany({
where: {
events: {
none: {
type: "ミルク",
},
},
},
});
every
関連する全データが条件を満たすものを探す。
// 持っているEventがすべてミルクのChild
const children = await prisma.child.findMany({
where: {
events: {
every: {
type: "ミルク",
},
},
},
});
1件側のリレーションを条件にする
Event から Child を条件指定する場合。
// Childのnameが「太郎」であるEvent
const events = await prisma.event.findMany({
where: {
child: {
name: "太郎",
},
},
});
Prismaのトランザクションまとめ
基本形
await prisma.$transaction([
prisma.child.create({
data: {
name: "太郎",
birthday: new Date("2025-01-01"),
},
}),
prisma.event.create({
data: {
childId: 1,
type: "ミルク",
},
}),
]);
上の場合、
両方成功
→ COMMIT
どちらか失敗
→ ROLLBACK
となる。
前の処理結果を次で使う場合
関数形式を使う。
await prisma.$transaction(async (tx) => {
const child = await tx.child.create({
data: {
name: "太郎",
birthday: new Date("2025-01-01"),
},
});
await tx.event.create({
data: {
childId: child.id,
type: "ミルク",
},
});
});
Prismaで生SQLを使う
下記のような状況で使う。
- Prisma APIでは書きにくい複雑なSQL
- PostgreSQL固有の機能を使いたい
- 特殊な集計やクエリを書きたい
$queryRaw
const children = await prisma.$queryRaw`
SELECT *
FROM children
WHERE id = 1
`;
$executeRaw
const count = await prisma.$executeRaw`
UPDATE children
SET name = '次郎'
WHERE id = 1
`;
値を埋め込む
const id = 1;
const children = await prisma.$queryRaw`
SELECT *
FROM children
WHERE id = ${id}
`;
Prismaのエラーハンドリングまとめ
基本形
import { Prisma } from "@/generated/prisma/client";
try {
await prisma.user.create({
data: {
email: "test@example.com",
},
});
} catch (error) {
if (error instanceof Prisma.PrismaClientKnownRequestError) {
if (error.code === "P2002") {
console.log("UNIQUE制約に違反しました");
}
}
}
| よくみるエラーコード | 意味 |
|---|---|
P2002 |
UNIQUE制約違反 |
P2003 |
外部キー制約違反 |
P2025 |
対象レコードが見つからない |
| よくある原因 | 例 |
|---|---|
| UNIQUE違反 | 同じメールアドレスを2回登録 |
| 外部キー違反 | 存在しない childId を指定 |
| レコードが存在しない |
update() / delete() で存在しないIDを指定 |
| DB接続失敗 | PostgreSQLが停止している |
| 型・必須値の問題 | 必須フィールドが不足 |
findUnique()
→ 見つからなければ null
update() / delete()
→ 対象がなければエラーになることがある
create()
→ 制約違反ならエラー
Prismaのぺージネーションまとめ
take
最初の指定した件数を取得する。
// 最初の10件を取得
const children = await prisma.child.findMany({
take: 10,
})
skip
最初の指定した件数を飛ばす。
// 11件目から20件目まで取得する
const children = await prisma.child.findMany({
skip: 10,
take: 10,
});
cursor
/*
id = 100 を基準にする
↓
100自身は skip: 1 で飛ばす
↓
その次の10件を取得
*/
const children = await prisma.child.findMany({
cursor: {
id: 100,
},
skip: 1,
take: 10,
orderBy: {
id: "asc",
},
});
Prismaのネストした書き込みまとめ
Prismaでは、関連するデータを1回の create() や update() の中でまとめて操作可能。
親と子を同時に作成
/*
Childを1件作成
+
そのChildに紐づくEventを2件作成
*/
const child = await prisma.child.create({
data: {
name: "太郎",
birthday: new Date("2025-01-01"),
events: {
create: [
{
type: "ミルク",
},
{
type: "睡眠",
},
],
},
},
});
connect
すでに存在するデータと関連付ける。
// 新しいEvent
// ↓
// 既存の id = 1 のChildと関連付ける
await prisma.event.create({
data: {
type: "ミルク",
child: {
connect: {
id: 1,
},
},
},
});
connectOrCreate
関連先があれば接続、なければ作成。
// 存在する
// → connect
// 存在しない
// → create
child: {
connectOrCreate: {
where: {
id: 1,
},
create: {
name: "太郎",
birthday: new Date("2025-01-01"),
},
},
}
関連データを追加する
// 既存のChildにEventを追加
await prisma.child.update({
where: {
id: 1,
},
data: {
events: {
create: {
type: "ミルク",
},
},
},
});
関連データを更新する
// id = 1 のChildに関連する id = 10 のEventを更新
await prisma.child.update({
where: {
id: 1,
},
data: {
events: {
update: {
where: {
id: 10,
},
data: {
type: "睡眠",
},
},
},
},
});
関連データを削除する
// 関連するEventそのものがDBから削除される
await prisma.child.update({
where: {
id: 1,
},
data: {
events: {
delete: {
id: 10,
},
},
},
});
Prismaの index / unique / 複合キーまとめ
@unique
重複禁止
model User {
id Int @id @default(autoincrement())
email String @unique
}
@@unique
組み合わせでの重複禁止
model Membership {
id Int @id @default(autoincrement())
userId Int
teamId Int
@@unique([userId, teamId])
}
@@index
検索を速くするためのインデックスを作る。
model Event {
id Int @id @default(autoincrement())
childId Int
type String
@@index([childId])
}
CREATE INDEX ...
ON events (child_id);
複合インデックスも可能
model Event {
id Int @id @default(autoincrement())
childId Int
recordedAt DateTime
@@index([childId, recordedAt])
}
@@id
複数フィールドをまとめて主キーにする
model Membership {
userId Int
teamId Int
@@id([userId, teamId])
}
Prismaのenumまとめ
enumは決められた候補の中からしか値を入れられないようにする時に使う。
// この場合、type に入れられるのは MILK / SLEEP / DIAPER だけ
enum EventType {
MILK
SLEEP
DIAPER
}
model Event {
id Int @id @default(autoincrement())
type EventType
}
Prismaの introspection(既存DBから schema.prisma を作る)
すでにPostgreSQL側にテーブルがある場合、Prismaからその構造を読み取れる。
npx prisma db pull
PostgreSQL
↓
テーブル構造を読み取る
↓
schema.prisma を更新
| コマンド | 向き |
|---|---|
prisma db pull |
DB → schema.prisma
|
prisma migrate dev |
schema.prisma → DB |
prisma db push |
schema.prisma → DB(履歴なし) |