Next.jsで学ぶReact講座 90日コース | Next.jsでCRUDアプリ開発 - Day 53:ORM

React Next.jsで学ぶReact講座90日コース
スポンサーリンク
スポンサーリンク
  1. Day 53:ORM ― Schema・Migration・Modelを理解して、Next.jsからデータベースへ接続する
  2. 今回のゴールと使用環境
    1. Prismaのバージョンをそろえる
  3. ORMとは何か
    1. SQLで書く場合と比較する
    2. ORMはデータベースの代わりではありません
    3. ORMを使ってもSQLの知識は必要です
  4. Schema・Model・Migrationの違い
    1. Schemaは「データ構造の設計」です
    2. Modelは「扱う対象の定義」です
    3. Migrationは「構造変更の履歴」です
  5. 設計・反映・生成を混同しない
  6. 実装前にファイル構成を確認する
  7. Next.jsプロジェクトを準備する
    1. 必要なパッケージを追加する
  8. 接続先を設定する
    1. .env
    2. 環境変数の二重定義を避ける
    3. .gitignoreへ追加する
  9. Prisma CLIの設定を作る
    1. prisma.config.ts
  10. SchemaへUserモデルを書く
    1. prisma/schema.prisma
    2. 各記述の意味を確認する
    3. Stringは空文字まで禁止するわけではありません
  11. Migrationを作ってDBへ反映する
    1. 何が作られたかを確認する
  12. Next.js用のPrisma Clientを作る
    1. src/lib/prisma.ts
    2. なぜ再利用するのか
  13. 初期データを登録する
    1. prisma/seed.ts
    2. なぜcreate()だけにしないのか
    3. なぜSeedからlib/prisma.tsを読み込まないのか
  14. ユーザー取得サービスを作る
    1. src/services/user.service.ts
  15. Next.jsのページに表示する
    1. src/app/users/page.tsx
    2. 開発サーバーを起動する
  16. 接続できたかを正しく確認する
    1. 実行順を振り返る
  17. Schemaを変更してMigrationを体験する
    1. Userモデルへ任意項目を追加する
    2. なぜ最初は任意項目にするのか
    3. generateだけでは列は追加されません
  18. ORMとSQLの対応を復習する
    1. 追加の形
    2. 更新の形
    3. 削除の形
  19. RelationとForeign Keyのつながり
  20. Migrationで特に注意すること
    1. 開発用コマンドと本番用コマンドを区別する
    2. リセットの案内を安易に承認しない
    3. 適用済みの履歴を書き換えない
  21. セキュリティと公開環境の注意点
    1. ORMは入力検証や認可の代わりではありません
    2. Prisma Clientをブラウザーから直接使わない
    3. ローカルSQLiteをそのまま全公開環境へ持ち込まない
  22. よくあるつまずきと確認方法
  23. 自力で取り組む練習問題
    1. ユーザーを1人追加する
    2. プロフィール欄を取得する
    3. 取得件数と並び順を変える
    4. ファイルの役割を説明する
  24. Day 53のチェックリスト
  25. まとめ

Day 53:ORM ― Schema・Migration・Modelを理解して、Next.jsからデータベースへ接続する

Day 53では、これまで学んだデータベースとSQLを、Next.jsのコードにつなげます。今回はORMとしてPrisma ORMを使い、ローカルのSQLiteへユーザーを保存し、Next.jsのページに表示します。

大切なのは、コマンドを実行して接続できることだけではありません。「データの設計」「データベースへの反映」「操作用コードの生成」「画面からの利用」を区別することです。この流れが分かると、今後の登録・編集・削除機能を理解しやすくなります。

今回のゴールと使用環境

完成後は、次の流れが動きます。

ブラウザーで /users を開く
    ↓
Next.jsのServer Componentが実行される
    ↓
ユーザー取得サービスを呼び出す
    ↓
Prisma Clientがデータベースへ問い合わせる
    ↓
SQLiteからユーザーを取得する
    ↓
名前を画面へ表示する

今回の実装範囲は、次のとおりです。

項目今回行うこと
ORMPrisma ORMを導入します
Schemaユーザーの構造を定義します
ModelUserモデルを作ります
Migrationユーザーテーブルを作ります
初期データ学習用ユーザーを登録します
Next.jsとの接続Server Componentからユーザーを取得します
画面/usersにユーザー名を表示します

