> For the complete documentation index, see [llms.txt](https://summerain-1.gitbook.io/summerain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://summerain-1.gitbook.io/summerain/ja/yzgaidoto/migrations.md).

# データベースマイグレーション

v2.0.3 以降、サーバー起動時のすべての MySQL ブートストラップ処理は `repository.BootstrapDatabase(ctx, db)` が管理します。ブートストラップの エラーはすべて致命的であり、サーバーはトラフィックを受け付ける前に終了します。

ブートストラップは 1 本の物理 SQL 接続を占有し、その接続上でデータベーススコープの MySQL アドバイザリーロックを取得し、すべてのステージが完了するまで両方を保持します。 ロック保持中に次の処理を行います。

1. `schema_migrations` を作成または読み込み、バージョンの連続性、既知のバージョン、 不変の SHA-256 チェックサムを検証する。
2. 適用済みの操作に対応するすべてのオブジェクトが存在することを確認する。これには、 記録済みの列、インデックス、テーブル、および容量ロックのシード行が含まれる。
3. 存在する場合は、互換性のない旧式アクセストークンのデータと列を削除する。
4. GORM ベースラインスキーマを適用する。
5. 不足しているチェックサム付き操作をバージョン順に適用する。列またはインデックスを 追加する前に `information_schema` を確認し、そのバージョンのすべての操作が 成功した後に限りバージョンを記録する。
6. 既存値を上書きせずに、必要なデフォルト設定を登録する。

マイグレーション台帳と適用済みオブジェクトの検証は、破壊的な旧式処理より前に完了します。 記録済みオブジェクトの欠落、チェックサムの不一致、未知のバージョン、バージョンの空白、 DDL 失敗、またはデフォルト設定の登録失敗は、すべて起動を中止させます。 ブートストラップが戻るときにアドバイザリーロックは解放されます。

MySQL の DDL は暗黙的にコミットされます。そのため、チェックサム付きマイグレーションのすべての操作は追加型で、 中断後に安全に再試行できなければなりません。ただし、ブートストラップは MySQL が 既にコミットした DDL のトランザクションロールバックを保証しません。報告された問題を修正し、 ブートストラップを再実行してください。適用済みマイグレーションは決して編集せず、 より大きいバージョンを追加してください。破壊的な名前変更、列削除、テーブル削除には 個別の互換性計画とロールバック計画が必要であり、チェックサム付き V2 マイグレーションには 意図的に含めていません。旧式アクセストークンのクリーンアップは、この追加型マイグレーション一覧の 外側にある専用の互換性ステージです。

## 本番環境向け SQL の生成

`scripts/generate-sql-migration.sh` は、モデルとチェックサム付きマイグレーションが 生成するスキーマを、このディレクトリ内の明示的なスナップショット （例：`20261003_122900_baseline_schema.up.sql`）として書き出します。

```bash
./scripts/dev-wsl.sh deps-up
bash scripts/generate-sql-migration.sh baseline_schema
bash scripts/generate-sql-migration.sh --verify backend/migrations/<file>.up.sql
```

このコマンドは `SUMMERAIN_SCHEMA_DSN`（既定値 `root:summerain-dev@tcp(127.0.0.1:13306)/`）上に使い捨てデータベースを作成して 削除するだけで、既存のデータベースには一切触れません。生成されたファイルは受け入れ前に 必ず検証されます。空のデータベースにファイルを適用したうえで、その後のブートストラップが スキーマを変更しないことを確認するため、スナップショットがモデルとすべての チェックサム付きマイグレーションに一致することが証明されます。`SUMMERAIN_SCHEMA_DSN` を設定すると、`go test ./cmd/schema-migration-gen/...` が同じ検査を実行します。

本番環境でこのリリースを起動する前に、スナップショットを空のデータベースへ適用してください。 サーバー起動時には引き続きスキーマの検証とマイグレーション台帳の記録が行われます。 その契約の外側で列やテーブルを追加することはないため、不完全または曖昧な復元は 本番データを黙って変更せず、早期に失敗します。既存のデータベースは、上記の追加型 チェックサム付きランナーで引き続きアップグレードされます。スナップショットは コミット後に変更できません。スキーマを変更するたびに現在のスキーマを再生成し、 日付付きの新しいファイルをコミットしてください。

## v2.0.3 への初回アップグレード

最初の v2.0.3 インスタンスを起動する前に、v2.0.2 以下のすべてのバックエンドインスタンスを 停止してください。新旧バイナリーが重なって実行されるローリングデプロイは行わないでください。 旧バージョンは、現在 `BootstrapDatabase` が所有するアドバイザリーロックの外側で、 旧式クリーンアップ、ベースラインマイグレーション、およびデフォルト設定の登録を実行する可能性があります。 1 つの v2.0.3 インスタンスがブートストラップを正常に完了した後は、残りの v2.0.3 インスタンスを 通常どおり起動でき、同じロックによって直列化されます。

現在のバージョン：

* `2026071501`：`images` に V2 パイプラインのメタデータとインデックスを追加する。
* `2026071502`：V2 バリアント、アップロードセッション/パート、処理ジョブ、 トランザクショナルアウトボックスの各テーブルを作成する。
* `2026071601`：バックエンドインスタンス間でグローバルアップロード容量の予約を 直列化するための単一行を追加する。
* `2026071602`：ストレージ参照検索用インデックスと、上限付き制御プレーン保持 インデックスを追加する。
* `2026071603`：リモートバックエンド、エンドポイント、バケットの系統情報を保持する列とインデックスを 追加する。履歴行は独立した移行ツールのため未分類のままとし、サーバー起動時に ストレージターゲットを推測することはない。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://summerain-1.gitbook.io/summerain/ja/yzgaidoto/migrations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.