メインコンテンツにスキップ

メンタルモデル

このガイドでは、リレーショナルデータベースを使用する際の Prisma Migrate を使用したデータベースマイグレーションの概念的な概要について説明します。データベースマイグレーションとは何か、その価値、Prisma Migrate とは何か、さまざまな環境で Prisma Migrate を使用してデータベーススキーマを進化させる方法について説明します。

MongoDB を使用している場合は、スキーマを進化させるために prisma db push を使用してください。

データベースマイグレーションとは？​

データベースマイグレーションは、データベーススキーマの構造を変更および進化させる、制御された一連の変更です。マイグレーションは、データベーススキーマをある状態から別の状態に移行するのに役立ちます。たとえば、マイグレーション内で、テーブルとカラムを作成または削除したり、テーブル内のフィールドを分割したり、データベースに型と制約を追加したりできます。

データベーススキーマを進化させるためのパターン​

このセクションでは、データベーススキーマを進化させるための一般的なスキーママイグレーションパターンについて説明します。

主なスキーママイグレーションパターンは 2 つあります。

  • モデル/エンティティファーストマイグレーション： このパターンでは、コードでデータベーススキーマの構造を定義し、マイグレーションツールを使用して SQL を生成します。たとえば、アプリケーションとデータベーススキーマを同期するためなどです。

Model-first migration flow

  • データベースファーストマイグレーション： このパターンでは、データベースの構造を定義し、SQL を使用してデータベースに適用します。次に、データベースをイントロスペクトして、アプリケーションとデータベーススキーマを同期するためにデータベースの構造を記述するコードを生成します。

Database-first migration flow

情報

注記

わかりやすくするために、上記の用語を選択して、データベーススキーマを進化させるためのさまざまなパターンを説明しました。他のツールやライブラリでは、異なる用語を使用してさまざまなパターンを説明している場合があります。

マイグレーションファイル（SQL）は、理想的にはアプリケーションコードと一緒に保存する必要があります。また、バージョン管理で追跡し、アプリケーションに取り組んでいるチームの他のメンバーと共有する必要があります。

マイグレーションは状態管理を提供し、データベースの状態を追跡するのに役立ちます。

マイグレーションを使用すると、データベースの状態を特定の時点に複製することもできます。これは、チームの他のメンバーと共同作業する場合（例：異なるブランチ間を切り替える場合）に役立ちます。

データベースマイグレーションの詳細については、Prisma Data Guideを参照してください。

Prisma Migrateとは？​

Prisma Migrate は、ローカル環境および本番環境でデータベーススキーマを管理するためにモデル/エンティティファーストマイグレーションパターンをサポートするデータベースマイグレーションツールです。

プロジェクトで Prisma Migrate を使用する場合のワークフローは反復的であり、次のようになります。

ローカル開発環境（フィーチャーブランチ）

  1. Prisma スキーマを進化させる
  2. prisma migrate dev または prisma db push を使用して、Prisma スキーマをローカル開発データベースのデータベーススキーマと同期させます。

プレビュー/ステージング環境（フィーチャープルリクエスト）

  1. フィーチャープルリクエストに変更をプッシュします
  2. CI システム（例：GitHub Actions）を使用して、prisma migrate deploy を使用して Prisma スキーマとマイグレーション履歴をプレビューデータベースと同期させます。

本番環境（メインブランチ）

  1. フィーチャーブランチからメインブランチにアプリケーションコードをマージします
  2. CI システム（例：GitHub Actions）を使用して、prisma migrate deploy を使用して Prisma スキーマとマイグレーション履歴を本番データベースと同期させます。

Prisma Migrate workflow

Prisma Migrate がマイグレーション状態をどのように追跡するか​

Prisma Migrate は、データベーススキーマの状態を追跡するために、次の状態を使用します。

  • Prisma スキーマ：データベーススキーマの構造を定義する真実のソース。
  • マイグレーション履歴：データベーススキーマに加えられた変更の履歴を表す prisma/migrations フォルダ内の SQL ファイル。
  • マイグレーションテーブル：データベースに適用されたマイグレーションのメタデータを格納するデータベース内の prisma_migrations テーブル。
  • データベーススキーマ：データベースの状態。

Prisma Migrate "state management"

Prisma Migrate を使用する際の要件​

  • 理想的には、環境ごとに 1 つのデータベースを使用する必要があります。たとえば、開発、プレビュー、および本番環境用に別々のデータベースを用意することができます。
  • 開発環境で使用するデータベースは使い捨てです。必要に応じてデータベースを簡単に作成、使用、および削除できます。
  • 各環境で使用されるデータベース構成は一貫している必要があります。これは、ワークフロー全体を移動する特定のマイグレーションがデータベースに同じ変更をもたらすことを保証するために重要です。
  • Prisma スキーマは、データベーススキーマの形状を記述する真実のソースとして機能します。

Prisma Migrate を使用してデータベーススキーマを進化させる​

このセクションでは、Prisma Migrate を使用して、開発、ステージング、および本番環境などの異なる環境でデータベーススキーマを進化させる方法について説明します。

開発環境（ローカル）での Prisma Migrate​

