👻

Next.js + Supabase に Prisma を導入する方法

2025/06/06に公開

Next.js + Supabase プロジェクトに Prisma を導入したのですが、導入手順で一部分かりにくいところがあったので、誰かの役に立てればと記事を書くことにしました！
本記事では、既存の Next.js + Supabase プロジェクトに Prisma を導入する手順を、画面キャプチャ付きで詳しく解説します。この記事を読めば、環境変数の設定でつまずきやすいポイントも含めて、スムーズに Prisma を導入できるようになります。

 Prisma とは何かPrisma はデータベースツールキットで、以下の 3 つの特徴があります。

型安全なデータベースアクセス - TypeScript との親和性が高く、コンパイル時にエラーを検出

直感的なスキーマ定義 - 宣言的なスキーマファイルでデータベース構造を管理

自動生成されるクライアント - スキーマから自動でクライアントコードを生成
特に TypeScript ベースのプロジェクトでは、型安全性の恩恵を最大限に活用できます。

 前提条件本記事では、以下の環境が既に整っていることを前提としています。
Next.js プロジェクトが TypeScript で初期化済み
Supabase のプロジェクトが作成済み
Supabase プロジェクトのデータベースパスワードを把握している

 Prisma のインストールと初期化https://supabase.com/docs/guides/database/prisma
この手順の step2 の部分です。

 パッケージのインストールまず、Prisma をプロジェクトに追加します。
npm install prisma --save-dev

 Prisma プロジェクトの初期化次に、Prisma の初期化を行います。
npx prisma init
このコマンドを実行すると、プロジェクトルートにprismaフォルダとschema.prismaファイルが自動生成されます。
生成されるprisma/schema.prismaファイルの内容は以下のようになります
schema.prisma
// This is your Prisma schema file,
// learn more about it in the docs: https://pris.ly/d/prisma-schema

// Looking for ways to speed up your queries, or scale easily with your serverless or edge functions?
// Try Prisma Accelerate: https://pris.ly/cli/accelerate-init

generator client {
  provider = "prisma-client-js"
  output   = "../app/generated/prisma"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

 環境変数の設定https://supabase.com/docs/guides/database/prisma
この手順の step3 の部分です。
ここが結構わかりにくいです。特に Supabase との連携で、どの接続文字列を使用すべきかが分かりにくいため、詳しく解説します。

 デフォルト環境変数の削除.envファイルを開くと、prisma init時に自動追加された環境変数がありますが、これは削除して OK です。

 Supabase から接続情報を取得Supabase から接続文字列を取得する手順は以下です。
Supabase ダッシュボードを開く
ヘッダーの「Connect」ボタンをクリック
または直接以下の URL にアクセスしてプロジェクトを選択https://supabase.com/dashboard/project/_?showConnect=true

 接続文字列の使い分けここつまづきやすいポイントです。

DATABASE_URL - Transaction pooler の値を使用する

DIRECT_URL - Session pooler の値を使用する

 環境変数の設定.envファイルに、手順内記載の以下環境変数をコピペします。
DATABASE_URL="postgres://[DB-USER].[PROJECT-REF]:[YOUR-PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres?pgbouncer=true"

DIRECT_URL="postgres://[DB-USER].[PROJECT-REF]:[YOUR-PASSWORD]@aws-0-us-east-1.pooler.supabase.com:5432/postgres"
値は、先ほど Supabase のダッシュボードでコピーした値に置き換えて、その上で以下 2 点の対応をします。

[YOUR-PASSWORD]は Supabase プロジェクト作成時に設定した Database Password

DATABASE_URLの末尾には必ず?pgbouncer=trueを追加
最終的に以下のような値になっていれば OK です！
.env
DATABASE_URL="postgresql://postgres.abcdefghijk:your_database_password@aws-0-ap-northeast-1.pooler.supabase.com:6543/postgres?pgbouncer=true"

DIRECT_URL="postgresql://postgres.abcdefghijk:your_database_password@aws-0-ap-northeast-1.pooler.supabase.com:5432/postgres"

 スキーマファイルの更新prisma/schema.prismaファイルの datasource 部分を更新します。
    datasource db {
      provider = "postgresql"
      url      = env("DATABASE_URL")
+     directUrl = env("DIRECT_URL")
    }
directUrlを追加することで、マイグレーション時には直接接続を使用し、通常のクエリ時にはコネクションプーリングを使用するように設定できます。

 データベーステーブルの作成と同期
 サンプルテーブルの定義動作確認のため、ミニマムな User テーブルを定義しましょう。
prisma/schema.prismaファイルに以下のモデルを追加します
schema.prisma
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

 データベースへの反映スキーマ定義をデータベースに反映させます。
npx prisma db push
正常に実行されると、以下のような出力が表示されます
Environment variables loaded from .env
Prisma schema loaded from prisma/schema.prisma
Datasource "db": PostgreSQL database "postgres", schema "public" at "aws-0-ap-northeast-1.pooler.supabase.com:5432"

🚀  Your database is now in sync with your Prisma schema. Done in 531ms

Running generate... (Use --skip-generate to skip the generators)

✔ Generated Prisma Client (v6.9.0) to ./app/generated/prisma in 24ms
このコマンドにより、以下の処理が実行されます
データベースに User テーブルが作成される
Prisma Client が./app/generated/prismaに自動生成される
Supabase のダッシュボードでテーブルを見てみると以下のように反映されていることを確認できます！

 まとめ本記事では、Next.js + Supabase プロジェクトに Prisma を導入する手順を詳しく解説しました。
特に重要なポイントは以下の 2 つです。

環境変数の正しい設定 - Transaction pooler と Session pooler の使い分け

スキーマファイルの適切な設定 - directUrl の追加による最適化
Prisma を導入することで、型安全なデータベース操作が可能になり、開発効率が大幅に向上します。まずは今回のサンプル User テーブルで動作確認を行い、その後プロジェクトに必要なテーブル定義を追加していってください！