マルチORM環境のDBマイグレーション管理｜Prisma+Alembic共存から一本化への移行・DDLガード・スキーマ不整合の復旧ガイド【2026年版】

FEとBEが同じDBを触る——マイグレーション衝突の悪夢

Next.js（Prisma）とFastAPI（Alembic/SQLAlchemy）が同じMySQLデータベースを共有する。この構成は珍しくありませんが、両方のORMがDDL（Data Definition Language）を発行すると、スキーマ不整合という深刻な問題が発生します。

実際に、FEコンテナを差し替えた直後にPrismaマイグレーションが走り、AlembicのDDLと衝突してテーブル定義が壊れ、コア機能が停止した事例が報告されています。画面表示は正常なのにバックエンド処理がエラーになる——最も発見が遅れるタイプの障害です。

本記事では、マルチORM環境でのDBマイグレーション管理の実践手法を、DDL管理の一本化からCIガード設計まで解説します。

なぜ問題が起きるのか——マルチORM環境の構造的リスク

典型的な構成

FE（Next.js）                BE（FastAPI）
  └ Prisma ORM                └ SQLAlchemy + Alembic
    └ prisma migrate            └ alembic upgrade head
      ↓                          ↓
   ┌──────────────────────────────┐
   │      同一MySQL DB           │
   │  ・FE管理テーブル            │
   │  ・BE管理テーブル            │
   │  ・共有テーブル              │
   └──────────────────────────────┘

衝突が発生する3つのパターン

パターン	発生条件	症状
テーブル重複作成	両方のORMが同名テーブルを作成しようとする	Table already existsエラー
カラム定義の不一致	PrismaのupdatedAt（アプリ側自動設定）とAlembicのINSERT文の間でデフォルト値が不整合	INSERT時にNOT NULLエラー
マイグレーション未適用	FEコンテナ差し替え時にPrismaマイグレーションが実行されない	Table does not existエラー

解決策：DDL管理の一本化

最も根本的な解決策は、DDL管理を1つのORM（通常はバックエンド側）に一本化することです。

一本化の方針

• DDL発行はAlembic（BE）のみ：テーブルの作成・変更・削除はAlembicだけが行う
• Prismaはクライアントとしてのみ使用：FE側のPrismaはDB操作（CRUD）のみを担当。マイグレーションは実行しない
• スキーマ同期は手動：Alembic側でスキーマを変更したら、Prismaスキーマも手動で同期

Prismaマイグレーションの「封印」手順

Prismaのマイグレーション機能を無効化する具体的な手順は以下の通りです。

1. prisma/migrations/を全削除：既存のマイグレーションファイルとlock fileを削除
2. package.jsonからprisma:migrateを削除：prisma:generateとprisma:studioは残す
3. prisma/schema.prisma先頭にコメント追加：DDL管理ルール、スキーマ同期手順、禁止操作を明記
4. .gitignoreにprisma/migrations/を追加：誤再作成・誤コミットを防止
5. README/AGENTS.mdを更新：「DDLはBE（Alembic）管理。FE側でマイグレーションしない」方針を明記
6. CIにDDLガードを追加：prisma/migrations/が存在したら失敗、package.jsonにprisma:migrateが混入したら失敗

封印後も維持するもの

• @prisma/client依存（92箇所のDB操作を維持）
• DATABASE_URL環境変数
• prisma:generateコマンド（型生成に必要）
• prisma:studioコマンド（DB閲覧に便利）

スキーマ不整合からの復旧手順

パターン1：テーブルが存在しない場合

FEがprisma.conversionSettings.findUnique()を呼び出すが、テーブルが存在しないケースです。

エラー: The table 'ConversionSettings' does not exist in the current database.
原因: Prismaマイグレーションが最新まで実行されていない

復旧手順

1. DBバックアップを取得（mysqldump）
2. データベースを全削除（DROP DATABASE→CREATE DATABASE）
3. Alembicのみでテーブルを再作成（alembic upgrade head）
4. FEコンテナを再起動してDB接続をリフレッシュ

パターン2：テーブルが既に存在する場合

Alembicが新しいテーブルを作成しようとするが、Prismaが既に作成済みのケースです。

エラー: Table 'BlobFileOverwriteHistory' already exists
原因: Prismaが作成したテーブルをAlembicが再作成しようとした

復旧手順

1. alembic stamp headで「DBは既に最新状態」とAlembicに記録
2. テーブル構造自体は変更しない
3. 以後のマイグレーションはAlembicのみが管理

