metabase-data-app-migrate

データアプリを現在のコントラクトバージョンへ移行する

データアプリは、そのコードが対象とするコントラクトバージョンを data_app.yaml で宣言します （version: N。このフィールドがないマニフェストはバージョン 1 です）。Metabase が提供する バージョンを引き上げるのは、そのコントラクトに対する破壊的変更が発生した場合のみです。すなわち、 @metabase/embedding-sdk-react/data-app API、バンドルファクトリー、マニフェスト、 queries/ および actions/ の規約、またはアプリが宣言できる内容のいずれかです。古いバージョンのアプリは、 管理一覧で Outdated と表示され、他のすべてのユーザーからは隠され、 移行されるまで開くことができません。

移行は アップグレード を順にたどる作業です。N -> N+1 -> ... -> M と、一度に 1 つずつ アップグレードを進め、それぞれが references/upgrades/ 内のガイドで説明されています。何もスキップされず、 セッション間で何も記憶されません。アプリ自身のファイルと git 履歴が、すべての 状態を保持しています。

4 つの不変条件

以下のすべての手順は、これらから導かれます。決して破らないでください。

1. version は最後に書きます。 アップグレードの version: N+1 は、 そのアップグレードのすべてのチェックが成功した後にのみ data_app.yaml へ書き込みます。
2. アップグレードごとに 1 コミット、ローカルで。 プッシュは、目標バージョンでの最終ゲートが 合格した後にのみ行います。バージョン行は、1 コミットにつき 1 つを超えて移動することはありません。
3. コンパイラーとビルドのゲートは、目標バージョンでのみ実行します。 インストールされている SDK は目標であるため、複数のアップグレードの途中にあるアプリは、型チェックも ビルドもできません。それらを早めに実行せず、その失敗を早めに「修正」しないでください。
4. 生成されたものは何も手で編集しません。 dist/ は npm run build によって、src/metabase.data.ts は型付きスキーマのエクスポートによって書き込まれ、 決してあなたによって書き込まれることはありません。collections/data_apps/ 配下にある アプリのコレクションのファイルと、その定義が名前を挙げるエンティティ ID（savedQuestionEntityId、 copiedActionEntityId）は、アップグレードガイドがそう指示する箇所でのみ変更されます。 アプリのコレクションのファイルを書く際のデータアプリのガイダンスに従ってください （スキルディスカバリーを使用してください）。

ステップ 0 - アプリを特定してその状態を確認する

アプリのディレクトリ <repo>/data_apps/<slug>/ で作業します。リポジトリのルートは ROOT="$(git rev-parse --show-toplevel)" で解決します。インスタンスのチェックには、 リポジトリルートの .env.local にある認証情報 (DATA_APP_MB_URL、DATA_APP_MB_API_KEY) が必要です。サブシェルでファイルを source し、両方が設定されているかどうかだけを出力して 確認します。ファイルやその変数を決して出力しないでください。このキーは管理者のものである 必要があります。API は version と outdated を管理者にのみ返し、それ以外のすべての ユーザーには古いアプリのメタデータを拒否するため、非管理者のキーではここで何も証明できません。

以下の npm は、アプリ自身のパッケージマネージャー、つまりロックファイル (package-lock.json、yarn.lock、pnpm-lock.yaml、bun.lock) がコミットされている ものを指します。2 つ目のロックファイルを決して導入しないでください。

3 つの数字を読み取ります:

# version committed at HEAD (absent line means 1)
git show HEAD:data_apps/<slug>/data_app.yaml | grep -E '^version:' || echo "version: 1"
# version in the working tree
grep -E '^version:' data_app.yaml || echo "version: 1"
# target: the highest upgrade guide shipped with this skill (no guides means 1)
ls <skill-dir>/references/upgrades/ | sed -nE 's/^v[0-9]+-to-v([0-9]+)\.md$/\1/p' | sort -n | tail -1 | grep . || echo 1

