spree-upgrade

Spree のアップグレード

Spree のアップグレードは、毎回同じ 3 つのステージで行います。

1. gem を更新する — spree* gem に対して bundle update を実行します。
2. スキーマをマイグレーションする — gem から新しいマイグレーションをコピーし（spree:install:migrations）、db:migrate を実行します。
3. データをバックフィルする — rake spree:upgrade により、spree_core 内に同梱されているアップグレードマニフェストに記載された、バージョン固有のデータタスクが実行されます。

その後、手動で 4 つ目のステージを行います。移行するバージョンに対応するアップグレードガイドを確認してください（動作の変更、設定の移動、編集が必要なコード）。rake で実行できる処理だけでは、すべてに対応できません。

5.x から 6.0 に移行しますか？ これは前提条件のある、破壊的変更を伴うメジャーアップグレードです（まず 5.6 にアップグレードし、Rails 8.1 にし、Gemfile を入れ替え、ロールをデータとして扱う必要があります）。始める前に spree-upgrade-5-to-6 スキルをお読みください。

アップグレード方法を選ぶ

プロジェクト	実行方法
create-spree-app（Docker + @spree/cli、server/ 内の Rails アプリ — 古いプロジェクトでは backend/）	spree upgrade
リポジトリのルートに Spree gem がある従来型の Rails アプリ（Docker/CLI なし）	以下のネイティブコマンド
本番環境（どちらの方法でも）	デプロイパイプライン + bundle exec rake spree:upgrade

CLI（create-spree-app）

spree upgrade --plan            # list the backfill steps a run would execute; runs nothing
spree upgrade                   # bundle update spree* → install migrations + db:migrate → rake spree:upgrade

spree upgrade は、bundle update の前とマイグレーションの前に確認を求めます（いずれかをスキップするには No と回答してください）。非対話型の使用では --yes を指定すると確認を省略します。rake によるバックフィルは常に実行されます。

eject 済みの開発スタックが必要です。新規プロジェクトでは、ソースのバインドマウントなしで、ビルド済みの ghcr.io/spree/spree イメージを実行します。そのため、イメージ内で bundle update を実行しても server/Gemfile.lock は更新されず、コピーされたマイグレーションも server/db/migrate/ に反映されません。先に spree eject を実行して（ソースからビルドする compose に切り替えて）から、アップグレードしてください。

CLI はモノレポのエッジプロジェクト（.env で SPREE_PATH が設定されているもの）での実行を拒否します。その場合は、モノレポのルートから pnpm server:* スクリプトを使用してください。

ネイティブ（従来型の Rails アプリ、または CLI なし）

bundle update spree spree_core spree_api spree_emails   # + spree_dashboard and any spree_* extensions you use
bin/rails spree:install:migrations db:migrate
DRY_RUN=1 bundle exec rake spree:upgrade                  # plan
bundle exec rake spree:upgrade                            # run the backfills

CLI のフラグは、rake タスクの環境変数に 1 対 1 で対応します。--plan → DRY_RUN=1、--step <id> → STEP=<id>、--to <x.y> → TO=<x.y>。

rake spree:upgrade の仕組み

• マニフェストは gem 内の spree_core/lib/spree/upgrades/<from>_to_<to>/manifest.yml にあります（ドットはアンダースコアに変換されます：5_6_to_6_0）。各マニフェストには順序付きのステップが記載されています。id、name、task（rake タスク）、notes と、任意で optional: true（タスクが定義されていない場合、たとえば使用していないプロバイダー gem の場合にスキップ）があります。
• 通常の実行では、インストール済みのマイナーバージョン以下を to とするすべてのマニフェストを、古い順に処理します。2 バージョン前のバックフィルをスキップしたアプリも、自動的に追いつけます。
• すべてのステップは冪等である必要があります。アップグレード済みのアプリに対してタスク全体を再実行しても、安全に何も行われない状態になります。これにより、リリースフェーズのコマンドとして安全に実行できます。
• マニフェストにはデータのバックフィルのみが含まれます。bundle update、マイグレーション、cron／定期実行ジョブ、コード変更は含まれません。

インストール済みの gem に含まれる内容を一覧表示します。

spree exec sh -c 'ls "$(bundle info spree_core --path)/lib/spree/upgrades/"'
# classic: ls "$(bundle info spree_core --path)/lib/spree/upgrades/"

まずプランを確認する

spree upgrade --plan                   # or: DRY_RUN=1 bundle exec rake spree:upgrade

実際の実行で処理されるすべてのステップ（id、rake タスク、notes）を、実行順に表示します。プランモードでは実行時と同じマニフェスト選択ロジックを使用します（インストール済みのマイナーバージョン以下を to とするすべてのマニフェスト、または指定した場合は --to 以下のマニフェスト）。何も実行されず、bundle と migrate の前処理もスキップされます。

プランではインストール済みの gemからマニフェストを読み取るため、最初に gem を更新してください。5.6 の bundle には、5.6 → 6.0 のマニフェストは含まれません。

1 つのステップを再試行する

一部の処理が失敗した場合は、原因を修正して、そのステップだけを再実行します（bundle と migrate はスキップされます）。

spree upgrade --step migrate_returns        # or: STEP=migrate_returns bundle exec rake spree:upgrade