登録フォームや編集フォームは、今回はまだ作りません。まずは、Next.jsからデータベースを読み取れるところまでを完成させます。

Prismaのバージョンをそろえる

この記事の実装は、Prisma ORM 7.10.0に固定します。Next.jsはApp Router、TypeScript、srcディレクトリを使用します。

Prismaはメジャーバージョンによって、設定方法やクライアントの作成方法が変わります。今回はPrisma 7の方式にそろえ、異なるバージョンの記事にあるコードを混ぜないようにします。Prisma 7でデータベースへ直接接続する場合は、対応するドライバーアダプターを使います。(🔗 docs.prisma.io)

実行環境は、学習用のローカルPCにあるNode.js 24系を想定します。Prisma 7のNode.js要件を満たす、更新済みの環境を使ってください。(🔗 docs.prisma.io)

ORMとは何か

ORMは、Object-Relational Mappingの略です。 プログラム側のデータ構造と、リレーショナルデータベースのテーブルを対応付けて扱うための仕組みです。

Prismaでは、モデルを定義し、そのモデルに対応したクライアントを生成して、TypeScriptからデータベースを操作します。(🔗 prisma.io)

SQLで書く場合と比較する

Day 52では、ユーザー一覧を次のようなSQLで取得しました。

-- IDの小さい順に、ユーザーのIDと名前を取得します
SELECT id, name
FROM users
ORDER BY id ASC;
SQL

Prismaでは、対応する操作を次のように表現できます。

// Userモデルに対応するユーザーを取得します
const users = await prisma.user.findMany({
  // 必要な項目だけ取得します
  select: {
    id: true,
    name: true,
  },
  // IDの小さい順に並べます
  orderBy: {
    id: "asc",
  },
});
TypeScript

Prisma Clientは、モデルに応じた問い合わせ用のAPIと型を提供します。findMany()などを通じて、TypeScriptからデータを操作できます。(🔗 prisma.io)

ORMはデータベースの代わりではありません

今回の役割を分けると、次のようになります。

要素役割
Next.jsページやサーバー側の処理を実行します
Prisma ORMモデル・問い合わせ・変更履歴などを扱います
ドライバーアダプターPrisma ClientとDBドライバーをつなぎます
SQLite実際のデータを保存・管理します

Prismaを導入しても、データの保存先がPrismaの設定ファイルになるわけではありません。今回のデータ本体は、SQLiteのデータベースファイルへ保存します。SQLite接続には@prisma/adapter-better-sqlite3を使います。(🔗 prisma.io)

ORMを使ってもSQLの知識は必要です

ORMを使うと、よく使う操作をTypeScriptで表現しやすくなります。

ただし、次の判断は引き続き必要です。

  • どの行を取得・更新・削除するか。
  • 必要な列だけを取得しているか。
  • 何件のデータを扱うか。
  • 一意制約や外部キーをどう定義するか。
  • 複数の変更を、ひとまとまりで確定する必要があるか。

SQLを忘れるためにORMを使うのではなく、SQLとデータベースの理解を土台に、アプリ側の操作を整理するために使うと考えます。

Schema・Model・Migrationの違い

今回の3つの重要語を、先に整理します。

用語今回の意味例
Schemaデータ構造などを記述した設計schema.prisma
Modelユーザーなど、扱う対象の定義model User
MigrationDB構造の変更を適用・記録する仕組みusersテーブルの作成

Prisma 7では、schema.prisma内のmodelでデータモデルを定義し、Prisma Migrateでデータベースへ反映できます。(🔗 prisma.io)

Schemaは「データ構造の設計」です

今回のPrismaスキーマには、次のような内容を書きます。

  • SQLiteを使うこと。
  • Prisma Clientをどこへ生成するか。
  • ユーザーが持つ項目。
  • 主キーや一意制約。
  • 項目が必須か、省略可能か。

ただし、ファイルへ設計を書いただけでは、データベースのテーブルは変わりません。

Modelは「扱う対象の定義」です

ブログであればUser、Post、Commentなどがモデルの候補です。

今回は、ユーザー1件が持つデータをUserモデルとして定義します。

Prismaのモデルは、必ずしも自分で書くTypeScriptのクラスではありません。Prismaスキーマのmodelブロックとして定義します。(🔗 prisma.io)

Migrationは「構造変更の履歴」です

最初にユーザーテーブルを作り、その後プロフィール欄を追加する場合を考えます。

