prisma migrate とは、Prisma の schema の変更を migration の記録として残し、DB に順に当てていく命令の一群です。

  • migrate dev・deploy・reset・diff と db push・db execute が、それぞれ何をして、どこで使う命令か
  • 当社が db push と手書きの SQL で CI の使い捨て DB を建てて、実際に落ちた所と直した形
  • schema と SQL のずれを migrate diff で見る門と、本番に当て終わった SQL の置き場

当社は、DB の変更を AIエージェント の席に書かせ、PR と merge queue を通して本番へ入れています。この頁は、その道で Prisma の命令の役割を取り違えて止まった記録を、公式の文書の定義と並べたものです。

prisma migrate と prisma db push、命令ごとの役割

Prisma の CLI の参照（Prisma ORM v7 の版）では、migrate の命令は migration の履歴を使い、db push と db execute は履歴の表（_prisma_migrations）を通さずに DB を変えます。

命令何をするか（公式の文書）どこで使うか（公式の文書）当社で起きた事
prisma migrate devshadow database で既存の履歴を流し直してずれを見つけ、schema の変更から新しい migration を作り、開発の DB に当てて _prisma_migrations を更新する開発の環境だけ。shadow database が要る—
prisma migrate deployまだ当てていない migration を全部当てる。DB が無ければ作る。ずれの検出・reset・shadow database は使わない主に開発以外の環境—
prisma migrate resetDB か schema を消して（できなければ軽い reset）作り直し、migration を全部当てる開発の環境だけ—
prisma migrate diff2 つの schema の元を比べ、1 つ目を 2 つ目の状態へ移す migration の中身を出す。--exit-code で差が無い 0・誤り 1・差がある 2 を返す（用途の限定の記載なし）schema と手書きの SQL のずれを見る門に使った（社の実測 2026-09-20）
prisma db pushmigration を使わずに schema の状態を DB へ押し込む。DB が無ければ作る。--accept-data-loss はデータが消える警告を無視するschema の変更に版を付けなくてよい時（試作・手元の開発）CI の使い捨て DB の土台に使う。--accept-data-loss は 2026-04-12 に schema の外の表を全部消して禁止（社の実測 2026-04-12）
prisma db executemigration の表に触れずに SQL の台本を DB に当てる（用途の限定の記載なし）—

出典: Prisma CLI reference（Prisma ORM v7）https://www.prisma.io/docs/orm/reference/prisma-cli-reference （2026-11-04 に確認）。「当社で起きた事」の列は社の実測（日付は各行）。

なお、Prisma の mental model の URL（https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/mental-model）は、2026-11-04 に開くと Prisma ORM 8 の「The migration graph」の頁に移っていました。そこでは ORM 8 の prisma db update が「ORM 7 の db push と同じく、migration を書かずに DB を contract に合わせる」と書かれています。この頁の命令の名前は ORM 7 の版で書いています。

当社の CI の使い捨て DB は「db push の後に手書きの SQL」

当社の CI は、試験のたびに使い捨ての DB を建てます。順は、prisma db push で schema.prisma の表を建て、その後に手書きの SQL（migrations-manual の直下のファイル）を全部当てる、です（社の実測 2026-10-21）。schema.prisma で書けない制約や設定は手書きの SQL が持ちます。

この形は「schema.prisma が建てる物」と「SQL が足す物」が 1 つの DB に重なるので、同じ物を両方が持つと衝突し、片方にしか無い物は CI の DB に現れません。下の 4 つの記録は、どれもこの重なりで起きました。

同じ一意を 2 か所で宣言して、merge queue が約 35 分止まった

ある一意（unique）を、schema.prisma の @@unique（map で名前つき）と、手書きの SQL の ADD CONSTRAINT の 2 か所で宣言しました。CI の DB では db push が先に同じ名前の索引を作るので、後から当てる SQL が relation "…" already exists で落ちました（社の実測 2026-10-21）。

厄介だったのは、SQL だけの PR は単独では CI を通ったことです。schema に @@unique を足すコードの PR を main に重ねた merge queue の列で初めて 2 つが出会って衝突し、後ろの 5 つの束を巻き添えにして約 35 分止まりました（社の実測 2026-10-21）。

直しは、main に入った SQL は書き換えず、schema.prisma から @@unique を外して、一意は SQL だけが持つ形にしました（社の実測 2026-10-21）。当てた後の SQL を書き換えると、本番に当てた物と記録が食い違うためです。

db push の DB には、SQL にしか無い CHECK 制約が無い

db push で建てた CI の DB には、手書きの SQL にしか無い CHECK 制約がありませんでした。CHECK が在る前提で書いた試験は、PR の CI では skip され、merge queue で初めて赤になりました（社の実測 2026-10-30）。緑の中に「撃たれていない試験」が混ざる形で、揺れる試験とは別の理由の、列でだけ出る赤です。

直しは、試験の中で出荷する SQL のファイルから CHECK を読んで DB に当ててから撃つ形です（社の実測 2026-10-30）。試験の側で CHECK を書き写すと、SQL を直した時に試験だけ古いまま残ります。

prisma db push --accept-data-loss を禁止にした理由

公式の文書の通り、--accept-data-loss はデータが消える警告を無視する印です。当社は 2026-04-12 に実際に撃ち、schema.prisma の外にある表が全部消えました（社の実測 2026-04-12）。それ以来、社の規則で禁止です。

