create-t3-app における Prisma 活用ガイド:型安全 ORM のセットアップ、スキーマ設計、データベース・シーディングまで

原创2026-09-19 21:20:061,349 阅读
文章标签:开发工具CLI代码生成

create-t3-app における Prisma 活用ガイド:型安全 ORM のセットアップ、スキーマ設計、データベース・シーディングまで

Prisma は TypeScript のための ORM であり、schema.prisma ファイルでデータベーススキーマとモデルを定義し、バックエンドからデータベースとやり取りするための型安全なクライアントを生成できます。create-t3-app で Prisma を選択すると、CLI がクライアントの初期化からスキーマ生成、環境変数、npm スクリプトまでを一括でセットアップしてくれます。本記事では、生成される src/server/db.ts の設計意図、スキーマファイルの構成、データベースプロバイダの切り替え方、そしてシーディングの実装手順までを、実際のリポジトリのソースコードと照らし合わせながら解説します。

Prisma とは

Prisma は TypeScript 向けのデータベースツールキット(ORM)です。schema.prisma ファイルでデータベーススキーマとモデルを宣言的に定義し、そのスキーマから型安全なクライアントを生成することで、SQL を直接書かずにデータベースへアクセスできます。モデル定義に対する型が自動生成されるため、コンパイル時にフィールド名や型の誤りを検出でき、リファクタリング時の安全性も高まります。

create-t3-app では Prisma を選択すると、prismaInstaller が以下のパッケージを自動でインストールします。

  • 開発依存:prisma(CLI/スキーマ管理)
  • 本番依存:@prisma/client(生成されるクライアント本体)
  • PlanetScale を選択した場合:@prisma/adapter-planetscale と @planetscale/database

バージョンは dependencyVersionMap.ts に固定マッピングされており、現時点では prisma・@prisma/client ともに ^6.6.0、アダプタは @prisma/adapter-planetscale: ^6.6.0 が使用されます。npm レジストリへの問い合わせを省くことで、インストールのパフォーマンスも最適化されています。

Prisma Client:src/server/db.ts の設計

Prisma クライアントは src/server/db.ts に置かれ、グローバル変数としてインスタンス化されたうえでエクスポートされ、API ルートで使用されます。これは Prisma チームが Next.js 開発時のベストプラクティスとして推奨しているパターンです。

実際の生成テンプレート(db-prisma.ts)を見ると、その設計が明確にわかります。

import { env } from "~/env";
import { PrismaClient } from "../../generated/prisma";

const createPrismaClient = () =>
  new PrismaClient({
    log:
      env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
  });

const globalForPrisma = globalThis as unknown as {
  prisma: ReturnType<typeof createPrismaClient> | undefined;
};

export const db = globalForPrisma.prisma ?? createPrismaClient();

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

この実装が解決しているのは、Next.js のホットリロード(Fast Refresh)時に開発サーバが再起動されるたびに Prisma クライアントが多重生成され、データベース接続がリークするという問題です。globalThis にクライアントを保持し、NODE_ENV が production 以外の場合だけグローバルに再利用する、という 2 段構えのパターンによって、開発時の再生成を防いでいます。

また、PrismaClient の log オプションは環境によって切り替わります。

  • 開発環境(development):query(実行 SQL)、error、warn を出力
  • それ以外(テスト・本番):error のみ

これにより、開発中はクエリログを確認しながらデバッグでき、本番ではログノイズを抑えられます。

なお、生成されるクライアントの出力先はスキーマの generator client ブロックで output = "../generated/prisma" と指定され、プロジェクト直下の generated/prisma に置かれる点にも注目してください(base.prisma)。

PlanetScale を選んだ場合のクライアント

データベースプロバイダとして PlanetScale を選択した場合は、db-prisma-planetscale.ts がコピーされます。こちらは Prisma のドライバアダプタ機能を使って、PlanetScale 用アダプタを直接クライアントに渡します。

import { PrismaPlanetScale } from "@prisma/adapter-planetscale";

import { env } from "~/env";
import { PrismaClient } from "../../generated/prisma";