最初の変更
    usersテーブルを作る

次の変更
    usersテーブルにbio列を追加する

このような構造の変化を、順番に適用できる変更履歴として管理します。

Prisma 7の開発環境では、prisma migrate devで変更を生成・適用します。このコマンドは開発用であり、本番環境へそのまま使うものではありません。(🔗 prisma.io)

設計・反映・生成を混同しない

今回、特に大切なのが次の違いです。

作業変更する対象
schema.prismaを編集する設計ファイル
prisma migrate devを実行するDB構造とマイグレーション履歴
prisma generateを実行するモデルに対応するクライアントコード・型
prisma db seedを実行する初期データ

prisma generateは、テーブルを作るコマンドではありません。

今回は、設計の反映とクライアント生成を、別々のコマンドとして明示的に実行します。Prisma 7のSQLiteクイックスタートでも、マイグレーション後にクライアント生成を実行する流れが案内されています。(🔗 prisma.io)

実装前にファイル構成を確認する

今回作る主要なファイルは、次のとおりです。

day53-orm/
├── prisma/
│   ├── schema.prisma
│   ├── seed.ts
│   └── migrations/          ← コマンドで生成されます
├── src/
│   ├── app/
│   │   ├── users/
│   │   │   └── page.tsx
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── generated/
│   │   └── prisma/          ← コマンドで生成されます
│   ├── lib/
│   │   └── prisma.ts
│   └── services/
│       └── user.service.ts
├── .env
├── .gitignore
├── dev.db                  ← マイグレーションで作られます
├── prisma.config.ts
├── package.json
└── package-lock.json

今回は新しいデータベースを作ります。Day 51やDay 52で作ったDBファイルを、そのまま接続先へ指定しないでください。

既存DBへORMを導入する場合は、既存テーブルの取り込みや変更履歴の基準作成などを別途検討します。今回の「空のDBを設計から作る手順」とは分けて考えます。(🔗 prisma.io)

Next.jsプロジェクトを準備する

新規作成する場合は、次のコマンドを実行します。

# Next.jsのプロジェクトを作成します
npx create-next-app@latest day53-orm

# 作成したプロジェクトへ移動します
cd day53-orm

# Node.jsのバージョンを確認します
node -v

TypeScript、App Router、srcディレクトリを使用する構成にします。画面の装飾は最小限なので、Tailwind CSSの有無は今回の接続処理に影響しません。

以降のコマンドは、package.jsonがあるプロジェクトルートで実行します。

必要なパッケージを追加する

# CLIと実行補助のパッケージを追加します
npm install -D --save-exact prisma@7.10.0 tsx @types/better-sqlite3

# クライアント、SQLite用アダプター、環境変数読み込みを追加します
npm install --save-exact @prisma/client@7.10.0 @prisma/adapter-better-sqlite3@7.10.0 dotenv server-only

# ESMを使用するプロジェクトとして設定します
npm pkg set type=module

# Prisma関連のバージョンを確認します
npx prisma -v

Prisma CLI、Prisma Client、アダプターを同じバージョンへそろえています。Prisma 7では、ESMの設定とアダプターを使った接続方法を前提に進めます。(🔗 prisma.io)

今回は設定内容を理解するため、prisma initに任せず、必要なファイルを手動で作ります。

接続先を設定する

.env

プロジェクトルートに作成します。

# 今回はプロジェクトルートのSQLiteファイルを使います
DATABASE_URL="file:./dev.db"

SQLiteなので、ユーザー名やパスワードは指定していません。

ただし、将来PostgreSQLなどへ変更すると、接続URLに認証情報が含まれる場合があります。接続設定は、公開する値ではないものとして管理します。

環境変数の二重定義を避ける

今回、DATABASE_URLはルートの.envだけで管理します。

以前の学習で.env.localやシェル側へ同名の変数を設定している場合は、内容を確認します。CLIとNext.jsが別々の接続先を見ていると、「登録したのに画面へ出ない」といった混乱が起こります。

Prisma CLI側では、次に作る設定ファイルでdotenv/configを読み込みます。Prisma Configで環境変数を利用する場合、読み込みも明示する必要があります。(🔗 prisma.io)

.gitignoreへ追加する

既存の内容を消さず、必要な行を追加します。

# 環境変数を公開しません
.env
.env.*

# 認証情報を含めないサンプルは管理できます
!.env.example