手元の使い捨て DB に撃った例では rc=1 で止まり、何も当たりませんでした（社の実測 2026-10-04）。それでも禁止は宛先によらず、手元の結合試験の DB も、CI と同じ setup の手順という決まった 1 本の作り方だけで作ります（社の実測 2026-10-04）。宛先を見て許すかを決める形は、次の節の取り違えで崩れるからです。

使い捨て DB のつもりで、他人の試験 DB に SQL を当てた

使い捨ての DB を docker run -p で立てようとした時、その port は別の古い容器に取られていて、docker run は失敗していました。ところが次の setup を && でなく ; で繋いでいたので、setup はそのまま走り、その port の先にあった他人の試験 DB に SQL を全部当てました（社の実測 2026-10-25）。db push はデータが消える警告で止まり、宛先は本番ではありませんでした（社の実測 2026-10-25）。

直しは 2 つです（社の実測 2026-10-25）。

  1. 空いた port を lsof で先に測ってから容器を立てる
  2. docker run の終了コードを見てから setup を撃つ（; で繋がない）

schema と SQL のずれを prisma migrate diff で見る門

schema.prisma が動いたのに、本番に当てる SQL がどこにも無い PR を止めたい。当社はそのために、prisma migrate diff --exit-code を使う門を置いています（社の実測 2026-09-20）。

  1. base（main 側）の schema を db push した DB を建てる
  2. その PR が足した SQL だけを当てる
  3. その DB と head（PR 側）の schema を prisma migrate diff --exit-code で比べる。差があれば 2 が返る（終了コードは CLI の参照の定義）

最初の形では、SQL を先の PR で入れ、schema の変更を後の PR で入れる正しい順序を踏むと、後の PR の SQL は base に既に在るので「その PR が足した SQL」が空になり、必ず赤になりました（社の実測 2026-09-20）。門の側を直し、次の 2 つを確かめています（社の実測 2026-09-20）。

  • 陰性: schema が動いたのに SQL がどこにも無い形は、赤のまま
  • 陽性: SQL が既に base に在る形は、緑

本番に当て終わった SQL は消さずに applied/ へ移す

本番に当て終わった SQL の中には、後の schema の変更のせいで CI の使い捨て DB では流せなくなる物が出ます。当社はそれを消さずに migrations-manual/applied/ へ移します（社の実測 2026-08-28）。setup の glob は直下だけを拾うので、移しただけで自動で CI の対象から外れます（社の実測 2026-08-28）。

採らなかった形は 2 つです。消すと、本番に何を当てたかの記録を失います。除外の一覧に足すと、いつ外すかの条件が無い穴が残ります（社の実測 2026-08-28）。

db push だけで建て直した staging は、RLS が外れていた

db push だけで建て直した staging の DB（Supabase）を測ると、38 表のうち 36 表で RLS（行の単位のアクセス制御）が無効でした（社の実測 2026-10-14）。全表で有効にしました（社の実測 2026-10-14）。db push が建てるのは schema.prisma に書いた物で、手書きの SQL が持っていた設定は、SQL を当てない限り戻りません。建て直した DB は、表の数だけでなく、SQL 側が持つ設定まで数えて確かめます。

prisma generate の「Generated」を信じない

日本語を含むパスの作業木で prisma generate を撃つと、「Generated」と出るのに、生成物はパスの 1 文字を U+FFFD に壊した別のディレクトリへ書き出されていました（社の実測 2026-10-06）。作業木の側の生成物は古いままです。

測り方は、生成物の更新時刻と index.d.ts の中身を見ることです（社の実測 2026-10-06）。回避は、schema を ASCII だけのパスへ写して生成し、生成物を作業木へ写す形です（社の実測 2026-10-06）。

よくある質問

prisma migrate dev と prisma migrate deploy の違いは？

migrate dev は開発の環境用で、shadow database でずれを見つけ、schema の変更から新しい migration を作って当てます。migrate deploy は主に開発以外の環境用で、まだ当てていない migration を当てるだけで、ずれの検出も新しい migration の作成もしません（Prisma CLI reference）。

prisma db push と prisma migrate はどう使い分ける？

公式の文書では、db push は migration を使わずに schema を DB へ押し込む命令で、schema の変更に版を付けなくてよい試作や手元の開発に向くとされています。当社は CI の使い捨て DB の土台にだけ db push を使い、本番に当てる変更は手書きの SQL で記録しています（社の実測 2026-10-21）。

prisma db push --accept-data-loss は使ってよい？

この印はデータが消える警告を無視するためのものです（Prisma CLI reference）。当社は実際に撃って schema の外の表が全部消えたので、宛先によらず禁止にしています（社の実測 2026-04-12）。

prisma migrate diff を CI の門に使える？

使えます。--exit-code を付けると差が無ければ 0、差があれば 2、誤りは 1 を返します（Prisma CLI reference）。当社は base の schema に PR の SQL を当てた DB と head の schema を比べていますが、SQL を先に入れる順序で誤って赤になる形を踏んだので、陰性と陽性の両方を確かめてから門にしました（社の実測 2026-09-20）。

出典

  1. Prisma CLI reference（Prisma ORM v7）https://www.prisma.io/docs/orm/reference/prisma-cli-reference （2026-11-04 に確認）
  2. Prisma Docs「The migration graph」（mental model の URL から移った先・Prisma ORM 8）https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/mental-model （2026-11-04 に確認）
  3. 社の実測 2026-04-12・2026-08-28・2026-09-20・2026-10-04・2026-10-06・2026-10-14・2026-10-21・2026-10-25・2026-10-30

ブルーランプ 記事の編集部／更新日 2026-11-04