const createPrismaClient = () =>
  new PrismaClient({
    log:
      env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
    adapter: new PrismaPlanetScale({ url: env.DATABASE_URL }),
  });

このアダプタを使うため、スキーマ側では previewFeatures = <a href="https://link.gitcode.com/i/b1b6077899fa80ed2c0ec0db64b7639f" target="_blank">"driverAdapters"] を有効にしたうえで、relationMode = "prisma"(外部キー制約をデータベース側で強制しない設定)がコメント付きで追加されます([base-planetscale.prisma)。

tRPC コンテキストへの組み込み

create-t3-app では Prisma クライアントがデフォルトで tRPC のコンテキスト に含まれており、各ファイルで個別にインポートするのではなく、コンテキスト経由で利用することを推奨しています。tRPC を使う場合、createTRPCContext は次のように db を返します(with-auth-db.ts)。

import { db } from "~/server/db";

export const createTRPCContext = async (opts: { headers: Headers }) => {
  const session = await auth();

  return {
    db,
    session,
    ...opts,
  };
};

これにより、ルーター内では ctx.db として型安全にアクセスできます。実際のルーター実装(with-prisma.ts)では、次のように利用されています。

create: publicProcedure
  .input(z.object({ name: z.string().min(1) }))
  .mutation(async ({ ctx, input }) => {
    return ctx.db.post.create({
      data: {
        name: input.name,
      },
    });
  }),

getLatest: publicProcedure.query(async ({ ctx }) => {
  const post = await ctx.db.post.findFirst({
    orderBy: { createdAt: "desc" },
  });

  return post ?? null;
}),

ctx.db.post.create や ctx.db.post.findFirst がコンパイル時に型チェックされるため、フィールド名のタイポや存在しないフィールドへのアクセスを即座に検出できます。

スキーマファイルの構成

Prisma のスキーマファイルはプロジェクトの /prisma/schema.prisma に置かれます。ここでデータベーススキーマとモデルを定義し、Prisma クライアント生成時の元ネタになります。

Prisma を選択した場合、create-t3-app は認証ライブラリの選択(NextAuth.js/Better Auth/なし)とデータベースプロバイダに応じて、適切なスキーマテンプレートをコピーします。インストーラ(prisma.ts)のロジックは以下のとおりです。

const schemaBaseName = packages?.betterAuth.inUse
  ? "with-better-auth"
  : packages?.nextAuth.inUse
    ? "with-auth"
    : "base";
const schemaSrc = path.join(
  extrasDir,
  "prisma/schema",
  `${schemaBaseName}${
    databaseProvider === "planetscale" ? "-planetscale" : ""
  }.prisma`
);

つまり、テンプレートディレクトリ cli/template/extras/prisma/schema 内の base.prisma、with-auth.prisma、with-better-auth.prisma と、それぞれの -planetscale 版から 1 つが選ばれ、プロジェクトの prisma/schema.prisma に書き出されます。

基本スキーマ(認証なし)

認証を使わない場合のスキーマ(base.prisma)は次のようになります。

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

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

model Post {
    id        Int      @id @default(autoincrement())
    name      String
    createdAt DateTime @default(now())
    updatedAt DateTime @updatedAt

    @@index([name])
}

Post モデルは id/name/作成日時/更新日時の最小構成で、@@index([name]) によるインデックスも定義済みです。datasource ブロックの url は env("DATABASE_URL") で環境変数から読み込むため、接続先をコードにハードコードしません。

NextAuth.js と組み合わせた場合

NextAuth.js と Prisma を同時に選択すると、NextAuth.js の Prisma アダプタが要求する User・Session・Account・VerificationToken の 4 モデルが、公式ドキュメント推奨の値でスキーマファイルに自動生成されます(with-auth.prisma)。

ポイントを整理すると、以下のとおりです。

  • User:id は cuid() で自動生成、email は @unique
  • Account:provider と providerAccountId の複合ユニーク(@@unique([provider, providerAccountId]))、user へのリレーションは onDelete: Cascade
  • Session:sessionToken は @unique、user へのリレーションは onDelete: Cascade
  • VerificationToken:identifier と token の複合ユニーク
  • Post モデルにも createdBy/createdById が追加され、User とのリレーションを持ちます

また、Account モデルの refresh_token・access_token・id_token には // @db.Text というコメント付きの注釈があります。これは MySQL/SQL Server で String 型(VARCHAR)のままではトークンが長すぎて保存できない問題への対策です。create-t3-app のインストーラは、データベースプロバイダが mysql または planetscale の場合にこのコメントを自動的に有効化します(schemaText.replace("// @db.Text", "@db.Text"))。SQLite/PostgreSQL を使う場合はコメントのままで問題ありません。

デフォルトのデータベースとプロバイダの切り替え

create-t3-app のデフォルトデータベースは SQLite です。セットアップ直後からファイルベースで動作するため、開発や PoC(概念実証)を素早く立ち上げるのには最適ですが、同時実行やスケーラビリティの面から本番環境での使用は推奨されません。

使用するデータベースを変更するには、次の 2 点を変更します。

  1. schema.prisma の datasource ブロックにある provider を postgresql または mysql に変更
  2. 環境変数 DATABASE_URL の接続文字列を対象データベースのものに更新

プロバイダごとの DATABASE_URL

CLI は選択したプロバイダに応じて .env/.env.example に接続文字列の雛形を書き込みます(envVars.ts)。

プロバイダ provider の値 生成される DATABASE_URL の雛形
SQLite(デフォルト) sqlite DATABASE_URL="file:./db.sqlite"
PostgreSQL postgresql DATABASE_URL="postgresql://postgres:password@localhost:5432/<appName>"
MySQL mysql DATABASE_URL="mysql://root:password@localhost:3306/<appName>"
PlanetScale mysql DATABASE_URL='mysql://YOUR_MYSQL_URL_HERE?sslaccept=strict'

プロジェクト名(<appName>)は CLI 実行時に入力した名前がそのままデータベース名に使われます。PlanetScale の場合は、PlanetScale のコンソールで「prisma」ドロップダウンから発行された接続 URL を使い、末尾に ?sslaccept=strict を付けるというガイドがコメントとして書き込まれます。

インストーラによるスキーマ変換

プロバイダを SQLite 以外にした場合、インストーラはスキーマファイルの provider = "sqlite" を選択されたプロバイダに置換します。mysql/postgresql/planetscale のマッピングはインストーラ内に定義されており、PlanetScale は内部的には mysql として扱われます。さらに、前述のとおり mysql/planetscale では @db.Text 注釈も同時に有効化されます。

ただし、すでにプロジェクトを作成済みの場合は、この変換は自動では行われません。provider を手で書き換えた後、pnpm db:push などでスキーマをデータベースに反映し、.env の DATABASE_URL を更新する必要があります。

環境変数のバリデーション

Prisma を使うプロジェクトでは、src/env.js に DATABASE_URL のバリデーションが追加されます(with-db.js)。

DATABASE_URL: z.string().url(),

@t3-oss/env-nextjs と zod によるこのバリデーションにより、DATABASE_URL が未設定・不正な形式のまま next build や next dev を実行すると、起動時にエラーで検出されます。空文字を未定義として扱う emptyStringAsUndefined: true の設定と合わせて、環境変数ミスによる実行時トラブルを未然に防ぎます。スキップしたい場合は SKIP_ENV_VALIDATION 環境変数を指定します(Docker ビルドなどで有用です)。

package.json に追加される npm スクリプト

Prisma インストーラは、次の 5 つのスクリプトを package.json に追加します(prisma.ts)。

スクリプト 実行されるコマンド 用途
postinstall prisma generate 依存関係インストール後に自動でクライアント生成
db:push prisma db push スキーマをデータベースに直接反映(マイグレーション履歴を作らない)
db:studio prisma studio ブラウザベースのデータ閲覧・編集 UI を起動
db:generate prisma migrate dev 開発用マイグレーション作成+適用+クライアント再生成
db:migrate prisma migrate deploy 本番環境向けに既存マイグレーションを適用

postinstall が設定されているため、pnpm install(または npm install/yarn)を実行するだけで Prisma クライアントが自動生成され、src/server/db.ts の import が解決されます。

データベースのシーディング

データベースのシーディング(訳註:データベース構築時にダミーデータや初期データを投入すること)は、開発を始める際にテストデータを素早く投入できる非常に便利な機能です。create-t3-app の公式ドキュメントに沿ったセットアップ手順は次のとおりです。

1. seed.ts を作成する

/prisma ディレクトリに seed.ts ファイルを作成します。

import { db } from "../src/server/db";

async function main() {
  const id = "cl9ebqhxk00003b600tymydho";
  await db.example.upsert({
    where: {
      id,
    },
    create: {
      id,
    },
    update: {},
  });
}

main()
  .then(async () => {
    await db.$disconnect();
  })
  .catch(async (e) => {
    console.error(e);
    await db.$disconnect();
    process.exit(1);
  });

このサンプルは upsert を使って指定 ID のレコードが存在すれば更新、なければ作成するという冪等(何度実行しても同じ結果)なシーディングです。最後に db.$disconnect() を呼んで接続を閉じ、エラー時は process.exit(1) で異常終了させる、という定番の流れになっています。

なお、上の例の db.example はあくまで雛形です。実際のプロジェクトでは、スキーマで定義したモデル名に合わせてください。現在のリポジトリの基本スキーマ(base.prisma)ではモデルは Post なので、db.post.upsert(...) のようになります。

2. package.json にシード設定を追加する

package.json の scripts に db-seed を追加し、prisma キーにシード実行コマンドを定義します。

{
  "scripts": {
    "db-seed": "NODE_ENV=development prisma db seed"
  },
  "prisma": {
    "seed": "tsx prisma/seed.ts"
  }
}

NODE_ENV=development を明示しているのは、src/server/db.ts のログ設定が NODE_ENV で切り替わるためです。prisma db seed コマンドが prisma.seed で指定されたコマンドを実行します。

3. TypeScript ランナーを導入する

シードスクリプトは TypeScript で書かれているため、実行できるランナーが必要です。create-t3-app が推奨するのは tsx です。esbuild ベースで非常に高速に動作し、ESM 設定(ts-node で必要になるような)が不要という利点があります。ts-node や他のランナーでも動作します。

pnpm add -D tsx

4. 実行する

あとは次のコマンドを実行するだけです。

pnpm db-seed

npm や yarn を使っている場合は、それぞれ npm run db-seed、yarn db-seed と読み替えてください。

まとめ

create-t3-app が生成する Prisma 構成は、単なる ORM の雛形ではなく、「Next.js 開発における実践的な設計」が織り込まれています。

  • グローバルクライアントパターン(src/server/db.ts)による開発時の接続リーク防止
  • 環境別のログレベル(開発時は query/error/warn、本番は error のみ)
  • tRPC コンテキスト経由の db 公開による各ファイルでの個別 import 回避
  • NextAuth.js 連携モデルの自動生成と MySQL 向け @db.Text の自動有効化
  • PlanetScale ドライバアダプタへの透過的な切り替え
  • postinstall・db:push・db:studio・db:generate・db:migrate という整備済み npm スクリプト

スキーマファイルは cli/template/extras/prisma/schema に、クライアント実装は cli/template/extras/src/server/db に、インストール処理は cli/src/installers/prisma.ts にそれぞれ置かれているため、興味があればぜひ読み進めてみてください。また、環境変数まわりは envVars.ts と src/env.js を、tRPC との連携は tRPC のドキュメント を参照すると、より全体像を把握できます。

関連する公式リソースとしては、Prisma 公式ドキュメント、Prisma GitHub リポジトリ、Prisma Migrate プレイグラウンド、NextAuth.js の Prisma アダプタ解説、PlanetScale 接続ガイドなどが役立ちます。いずれも Prisma のスキーマ記法の詳細やマイグレーションの応用手法を学ぶ際に参照してください。

登录后查看全文
create-t3-app