# ローカルDBと付随ファイルを管理対象から外します
/dev.db
/dev.db-*

# 生成物はgenerateで作り直します
/src/generated/prisma/

一方、prisma/schema.prismaとprisma/migrationsは、通常コードと一緒に管理する対象です。データ本体と、構造の変更履歴を区別します。(🔗 prisma.io)

Prisma CLIの設定を作る

prisma.config.ts

// Prisma CLIから.envを読み込めるようにします
import "dotenv/config";

// Prisma 7の設定用関数を読み込みます
import { defineConfig, env } from "prisma/config";

// CLIが使うスキーマ、変更履歴、接続先を定義します
export default defineConfig({
  schema: "prisma/schema.prisma",

  migrations: {
    path: "prisma/migrations",
    // 初期データ登録時に実行するコマンドです
    seed: "tsx prisma/seed.ts",
  },

  datasource: {
    url: env("DATABASE_URL"),
  },
});
TypeScript

このファイルは、Prisma CLIがマイグレーションや初期データ登録などを行うための設定です。

この設定だけで、Next.jsの実行時にPrisma Clientが自動作成されるわけではありません。 実行時の接続用コードは、後ほど別に作ります。(🔗 prisma.io)

SchemaへUserモデルを書く

prisma/schema.prisma

// TypeScriptから利用するクライアントを生成します
generator client {
  provider = "prisma-client"

  // このschema.prismaから見た相対パスです
  output = "../src/generated/prisma"
}

// 今回使うデータベースの種類です
datasource db {
  provider = "sqlite"
}

// ユーザー1件の構造を定義します
model User {
  // 整数の主キーを、自動採番で作ります
  id Int @id @default(autoincrement())

  // 名前は必須です
  name String

  // メールアドレスは必須で、重複を禁止します
  email String @unique

  // 作成日時を保存します
  createdAt DateTime @default(now()) @map("created_at")

  // 実際のテーブル名をusersにします
  @@map("users")
}
Prisma

各記述の意味を確認する

記述意味
model UserUserモデルを定義します
Int整数を扱います
String文字列を扱います
DateTime日時を扱います
@id主キーにします
@default(autoincrement())整数IDを自動採番します
@unique重複を禁止します
@default(now())作成時の既定値として現在日時を使います
@map("created_at")DB列名とモデルの項目名を対応付けます
@@map("users")DBテーブル名とモデル名を対応付けます

Prismaの@mapと@@mapを使うと、TypeScript側で使いやすい名前と、DB側の名前を分けられます。(🔗 prisma.io)

今回は、次の対応になります。

Prisma側                 データベース側

User          →          usersテーブル
createdAt     →          created_at列

Stringは空文字まで禁止するわけではありません

name Stringは、モデル上で必須の文字列です。

しかし、「1〜50文字」「空白だけは不可」などの業務ルールまで、この記述だけで定義したわけではありません。

登録フォームを作る段階では、文字数や内容をサーバー側で検証します。必要に応じて、DB側の制約も設計します。

Migrationを作ってDBへ反映する

設計ができたら、データベースへ反映します。

# スキーマの書式を整えます
npx prisma format

# スキーマの定義を確認します
npx prisma validate

# 初回の変更履歴を作り、開発用DBへ適用します
npx prisma migrate dev --name init

# モデルに対応したPrisma Clientを生成します
npx prisma generate

これにより、DBファイル、マイグレーションファイル、生成クライアントが用意されます。Prisma 7のSQLite向け手順も、モデル定義、マイグレーション、クライアント生成という流れです。(🔗 prisma.io)

何が作られたかを確認する

dev.db
    実際のデータを保存するファイル

prisma/migrations/
    テーブル作成などの変更履歴

src/generated/prisma/
    モデルに対応した操作用コードと型

マイグレーションの中には、migration.sqlが作られます。内容を開き、Day 52で学んだCREATE TABLEなどとつながっていることを確認します。

生成されたSQLを、実行せずに一度読む習慣を付けると、ORMが何をしているかを理解しやすくなります。

Next.js用のPrisma Clientを作る

次に、アプリから使う接続用コードを作ります。

src/lib/prisma.ts

// Client Componentからの誤った読み込みを防ぎます
import "server-only";

// SQLite用のアダプターを読み込みます
import { PrismaBetterSqlite3 } from "@prisma/adapter-better-sqlite3";

