Skip to content
Code Blue プログラミング学習ノート
Javascript/Next.js

Next.jsでPrisma ORMをセットアップ

2025年9月24日 /

はじめに

Next.jsプロジェクトにPrisma ORMを導入し、データベースを利用するための初期セットアップを行います。Prismaのインストールから初期化、データベース接続の設定、スキーマファイルの作成、Prisma Clientの生成までの一連の流れを順番に解説します。開発環境を正しく構築することで、以降の章でCRUD操作やデータベース連携をスムーズに実装できるようになります。

Prisma ORMとは？

Prismaは、データベースを簡単に操作できる現代的なORM（Object-Relational Mapping）ツールです。TypeScriptと相性が良く、Next.jsアプリケーションとの統合もスムーズに行えます。

Prismaは、TypeScriptと高い親和性を持つORMであり、型安全にデータベースを操作できるのが大きな特徴です。

シンプルなスキーマファイルでデータモデルを定義できるほか、マイグレーション機能によってデータベース構造の変更も簡単に管理できます。また、自動補完による快適な開発環境を提供し、PostgreSQL、MySQL、SQLite、SQL Serverなど複数のデータベースに対応しているため、さまざまなWebアプリケーション開発で活用できます。

前提条件

前提条件となる開発環境を準備しておきましょう。Node.js（v14以上）がインストールされており、npmまたはyarnが利用できることを確認してください。また、Next.jsプロジェクトが作成済みであることに加え、MySQLやPostgreSQLなどのデータベースサーバーが利用できる環境を用意しておく必要があります。これらの準備が整っていれば、Prismaを利用したデータベース連携をスムーズに進められます。

Prismaのインストール

まず、Next.jsプロジェクトにPrismaをインストールします。

npm install prisma @prisma/client

またはyarnを使用する場合は以下のコマンドになります。

yarn add prisma @prisma/client

@prisma/clientはPrismaのクライアントライブラリで、アプリケーションからデータベース操作を行うために使用します。

Prismaの初期化

次に、Prismaを初期化して基本的な設定ファイルを作成します。

npx prisma init

このコマンドを実行すると、プロジェクトルートにprismaディレクトリが作成され、以下のファイルが生成されます：

  • prisma/schema.prisma – Prismaの主要な設定ファイル
  • .env – 環境変数ファイル（既に存在する場合は追記されます）

データベース接続の設定

.envファイルを開き、データベース接続URLを設定します。MySQLを使用する場合の例は以下の通りです。

DATABASE_URL="mysql://ユーザー名:パスワード@localhost:3306/データベース名"

PostgreSQLの場合は以下の通りです。

DATABASE_URL="postgresql://ユーザー名:パスワード@localhost:5432/データベース名?schema=public"

SQLiteの場合は以下の通りです。

DATABASE_URL="file:./dev.db"

接続URLの形式は使用するデータベースによって異なります。SSL接続が必要な場合や特別なオプションがある場合は、接続URLに追加パラメータを指定できます。

Prismaスキーマの設定

prisma/schema.prismaファイルを開き、データベースプロバイダーを設定します。

datasource db {
  provider = "mysql" // 使用するデータベース (mysql, postgresql, sqlite, sqlserverなど)
  url      = env("DATABASE_URL") // .envファイルから接続URLを読み込む
}

generator client {
  provider = "prisma-client-js"
}

この設定により、Prismaは指定されたデータベースを使用するようになります。

データモデルの定義

Prismaの強力な機能の1つが、直感的なデータモデリングです。schema.prismaファイルにモデルを定義していきます。例えば、ブログアプリケーションを作成する場合は次のように、PrismaのスキーマファイルでUserモデルとPostモデルを定義しています。

各モデルでは、フィールドの型や主キー、一意制約、デフォルト値を設定しています。また、UserとPostはリレーションで関連付けられており、1人のユーザーが複数の投稿を持つ「1対多」の関係を表現しています。これらの定義をもとに、Prismaはデータベースのテーブルや型安全なPrisma Clientを生成します。

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

このモデル定義では：

  • UserとPostという2つのテーブル（モデル）を定義
  • 各フィールドの型を指定（String, Int, Booleanなど）
  • リレーションシップを定義（UserとPostの1対多関係）
  • デフォルト値や制約を追加（@id, @unique, @defaultなど）

データベースマイグレーション

モデルを定義したら、データベースに実際のテーブルを作成するためにマイグレーションを実行します。

npx prisma migrate dev --name init

このコマンドを実行すると、現在のスキーマをもとに新しいマイグレーションファイルが作成されます。続いて、その変更内容がデータベースへ適用され、テーブルやカラムが更新されます。最後に、最新のスキーマに対応したPrisma Clientが自動生成されるため、すぐにアプリケーションから型安全にデータベースを操作できるようになります。

マイグレーションが成功すると、prisma/migrationsディレクトリにマイグレーションファイルが作成されます。このファイルはデータベーススキーマの変更履歴として機能します。

Prisma Clientの生成

Prisma Clientは、アプリケーションからデータベース操作を行うための型安全なクライアントです。通常、マイグレーションを実行すると自動的に生成されますが、必要に応じて手動で生成することもできます。