<skill-dir> は、この SKILL.md が読み込まれたディレクトリです。ターゲットは、この スキルと一緒にインストールされた data-app のスキャフォールディングテンプレート (<skills-dir>/*/template/data_app.yaml) の version: と一致していなければなりません (テンプレートが存在する場合)。一致しない場合、スキルは異なる Metabase リリースの ものです。停止し、Admin > Data apps に表示されるコマンドで、すべての data-app スキルを再インストールするようユーザーに伝えてください。回答を待ちます。

次に判断します:

HEAD のバージョン	作業ツリー	行うこと
ターゲットと等しい	クリーン	移行するものはありません。その旨を伝えます。ユーザーが検証を依頼した場合にのみ、最終ゲートを実行します。
ターゲットより上	任意	停止。 ダウングレードはありません。Metabase、SDK、スキルがアプリより古いか、誤ったインスタンスに対してバンプがコミットされています (git log -- data_apps/<slug>/data_app.yaml に表示されます)。回答を待ちます。
ターゲットより下	クリーン	ステップ 1 から開始します。
任意	data_apps/<slug> 配下がダーティ	前回のセッションが中断されました。まず 再開 に進みます。

ステップ 1 - プリフライト (1 回のみ)

1. ターゲットの Metabase リリースに一致する SDK を、アプリの パッケージマネージャーでインストールします (npm install @metabase/embedding-sdk-react@<tag> またはその 同等のもの)。各アップグレードガイドには、それが対象として書かれた dist-tag が記載されています。 ロックファイルの変更は、最終的なアップグレードとともにコミットされます。
2. アプリが現在のバージョンでテンプレートの形になっていることを確認します: vite.config.ts がワンライナーの export default dataAppConfig() であり、src/index.tsx が DataAppFactory をデフォルトエクスポートしていること。そうでない場合は、停止してください。 これはバージョン移行ではなく構造のドリフトです。同じスラッグで新しいアプリを スキャフォールドし (別のタスク: data app を作成するためのスキルディスカバリーを使用)、 src/、queries/、actions/ を移植するか、ユーザーのリスクで続行するかを提案します。 回答を待ちます。
3. 何かを編集する前に、現在のバージョンからターゲットまでのすべてのアップグレード ガイドを読み、後のアップグレードが途中で予期せぬ事態を引き起こさないようにします。

ステップ 2 - アップグレードループ

HEAD バージョンから target - 1 までの各 N について:

1. references/upgrades/v<N>-to-v<N+1>.md を開き、その Preconditions を実行します。
2. ガイドの Steps を順番に適用します。各ステップは機械的で、Done when コマンドで終わります。まずコマンドを実行します。すでにパスしていればそのステップをスキップし、そうでなければ編集を適用して再度実行します。ステップのコマンドだけが、それが実行された唯一の証拠です。読んだだけでステップを完了扱いにしないでください。
3. もしあれば Instance steps を適用します。その Done when は、.env.local の認証情報を使って取得した、接続済みの Metabase からの API レスポンスです:

   ( source "$ROOT/.env.local"; curl -s -H "x-api-key: $DATA_APP_MB_API_KEY" "$DATA_APP_MB_URL/api/apps/<slug>" )
   

4. ガイドの Done-check summary を実行します。すべての行が ok を出力しなければなりません。
5. ここで初めて data_app.yaml の version: N+1 を設定します。この行への編集はこれが唯一です。
6. N+1 < target の場合: リポジトリのルートから、 git add data_apps/<slug> collections/data_apps && git commit -m "Migrate <slug> data app to data-app version N+1" -- data_apps/<slug> collections/data_apps。 パススペックにより、アプリ外でステージされたものはコミットに含まれません。 プッシュも、型チェックも、ビルドも行いません。ユーザーが理由を尋ねたら、最後のアップグレードまでアプリはコンパイルできないと伝えてください。
7. N+1 == target の場合: コミットする前に Step 3 を実行します。

アップグレードをまたいでステップをまとめて行わないでください。項目 5 より前に version に触れないでください。

ステップ 3 - 最終ゲート、ターゲットバージョンのみ

1. npm run typecheck。失敗はアプリ自身のソース内で修正します。どのアップグレードガイドにも言及されていない SDK シンボルを名指しする失敗は、ガイドの欠落であり、ユーザーの問題ではありません。正確なエラーを示し、どのガイドがそれをカバーすべきだったかを伝えて、停止してください。それ以外の場合は、最大 3 回の修正ラウンドを行い、その後停止して質問してください。
2. npm run check-resources、続いて npm run build を実行します。これは、アプリのコレクションファイルが定義を裏付けていない場合にバンドルを拒否します。それぞれのメッセージに従ってください。どちらも Metabase を呼び出しません。
3. npm run dev を実行し、Vite が出力する Local: 行からプレビュー URL を取得します。テンプレートはポート 5174 を要求しますが、そのポートが使用中の場合は Vite が次の空きポートに移動するため、決して想定しないでください。その URL を開き、同じオリジンから診断フィードを一度読み取ります:

   curl -s "<preview-url>/__data-app/diagnostics?startEventId=0"
   

   clients: 1 であり、"alert": true のエントリがないことを期待します。clients: 0 はプレビュータブが開かれていないことを意味するため、空のフィードは何も証明しません。
4. リポジトリのルートから git status を実行すると、アップグレードの編集、data_app.yaml、ビルド済みバンドル、アップグレードで変更された場合はアプリのコレクションファイル、SDK が再ピン留めされた場合はパッケージロックファイルのみが表示されなければなりません。アプリディレクトリ内のそれ以外のものはユーザーの編集です。コミットする前にその旨を伝えてください。
5. リポジトリのルートから、 git add data_apps/<slug> collections/data_apps && git commit -m "Migrate <slug> data app to data-app version M" -- data_apps/<slug> collections/data_apps、 プッシュし、ユーザーに Admin > Data apps の下で Pull changes を行うよう伝えてください。
6. それを証明します。プルの後:

   ( source "$ROOT/.env.local"; curl -s -H "x-api-key: $DATA_APP_MB_API_KEY" "$DATA_APP_MB_URL/api/apps/<slug>" )
   

   は "version": M と "outdated": false を表示しなければなりません。 name と display_name のみを含むレスポンスは、そのキーが管理者のものではないことを意味します。管理者のキーを求めるか、ユーザーに管理者リストを読むよう依頼し、証明はまだ保留中であると伝えてください。コマンドと結果を報告してください。それなしで移行が完了したと主張しないでください。

中断されたマイグレーションの再開

新しいセッションは前のセッションの記憶を持たず、また必要もありません。ステップ 0 から 3 つの数値を読み取り、git status --porcelain -- data_apps/<slug> を実行してから、次に進みます:

tree	作業ツリーのバージョン	意味	実行内容
clean	HEAD と等しい	完了したアップグレードはすべてコミット済み。中途半端な状態はない	HEAD のバージョンからループを続行する
dirty	HEAD と等しい	アップグレード HEAD -> HEAD+1 が進行中で、そのチェックがすべて通過していなかった	そのアップグレードのすべての Done when を再実行する。コマンドが失敗するステップのみを適用する。ループ項目 4 から続行する
dirty	HEAD + 1 と等しい	すべてのチェックが通過し、バンプが書き込まれたが、コミットが欠けている（またはバンプ後に最終ゲートが失敗した）	そのアップグレードの Done-check summary を再実行する（すべて ok、またはバンプ後に誰かが編集した場合は停止して git diff を表示する）。それがターゲットであれば、最終ゲートを実行する。コミットする
any	HEAD + 1 より大きい、または HEAD 未満	不変条件が破られている	停止。 git diff -- data_apps/<slug>/data_app.yaml を表示し、その 1 ファイルを HEAD に戻して再導出するか、ツリーを stash するかを尋ねる。回答を待つ。

data_apps/<slug> の外にあるダーティなファイルはあなたのものではありません。決して git add しないでください。

レポート

アップグレードごとに 1 行、順番に: v1 -> v2: done (commit abc1234) または v2 -> v3: blocked - <失敗する正確な Done-when コマンドとその出力>。 失敗したチェックを決して和らげないでください。tsc の出力は、全体を貼り付けるのではなく、根本原因ごとにグループ化し、代表的な診断をいくつか示してください。

決して行わないこと

• アップグレードのチェックが通過する前に version を設定または編集すること、あるいは一度に 1 つを超えて変更すること。
• アップグレードをスキップすること、または 2 つのアップグレードのステップを一度に適用すること。
• 最後のアップグレードの前に npm run typecheck または npm run build を実行すること、あるいは最終ゲートが通過する前にプッシュすること。
• dist/ や src/metabase.data.ts を手で編集すること、またはアップグレードガイドに記載されている以上の範囲でアプリのコレクションファイルや定義のエンティティ ID を変更すること。
• ステップの Done when を再実行する代わりに、前のセッションのチャットからその結果をコピーすること。
• アップグレードガイドが存在するのに、独自のチェックリストでマイグレーションすること。必要なアップグレード用のガイドが存在しない場合は、停止してその旨を伝えてください。

アップグレードガイド

ガイドは references/upgrades/ にあり、アップグレードごとに 1 つ、v<N>-to-v<N+1>.md という名前です。これらはコントラクトバージョンがバンプされたときに Metabase によって、references/upgrade-guide-template.md のテンプレートから書かれます。references/maintainer-checklist.md はそのプロセスを説明しています。必要なアップグレード用のガイドが欠けていることは、スキルのインストールにおけるバグであり、その場で improvisation すべきものではありません。