// 自分のスキーマから生成したクライアントを読み込みます
import { PrismaClient } from "../generated/prisma/client";

// 開発時に接続用インスタンスを再利用するための型です
const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

// 必要になったときだけクライアントを作ります
function createPrismaClient() {
  const url = process.env.DATABASE_URL;

  if (!url) {
    throw new Error("DATABASE_URLが設定されていません。");
  }

  const adapter = new PrismaBetterSqlite3({ url });

  return new PrismaClient({ adapter });
}

// 開発時は、既存のインスタンスがあれば再利用します
export const prisma =
  globalForPrisma.prisma ?? createPrismaClient();

if (process.env.NODE_ENV !== "production") {
  globalForPrisma.prisma = prisma;
}
TypeScript

なぜ再利用するのか

Next.jsの開発中は、ファイル変更に応じてモジュールが再評価されます。

そのたびにPrisma Clientを増やさないよう、開発時にはglobalThisへ保存して再利用しています。PrismaのNext.js向けガイドでも、開発中の再読み込みを考慮した同様の構成が案内されています。(🔗 docs.prisma.io)

ただし、これは世界中のすべてのサーバーで、接続が必ずひとつになる仕組みではありません。 実行プロセスや公開環境が分かれれば、それぞれのインスタンスがあります。

また、ページを表示するたびに$disconnect()する構成にはしません。接続を再利用するアプリと、実行後に終了する初期データ用スクリプトは、扱いを分けます。

初期データを登録する

DBへ接続できても、まだユーザーは0件です。

今回は、初期データを登録する**Seed(シード)**を作ります。

prisma/seed.ts

// 通常のスクリプトから.envを読み込みます
import "dotenv/config";

// SQLite用のアダプターと生成クライアントを読み込みます
import { PrismaBetterSqlite3 } from "@prisma/adapter-better-sqlite3";
import { PrismaClient } from "../src/generated/prisma/client";

async function main() {
  const url = process.env.DATABASE_URL;

  if (!url) {
    throw new Error("DATABASE_URLが設定されていません。");
  }

  const adapter = new PrismaBetterSqlite3({ url });
  const prisma = new PrismaClient({ adapter });

  try {
    // メールアドレスが既存なら、そのユーザーを使います
    await prisma.user.upsert({
      where: {
        email: "aoi@example.com",
      },
      update: {},
      create: {
        name: "葵",
        email: "aoi@example.com",
      },
    });

    await prisma.user.upsert({
      where: {
        email: "ren@example.com",
      },
      update: {},
      create: {
        name: "蓮",
        email: "ren@example.com",
      },
    });

    // 確認に必要な項目だけ取得します
    const users = await prisma.user.findMany({
      select: {
        id: true,
        name: true,
      },
      orderBy: {
        id: "asc",
      },
    });

    console.table(users);
  } finally {
    // 短時間で終了するスクリプトなので、最後に切断します
    await prisma.$disconnect();
  }
}

// 失敗した場合は、実行元へ失敗を伝えます
main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
TypeScript

初期データを登録します。

# prisma.config.tsで指定したSeedを実行します
npx prisma db seed

db seedは、設定された初期データ登録用コマンドを実行します。今回の設定では、tsx prisma/seed.tsが動きます。(🔗 prisma.io)

なぜcreate()だけにしないのか

create()で同じメールアドレスを何度も登録すると、今回の一意制約に違反します。

今回はupsert()を使い、「メールアドレスがあれば既存データを使い、なければ作る」という動作にしています。これにより、同じSeedを再実行しても、同じメールアドレスのユーザーを追加し続けない構成になります。(🔗 prisma.io)

なお、update: {}なので、既存ユーザーの名前を初期値へ戻す処理は行いません。

なぜSeedからlib/prisma.tsを読み込まないのか

今回のlib/prisma.tsには、Next.jsでのサーバー専用境界を示すserver-onlyがあります。

Seedは通常のNode.jsスクリプトとして実行するため、ここでは専用のPrisma Clientを作り、終了時に切断する形に分けています。

ユーザー取得サービスを作る

Day 49で学んだ設計に合わせ、ページへ直接問い合わせを書かず、取得サービスを用意します。

src/services/user.service.ts

// サーバー側だけで利用する処理です
import "server-only";

// 共通のPrisma Clientを読み込みます
import { prisma } from "../lib/prisma";