npx prisma generate

生成されたクライアントはnode_modules/.prisma/clientに保存され、アプリケーションからインポートして使用できます。

Next.jsでPrisma Clientを使用する設定

Next.jsでPrisma Clientを使用する際のベストプラクティスは、クライアントのインスタンスをシングルトンとして管理することです。これにより、データベース接続の過剰な作成を防ぎます。

lib/prisma.tsという新しいファイルを作成し、以下のコードを追加します。

import { PrismaClient } from '@prisma/client'

declare global {
  var prisma: PrismaClient | undefined
}

const prisma = globalThis.prisma || new PrismaClient()

if (process.env.NODE_ENV !== 'production') globalThis.prisma = prisma

export default prisma

この設定では、開発環境でホットリロードが発生しても、既存のPrisma Clientインスタンスを再利用するため、不要なインスタンスの生成を防ぐことができます。

一方、プロダクション環境ではリクエストごとに新しいインスタンスが作成され、安全かつ安定した動作を実現します。また、TypeScriptの型定義を拡張することで、グローバル変数として保持したPrisma Clientを型安全に利用できるようになります。

Prisma Studioの使用（オプション）

Prismaには、データベースの内容を可視化・操作できるGUIツール「Prisma Studio」が付属しています。起動するには以下のコマンドを実行して起動します。

npx prisma studio

このコマンドを実行すると、ブラウザでhttp://localhost:5555が開き、データベースの内容を確認・編集できます。

TypeScript設定の確認

Next.jsでPrismaをスムーズに使用するために、TypeScriptの設定を確認します。tsconfig.jsonに以下を追加することを推奨します。理由としては、strictをtrueにすることで、TypeScriptの厳格な型チェックが有効になります。型の不一致やnull・undefinedの扱いなどを細かく検査するため、実行前に多くのバグを防ぐことができます。

{
  "compilerOptions": {
    "strict": true,
    "skipLibCheck": true
  }
}

また、skipLibCheckをtrueにすると、node_modulesなどに含まれるライブラリの型定義ファイル（.d.ts）のチェックを省略します。これによりコンパイル時間を短縮でき、ライブラリ側の型定義による不要なエラーを回避できます。strictモードを有効にすることで、Prismaの型安全性を最大限に活用できます。

よくあるエラーと解決策

データベース接続エラー

エラーメッセージ

Error: P1001: Can't reach database server at `localhost`:`3306`

解決策

  • データベースサーバーが実行中か確認
  • 接続URLのユーザー名、パスワード、ポートが正しいか確認
  • ファイアウォール設定を確認
  • データベースがリモートの場合は、接続が許可されているか確認

テーブルが存在しないエラー

エラーメッセージ

Error: P2021: The table `User` does not exist in the current database.

解決策

  • マイグレーションが実行されているか確認 (npx prisma migrate dev)
  • データベース名が正しいか確認
  • スキーマ名が正しいか確認（PostgreSQLの場合）

環境変数が見つからないエラー

エラーメッセージ

Error: Environment variable not found: DATABASE_URL

解決策

  • .envファイルがプロジェクトルートにあるか確認
  • .envファイルの変数名が正しいか確認
  • Next.jsで環境変数を使用する場合は、NEXT_PUBLIC_プレフィックスが必要な場合があります（ただし、データベース接続URLはクライアント側で公開しないでください）

パフォーマンス最適化のヒント

接続プーリングの使用

  • データベース接続を再利用するために接続プーリングを設定
  • PostgreSQLの場合、?connection_limit=5のようなパラメータを接続URLに追加

Prisma Clientの拡張

  • よく使用するクエリをカスタムメソッドとして追加
  • ロギングやエラーハンドリングを統一

SELECTの最適化

  • 必要なフィールドのみを選択 (selectオプションを使用)
  • 不要なリレーションの読み込みを避ける

テスト環境の設定

テストを行う場合は、開発環境とは別にテスト専用のデータベースを用意することをおすすめします。.env.testファイルを作成してテスト用データベースの接続情報を設定し、テスト実行時にはその環境変数を読み込むようにします。

これにより、テストデータが開発用データベースへ影響を与えることを防ぎ、安全に自動テストを実行できます。

# package.json
"scripts": {
  "test": "dotenv -e .env.test jest"
}

プロダクション環境へのデプロイ

プロダクション環境にデプロイする際の注意点は以下の事柄があります。

マイグレーションの自動化

  • CI/CDパイプラインでマイグレーションを実行
   npx prisma migrate deploy

Prisma Clientの生成

  • ビルドプロセスにprisma generateを含める

環境変数の保護

  • データベース接続情報を安全に管理
  • シークレットマネージャーや環境変数管理ツールを使用

まとめ

このガイドでは、Next.jsプロジェクトにPrisma ORMをセットアップする方法を詳細に説明しました。Prismaを導入することで、型安全で直感的なデータベース操作が可能になり、開発効率が大幅に向上します。

次のステップとして、Prismaを使った実際のCRUD操作や、Next.js APIルートとの統合について学んでいきましょう。Prismaの豊富な機能を活用すれば、複雑なデータベース操作も簡単に実装できます。