ステップ id はプランの出力から確認できます。同じ id が 2 つのマニフェストに存在すると、タスクは中止され、区別するために TO= の指定を求めます。一部のタスクには独自の環境変数（BATCH_SIZE、SKIP_INVALID_ROWS=true など）があり、各ステップの notes に記載されています。同じ方法で渡してください（spree rake spree:upgrade STEP=… BATCH_SIZE=200、または spree exec env BATCH_SIZE=200 bin/rake …）。

基になるタスクを直接実行することもできます。spree rake <task> / bundle exec rake <task> を使うと、どのマニフェストにも含まれていないタスクを実行する場合に便利です。

バージョンの上限を設定する

spree upgrade --to 5.6

to が上限以下のマニフェストが対象になります。次のメジャーバージョンに進む前に、中間のマイナーバージョンに移行する場合に便利です（5.x のアプリは、6.0 に進む前に 5.6 に移行する必要があります）。

対象外のもの

• 拡張機能のアップグレード。 spree upgrade は、インストール済みのすべての spree* gem を更新します（コンテナ内で bundle list --name-only を使って一覧表示します）。ただし、各拡張機能固有のマイグレーション、インストール用ジェネレーター、破壊的変更はご自身で実行する必要があります。CHANGELOG を確認してください。拡張機能には、対象の Spree バージョンと互換性のあるリリースが必要です。そうでない場合、bundle update は依存関係を解決できません。
• 定期ジョブ／設定。 新しいスケジュール済みジョブ（Solid Queue の config/recurring.yml、または Sidekiq／cron の設定）、移動した設定、新しい環境変数は、マニフェストではなくアップグレードガイドに記載されています。
• 独自のコード。 名前が変更または削除された API を参照するデコレーター、サブスクライバー、ワークフローフック、ダッシュボードプラグイン、ストアフロントのコードは、手動で監査する必要があります。このプラグインの /spree:audit-upgrade コマンドは、読み取り専用で準備状況を確認します。
• SDK。 フロントエンドパッケージ（@spree/sdk、@spree/admin-sdk、@spree/dashboard）は、ご自身のパッケージマネージャーで更新してください。CLI はリマインダーとして、「Next steps」パネルに apps/storefront の @spree/sdk バージョンを表示します。

本番環境での実行

spree upgrade は開発用 CLI のため、本番環境では実行しないでください。デプロイ時にはすでに bundle install と db:migrate が実行されます（スターターの Docker エントリーポイントは起動時に bin/rails db:prepare を実行します）。バックフィルをもう 1 つのコマンドとして追加してください。

bundle exec rake spree:upgrade

リリースフェーズコマンド（Heroku）、デプロイ前コマンド（Render）、init コンテナ／Job（Kubernetes）、またはデプロイ後フック（Kamal、Capistrano）として組み込みます。各ステップは冪等性があるため、データの移行後は、デプロイのたびに実行しても安全で、負荷も軽微です。

順序が重要です。マイグレーション → バックフィル → 新しいコードの提供。一部のステップはマイグレーションの安全策であり、一部は後続のマイグレーションより前に実行する必要があります（各ステップの注記に記載されています）。大きなバージョン移行では、メンテナンス時間帯にバックフィルを実行するか、復元したコピーに対して事前に実行し、所要時間を測定してください。複数のタスクが BATCH_SIZE に対応しています。

チェックリスト

1. データベースをバックアップします。
2. 該当するバージョン移行のアップグレードガイドを読みます。node_modules/@spree/docs/dist/developer/upgrades/<from>-to-<to>.md または https://spreecommerce.org/docs/developer/upgrades を参照してください。
3. gem（および拡張機能）を更新し、マイグレーションを実行します。
4. spree upgrade --plan を実行し、各ステップの注記をすべて読みます。
5. バックフィルを実行します。失敗したステップは --step を指定して再実行します。
6. ガイドに記載された手動作業を行い、テストスイートを実行し、SDK を更新します。
7. リリースフェーズで bundle exec rake spree:upgrade を実行してデプロイします。

注意点

• --plan を実行しても何も表示されない（または古いマニフェストしか表示されない）場合は、gem がまだ更新されていません。 プランは、インストール済みの spree_core から取得されます。
• コンテナ内で bundle update が失敗する場合 → 事前ビルド済みイメージを使用しています。まず spree eject を実行するか、bundle の同期を取り直してください（spree bundle install）。
• ステップが意図的に中断する場合があります。 6.0 の複数のタスクは、正確に変換できないデータがあると続行を拒否し（例：migrate_users_to_customers、migrate_returns）、該当する ID と、動作を上書きする環境変数を表示します。メッセージを確認し、何も考えずに再実行しないでください。
• 先のバージョンへ飛ばしてはいけません。 マニフェストは from バージョンのスキーマを前提としています。マイナーバージョンを飛ばすことは問題ありません（移行経路で追いつきます）が、必須の移行先バージョン（6.0 より前の 5.6 など）を飛ばすことはできません。

さらに詳しく知るには

• node_modules/@spree/docs/dist/developer/upgrades/ — バージョン移行ごとのアップグレードガイド
• node_modules/@spree/docs/dist/developer/cli/quickstart.md — spree upgrade のリファレンス
• https://spreecommerce.org/docs/developer/upgrades
• 関連スキル：spree-upgrade-5-to-6、spree-cli、spree-deployment、spree-extensions