// 今回の学習画面で表示するユーザー一覧を取得します
export async function getUsers() {
  return prisma.user.findMany({
    // メールアドレスは今回の画面へ返しません
    select: {
      id: true,
      name: true,
    },

    // 並び順を明示します
    orderBy: {
      id: "asc",
    },

    // 今回は最大20件に制限します
    take: 20,
  });
}
TypeScript

今回はPrismaが型を生成するため、DBと同じ形のUser型を手書きで重複定義しません。

また、selectでIDと名前だけを取得しています。DBにメールアドレスがあることと、画面へメールアドレスを渡すことは別に考えます。

Next.jsのページに表示する

src/app/users/page.tsx

// ページのMetadata型を読み込みます
import type { Metadata } from "next";

// データ取得サービスを読み込みます
import { getUsers } from "../../services/user.service";

// ローカルSQLiteのドライバーをNode.js環境で使います
export const runtime = "nodejs";

// 今回は、アクセス時に最新のDB内容を取得します
// cacheComponentsを有効にしていない構成を前提にします
export const dynamic = "force-dynamic";

// ページのMetadataです
export const metadata: Metadata = {
  title: "ユーザー一覧",
  description: "データベース接続を確認する学習用ページです。",
};

// Server ComponentからDBを読み取ります
export default async function UsersPage() {
  const users = await getUsers();

  return (
    <section>
      <h1>ユーザー一覧</h1>

      <p>SQLiteから取得したユーザーを表示しています。</p>

      {users.length === 0 ? (
        <p>ユーザーはまだ登録されていません。</p>
      ) : (
        <ul>
          {users.map((user) => (
            <li key={user.id}>
              ID:{user.id} / 名前:{user.name}
            </li>
          ))}
        </ul>
      )}
    </section>
  );
}
TSX

ページには"use client"を書いていません。App Routerのページは既定でServer Componentであり、サーバー側からデータベースへアクセスできます。server-onlyは、サーバー専用モジュールの誤ったClient Componentへの取り込みを検出するために使えます。(🔗 nextjs.org)

このページは、認証付きの管理画面ではなく、ローカルでダミーデータを使う接続確認用ページです。

開発サーバーを起動する

# 生成と初期データ登録が終わってから起動します
npm run dev

次のURLを開きます。

http://localhost:3000/users

空のDBから順番に実行した場合は、葵さんと蓮さんが表示されます。

IDの値自体は、既存データや過去の操作によって変わる可能性があります。大切なのは、Seedで登録したデータをDBから取得できていることです。

接続できたかを正しく確認する

表示されたら、次の操作を試します。

  • ブラウザーを再読み込みします。
  • 開発サーバーを停止します。
  • 開発サーバーを再起動します。
  • もう一度/usersを開きます。

ユーザーが残っていれば、今回の構成では、ソースコード内の配列ではなく、DBファイルへ保存したデータを読み取れています。

実行順を振り返る

schema.prismaを作る
    ↓
migrate devでDB構造を反映する
    ↓
generateで操作用クライアントを生成する
    ↓
db seedで初期データを登録する
    ↓
Next.jsからfindManyで取得する

どこかで止まった場合は、すべてをやり直すのではなく、この流れのどこまで成功しているかを確認します。

Schemaを変更してMigrationを体験する

接続できたら、プロフィール欄を追加します。

Userモデルへ任意項目を追加する

prisma/schema.prismaのUserモデルを、次のように変更します。

// プロフィール欄を追加したユーザーモデルです
model User {
  id        Int      @id @default(autoincrement())
  name      String
  email     String   @unique
  createdAt DateTime @default(now()) @map("created_at")

  // ?があるので、未設定を許可します
  bio String?

  @@map("users")
}
Prisma

反映します。

# プロフィール列を追加する変更履歴を作成・適用します
npx prisma migrate dev --name add_user_bio

# 新しい項目をクライアントの型へ反映します
npx prisma generate

String?は、値が未設定であることを許すフィールドです。今回のように既存ユーザーがいる場合でも、全員のプロフィールをすぐに用意せず追加できます。(🔗 prisma.io)

なぜ最初は任意項目にするのか

既存のユーザーがいる状態で、既定値のない必須項目を追加すると、既存行へ何を入れるべきかが問題になります。

実際の変更では、次のように段階を分けることも考えます。

  • まず任意項目として追加します。
  • 既存データへ適切な値を登録します。
  • 要件上必要なら、その後に必須へ変更します。

