`supabase/migrations/` に `001_xxx.sql` のような連番でファイルを足していく。多くの Supabase のプロジェクトで見かける、素朴なやり方です。on-board typingでもそうしていました。ところが複数の機能を並行して作っていると、この連番が壊れます。

理由がわからないまま、CI が落ちる

Supabase CLI は、適用したマイグレーションを `supabase_migrations.schema_migrations` という表に記録しています。この表の主キーは、ファイル名の先頭の番号そのものです。なので、`016_a.sql` と `016_b.sql` のように同じ番号のファイルが2つあると、`supabase test db` や `supabase db push` は「duplicate key value violates unique constraint "schema_migrations_pkey"」で必ず失敗します。

厄介なのは、このエラーだけを見ても原因がすぐにはわからないことです。マイグレーションの中身には何の問題もないのに、CI だけが落ちます。

同じ問題を、3回起こした

一度直せば終わりだと思っていましたが、そうはなりませんでした。機能ごとに別のブランチで作っていると、それぞれのブランチの中でしか「次の番号」がわかりません。ブランチAが019を使い、ブランチBも同じ頃に019を使う。それぞれ単体では問題なく通るので、マージするまで衝突に気づけません。

on-board typing では、016番、019・020番、021番と、形を変えて3回続けて起きました。3回目で、番号のつけ方そのものが並行開発と相性が悪いのだと認めました。

対策1:ぶつかったら、順番を守って振り直す

当面の直し方は単純で、後からマージした方のファイルを、空いている番号に付け替えます。ただし番号は実行順でもあるので、片方がもう片方より後に実行される必要がある場合は、その順番を崩さないように振り直す必要があります。

対策2:重複を機械で見つける

振り直しを3回繰り返した後、`supabase/migrations/` のファイル名から先頭の数字だけを取り出して、重複がないか確かめるスクリプトを作りました。数行の簡単なものです。ただ、これを CI に組み込むところまではまだできておらず、今は手元で走らせています。次の衝突が起きる前に、CI で自動的に止めるところまで持っていくつもりです。

そもそも、CLI は連番を前提にしていなかった

振り返ると、根本の選択ミスは番号のつけ方でした。`supabase migration new ` は、本来 `20260701123045_name.sql` のような日時つきのファイル名を作ります。日時なら、同じ秒に2つのブランチでコマンドを打たない限りぶつかりません。on-board typing では読みやすさを優先して手で連番に揃えていましたが、それは CLI が用意していた衝突よけを自分から手放すことでもありました。

見た目のきれいさと、並行開発への強さは、思っていたより両立しにくいものでした。この失敗をきっかけに開発の進め方そのものを変えた話は、12日で114本のプルリクエストの記事に書いています。