パターン3：カラム定義の不一致

PrismaのテーブルではupdatedAtがアプリ側で自動設定される前提だが、AlembicのINSERT文にはupdatedAtの値が含まれていないケースです。

エラー: Column 'updatedAt' cannot be null
原因: Prismaが作成したテーブル定義とAlembicのモデル定義でデフォルト値の扱いが異なる

復旧手順

1. Alembicでマイグレーションファイルを作成し、server_defaultを追加
2. alembic upgrade headで適用

CIガードの設計

DDL管理の一本化は、ルールだけでは守れません。CIパイプラインでの自動チェックが必須です。

チェック項目

チェック	失敗条件	目的
Prisma migrations検知	prisma/migrations/ディレクトリが存在する	封印後の誤再作成を防止
migrate コマンド検知	package.jsonにprisma:migrateが含まれる	封印後の誤混入を防止
Alembic整合性チェック	マイグレーション履歴とDBのalembic_versionが不一致	マイグレーション漏れを検出

マイグレーション冪等性の確保

Alembicマイグレーションは冪等（何回実行しても同じ結果になる）である必要があります。特にマルチORM環境では、テーブルが既に存在する状態でマイグレーションが実行されるケースが頻発します。

冪等性の実装パターン

• IF NOT EXISTS：テーブル作成時に既存チェックを含める
• try-except：テーブル存在エラーをキャッチして無視
• 条件分岐：alembic_versionテーブルの状態に応じて処理を分岐

2026年のマイグレーション管理トレンド

ORMの隠れた偏見

Alembic、Django Migrations、Prisma Migrateなどのマイグレーションツールには「隠れた偏見」があることが指摘されています。ORMはデータベースの抽象化に焦点を当てており、データベース管理そのものには向いていません。

高度なデータベース機能、CI/CD統合、複数スタック間の一貫性が必要なチームには、AtlasのようなORM非依存のスキーマ管理ツールが選択肢になります。

Prismaの外部管理テーブル機能

Prismaはtables.external設定で、他チーム・他サービスが管理するテーブルを「外部管理」とマークできます。これにより、Prismaがそのテーブルのマイグレーションを発行しなくなります。

実務でのベストプラクティス

DDL管理の一本化ルール

1. 1プロジェクト1マイグレーションツール：DDLを発行するのは1つだけ
2. ORM間の境界を明確に：どのORMがどのテーブルを「所有」するかを文書化
3. CIで強制：ルール違反を自動検出してマージをブロック
4. 環境再構築手順を文書化：DROP → CREATE → migrateの完全手順

デプロイ時の注意点

• マイグレーション前に必ずDBバックアップを取得する
• コンテナ再起動時にマイグレーションが自動実行されないか確認する（DockerfileのCMDにmigrate含まれていないか）
• ロールバック手順を事前に用意する（alembic downgrade、バックアップからの復元）

まとめ：マルチORM環境のマイグレーション管理チェックリスト

フェーズ	チェック項目	完了基準
設計	DDL管理ツールが1つに統一されているか	ドキュメントで明文化済み
封印	不要なマイグレーション機能が無効化されているか	migrations/削除、CIガード設定
CI	封印違反の自動検出が設定されているか	PRで自動ブロック
冪等性	マイグレーションが冪等に設計されているか	2回実行してもエラーなし
デプロイ	マイグレーション前にDBバックアップを取得しているか	バックアップファイル存在確認
復旧	スキーマ不整合の復旧手順が文書化されているか	3パターンの復旧手順が存在

マルチORM環境でのDBマイグレーション管理は、「ルールを決める」だけでは不十分です。CIで強制し、復旧手順を文書化し、デプロイ時にバックアップを取得する——この3層の防御が、スキーマ不整合という悪夢を防ぎます。

あわせて読みたい

• 5Sとは｜整理・整頓・清掃・清潔・しつけの意味・目的・進め方を解説
• AIリードスコアリング実装ガイド【2026年版】— 4要素スコアリング×テリトリー管理×ステータス倍率の本番アーキテクチャ
• AIカスタマーサポート完全ガイド【2026年版】— RAG・チャットボット・有人連携の実装パターンとツール比較

関連記事

• デプロイ障害の6ステージ切り分け
• 作業方針書テンプレート
• ポストモーテム設計
• 納品前セキュリティ検品

開発プロセスの改善はrenueにご相談ください。