Migrationは、ファイルの変更だけではなく、既にあるデータをどう扱うかまで考える作業です。

generateだけでは列は追加されません

bioをスキーマへ追加し、generateだけを実行すると、クライアント側は新しい構造を知っていても、DB側には列がない状態になり得ます。

設計ファイル、DB構造、生成クライアントの3つが一致しているかを意識します。

ORMとSQLの対応を復習する

今後使う主な操作を、Day 52のSQLと対応させます。

SQLの操作Prisma Clientの代表例用途
SELECTfindMany()複数件取得
一意な条件で取得findUnique()IDや一意なメールで取得
INSERTcreate()1件登録
UPDATEupdate()一意な対象を更新
DELETEdelete()一意な対象を削除

Prisma Clientでは、モデルに対してこれらの問い合わせや変更操作を行えます。(🔗 prisma.io)

追加の形

// サーバー側の登録処理で使う基本形です
const user = await prisma.user.create({
  data: {
    name: "結衣",
    email: "yui@example.com",
  },
});
TypeScript

更新の形

// IDで対象を特定して名前を変更します
const user = await prisma.user.update({
  where: {
    id: userId,
  },
  data: {
    name: newName,
  },
});
TypeScript

削除の形

// IDで対象を特定して削除します
const user = await prisma.user.delete({
  where: {
    id: userId,
  },
});
TypeScript

ここでのuserIdやnewNameは、事前に検証された値を想定しています。

また、登録・更新・削除を、ページを表示するためのレンダリング処理へ無条件に書かないようにします。今後、明示的な保存操作を受け付けるサーバー側の入口で、入力確認と権限確認を行ってから呼び出します。

RelationとForeign Keyのつながり

Day 51では、記事のuser_idから投稿者を参照しました。

Prismaでは、たとえば次のように表現できます。これは関係を理解するための追加例であり、今回の実習へ必ず追加する必要はありません。

// 投稿者を表すモデルです
model User {
  id    Int    @id @default(autoincrement())
  name  String
  email String @unique

  // Prisma側で、関連する記事を扱うためのフィールドです
  posts Post[]

  @@map("users")
}

// 記事を表すモデルです
model Post {
  id    Int    @id @default(autoincrement())
  title String

  // 実際のDBに保存する外部キーの列です
  userId Int @map("user_id")

  // userIdからUser.idを参照します
  user User @relation(
    fields: [userId],
    references: [id],
    onDelete: Restrict
  )

  @@map("posts")
}
Prisma

ここでは、次の違いが重要です。

  • userIdは、DBに保存される外部キーの列です。
  • userやpostsは、Prisma側で関係を扱うフィールドです。
  • posts Post[]と書いても、usersテーブルへ記事配列の列が作られるわけではありません。

Prismaのリレーションフィールドと、DBに存在する外部キー列は、区別して理解します。(🔗 prisma.io)

Migrationで特に注意すること

開発用コマンドと本番用コマンドを区別する

今回のmigrate devは、開発用DBの変更に使っています。

Prisma 7では、本番環境へ用意済みの変更を適用するためにmigrate deployを使う運用があります。開発用の変更作成と、本番への適用を分けます。(🔗 prisma.io)

リセットの案内を安易に承認しない

開発中、スキーマや変更履歴の不一致によって、DBのリセットを求められる場合があります。

その際は、接続先が本当に学習用か、失ってよいデータだけかを確認します。問題が出たからという理由で、DBやMigration履歴を削除して進めないようにします。(🔗 prisma.io)

適用済みの履歴を書き換えない

変更済みの構造をさらに変えたい場合は、新しいMigrationを追加することを基本にします。

過去の変更履歴と実際のDBが食い違うと、ほかの環境で同じ構造を再現しにくくなります。(🔗 prisma.io)

セキュリティと公開環境の注意点

ORMは入力検証や認可の代わりではありません

型の補完があることと、利用者がその操作を実行してよいことは別です。

  • メールアドレスの形式は適切ですか。
  • 名前は長すぎませんか。
  • 本人または管理者として操作していますか。
  • 更新してはいけない項目まで受け取っていませんか。

ORMを使っても、これらの確認はサーバー側の責務として残ります。

Prisma Clientをブラウザーから直接使わない

今回のDB接続は、Server Componentとサーバー専用サービスから行います。