prisma migrate dev を使用してマイグレーション履歴を追跡する​

prisma migrate dev コマンドを使用すると、データベースに加えた変更を追跡できます。prisma migrate dev コマンドは、SQL マイグレーションファイル（/prisma/migrations に保存）を自動的に生成し、データベースに適用します。マイグレーションがデータベースに適用されると、データベース内のマイグレーションテーブル（_prisma_migrations）も更新されます。

Prisma Migrate dev flow

prisma migrate dev コマンドは、次の状態を使用してデータベースの状態を追跡します。

  • Prisma スキーマ
  • マイグレーション履歴
  • マイグレーションテーブル
  • データベーススキーマ

注記：マイグレーションの状態を追跡するために使用される状態は、Prisma Migrate がマイグレーション状態をどのように追跡するか セクションで説明されているものと同じです。

マイグレーションをデータベースに適用する前に、--create-only フラグを使用してカスタマイズできます。たとえば、データ損失を招くことなくカラムの名前を変更したり、データベース拡張機能（PostgreSQL の場合）やデータベースビュー（現在サポートされていません）をロードしたりする場合は、マイグレーションを編集することができます。

内部的には、Prisma Migrate は シャドウデータベース を使用して スキーマドリフト を検出し、新しいマイグレーションを生成します。

注記：prisma migrate dev は、使い捨てデータベースを使用した開発でのみ使用することを目的としています。

prisma migrate dev がスキーマドリフトまたはマイグレーション履歴の競合を検出した場合、マイグレーション履歴とデータベーススキーマを同期させるために、データベースをリセット（データベースをドロップして再作成）するように求められます。

シャドウデータベースの説明（漫画）を展開

A cartoon that shows how the shadow database works.

スキーマドリフトを解決する​

スキーマドリフトは、予期されるデータベーススキーマがマイグレーション履歴にあるものと異なる場合に発生します。たとえば、Prisma スキーマと prisma/migrations を適切に更新せずにデータベーススキーマを手動で更新した場合に発生する可能性があります。

そのようなインスタンスの場合、prisma migrate diff コマンドを使用して、マイグレーション履歴を比較し、データベーススキーマに加えられた変更を元に戻すことができます。

Revert database schema with migrate diff

migrate diff を使用して、次のいずれかの SQL を生成できます。

  • 現在の Prisma スキーマと同期させるために、データベーススキーマに加えられた変更を元に戻します
  • Prisma スキーマと /migrations からの不足している変更を適用するために、データベーススキーマを前方に移動します

その後、prisma db execute コマンドを使用して、データベースに変更を適用できます。

スキーマをプロトタイプする​

prisma db push コマンドを使用すると、マイグレーション（/prisma/migrations）を永続化せずに、Prisma スキーマとデータベーススキーマを同期できます。prisma db push コマンドは、次の状態を使用してデータベースの状態を追跡します。

  • Prisma スキーマ
  • データベーススキーマ

prisma db push development flow

prisma db push コマンドは、次の場合に役立ちます。

  • 他の開発者、またはステージング環境や本番環境などの他の環境に変更をデプロイする必要なく、ローカルでスキーマ設計を迅速にプロトタイプおよび反復処理したい場合。
  • 目的の最終状態に到達することを優先しており、その最終状態に到達するために実行された変更または手順は優先していません（prisma db push によって行われた変更をプレビューする方法はありません）。
  • スキーマの変更がデータにどのように影響するかを制御する必要はありません。スキーマとデータマイグレーションを調整する方法はありません - prisma db push が変更によってデータ損失が発生すると予想される場合、--accept-data-loss オプションでデータ損失を受け入れるか、プロセスを停止することができます - 変更をカスタマイズする方法はありません。

prisma db push コマンドがデータベーススキーマへの破壊的な変更を検出した場合、データベースをリセットするように求められます。たとえば、デフォルト値を指定せずに既存のコンテンツを含むテーブルに必須フィールドを追加すると、これが起こります。

スキーマドリフト は、データベーススキーマがマイグレーション履歴およびマイグレーションテーブルと同期していない場合に発生します。

ステージング環境および本番環境での Prisma Migrate​

マイグレーション履歴を同期する​

prisma migrate deploy コマンドを使用すると、開発環境からのマイグレーション履歴をステージング環境または本番環境のデータベースと同期できます。

内部的には、migrate deploy コマンドは次の処理を行います。

  1. 既に適用されたマイグレーション（_prisma_migrations でキャプチャ）とマイグレーション履歴（/prisma/migrations）を比較します
  2. 保留中のマイグレーションを適用します
  3. 新しいマイグレーションで _prisma_migrations テーブルを更新します

Workflow of Prisma Migrate

このコマンドは、GitHub Actions などの自動化された CI/CD 環境で実行する必要があります。

マイグレーション履歴（/migrations）がない場合、つまり prisma db push を使用している場合は、ステージング環境および本番環境で prisma db push を引き続き使用する必要があります。データベーススキーマに適用される変更に注意してください。それらの変更の一部は破壊的である可能性があります。たとえば、prisma db push は、カラムの名前変更を実行しているかどうかを判別できません。データベースのリセット（ドロップと再作成）を求められます。