server-onlyは誤ったClient Componentへのimportを検出する助けになりますが、ログインや権限確認を自動実装する機能ではありません。(🔗 nextjs.org)

データを取得する権限と、表示する項目を分ける

今回の一覧では、selectでIDと名前だけを返しました。

将来、住所や管理用フラグなどが増えても、DBから取得できる情報をそのまますべて画面へ渡す構成にはしません。

接続情報は公開しない

接続URLをソースコードへ直接埋め込んだり、ブラウザーへ送る設定値として扱ったりしないようにします。

公開前の最終確認

今回の/usersは、ダミーデータによるローカル実習用です。実際の利用者情報を扱う場合は、一覧を誰が閲覧できるかまで設計してから公開します。

ローカルSQLiteをそのまま全公開環境へ持ち込まない

今回のdev.dbは、ローカルPCのファイルです。

公開先で同じ構成を使えるかは、永続的に書き込める保存領域があるか、複数の実行環境で共有できるか、バックアップをどうするかによって変わります。

ローカルで接続できたことと、公開先の保存設計が完成したことは別として考えます。

よくあるつまずきと確認方法

症状確認すること対応の方向
生成クライアントをimportできないprisma generateを実行したか生成先とimport先を一致させます
usersテーブルがないMigrationの適用先接続先とmigrate devの結果を確認します
Seedしたのに0件になるCLIとNext.jsの接続URL環境変数の二重定義を確認します
メール重複エラーになる@uniqueと登録処理新規登録か既存更新かを整理します
bioが型に現れないクライアント生成スキーマ変更後に再生成します
列がないというエラーになるDBへの反映generateだけで済ませていないか確認します
アダプターを要求されるPrismaのバージョンPrisma 7の接続方式へ統一します
SQLiteドライバーの導入に失敗するNode.jsとOS環境バージョンとインストールエラーを確認します
Client Componentでimportエラーになる依存関係DB処理をサーバー側へ戻します

SQLiteアダプターはネイティブなドライバーを使うため、Node.jsやOS環境によって導入時の確認が必要になる場合があります。パッケージ導入の失敗と、モデルやSQLの問題は分けて調べます。(🔗 prisma.io)

自力で取り組む練習問題

ユーザーを1人追加する

Seedへ、ダミーユーザーをもう1人追加します。

  • 重複しないメールアドレスを使います。
  • Seedを再実行します。
  • /usersを再読み込みします。
  • アプリを再起動しても残ることを確認します。

プロフィール欄を取得する

bioのMigrationを適用した後、取得サービスのselectへbio: trueを追加します。

画面では、未設定の場合に「プロフィール未登録」と表示します。

取得件数と並び順を変える

takeを変更し、表示件数の上限がどう変わるかを確認します。

その後、orderByを変更して、並び順と件数制限が別々の指定であることを確かめます。

ファイルの役割を説明する

次の問いへ、コードを見ながら答えます。

  • schema.prismaには何を定義していますか。
  • prisma.config.tsは、どの処理の設定ですか。
  • src/lib/prisma.tsは何を作っていますか。
  • なぜSeedはページ表示とは別に実行しますか。
  • なぜ画面表示にメールアドレスを含めていませんか。

Day 53のチェックリスト

  • ORMとデータベースの違いを説明できます。
  • Schema、Model、Migrationを区別できます。
  • Userモデルとusersテーブルの対応を説明できます。
  • Migrationの適用とClientの生成が別作業だと理解しています。
  • Seedで初期データを登録できます。
  • Next.jsのServer ComponentからDBを取得できます。
  • 必要な項目だけをselectできます。
  • スキーマ変更後の反映手順を説明できます。
  • ORMだけでは入力検証や認可は完成しないと理解しています。
  • ローカル接続と公開環境の保存設計を区別できます。

まとめ

Day 53では、Prisma ORMを使い、Next.jsからSQLiteへ接続しました。

今回の中心は、Schemaで設計し、MigrationでDBへ反映し、生成したPrisma Clientから操作するという流れです。さらに、初期データの登録と、画面からの取得を分けて実装しました。

ORMを使うと、データベース操作をTypeScriptのコードとして扱いやすくなります。ただし、対象の絞り込み、制約、入力検証、操作権限など、これまで学んだ考え方は引き続き必要です。まずは今回の接続を土台にし、次の段階で登録・編集・削除の画面へ発展させます。

タイトルとURLをコピーしました