frappe-ops-upgrades

バージョンアップグレード

Frappe／ERPNext のメジャーバージョン間のアップグレード、移行の失敗への対処、安全なロールバックに関する完全ガイドです。

バージョン: v14 → v15 → v16

---

クイックリファレンス：アップグレードコマンド

タスク	コマンド
全体を更新	bench update
特定のアプリを更新	bench update --pull --app erpnext
ブランチを切り替え	bench switch-to-branch version-15 frappe erpnext
移行のみを実行	bench --site mysite migrate
移行の準備状況を確認	bench --site mysite ready-for-migration
アップグレード前にバックアップ	bench --site mysite backup
バックアップから復元	bench --site mysite restore /path/to/backup.sql.gz
失敗したパッチを再実行	patches.txt に #YYYY-MM-DD サフィックスを追加

---

判断ツリー：アップグレード戦略

Need to upgrade?
├── Single minor version bump (e.g., v15.10 → v15.20)?
│   └── YES → Run `bench update` directly
├── Major version jump (e.g., v14 → v15)?
│   ├── Have custom apps?
│   │   ├── YES → Test on staging FIRST, check breaking changes
│   │   └── NO → Follow standard upgrade path
│   └── Multiple major versions (v14 → v16)?
│       └── ALWAYS upgrade one version at a time: v14 → v15 → v16
└── Production environment?
    ├── YES → ALWAYS test on staging clone first
    └── NO → Proceed with standard upgrade

---

アップグレード前チェックリスト

メジャーバージョンをアップグレードする前に、必ず以下の手順を完了してください。

1. 完全バックアップ — bench --site mysite backup --with-files
2. ステージング環境でテスト — 本番環境をステージング用の bench に複製し、まずそこでテストします
3. 破壊的変更を確認 — 以下の破壊的変更のセクションを確認します
4. カスタムアプリを監査 — 新バージョンの API 変更に対してカスタムアプリを実行します
5. Python／Node のバージョンを確認 — v15 には Node 18+ が必要です。v16 には Node 24+ と Python 3.14+ が必要です
6. スケジューラーを無効化 — bench --site mysite scheduler disable
7. 保留中のジョブを確認 — bench --site mysite ready-for-migration
8. リリースノートを読む — 各バージョンの GitHub リリースノートを確認します

---

標準的なアップグレード手順

ステップごとの手順

# 1. Backup all sites
bench backup-all-sites

# 2. Switch to target version branch
bench switch-to-branch version-15 frappe erpnext

# 3. Update (pulls code, installs deps, builds, migrates)
bench update

# 4. Verify
bench --site mysite migrate  # if not done by update
bench version                # confirm versions

bench update が実行する処理（順番）

1. すべてのサイトをバックアップ
2. すべてのアプリの最新コードを取得（git pull）
3. Python の依存関係をインストール（pip install）
4. Node の依存関係をインストール（yarn install）
5. 静的アセットをビルド（bench build）
6. すべてのサイトで移行を実行（bench migrate）
7. bench のプロセスを再起動

---

v14 → v15 の破壊的変更

環境要件

要件	v14	v15
Node.js	v14+	v18+
Python パッケージング	setup.py	pyproject.toml

バックエンドの破壊的変更

• db.set() は削除されました — 代わりに doc.db_set() を使用します
• db.sql() のパラメーターは削除されました — as_utf8 と formatted は受け付けられなくなりました
• Singles に対する db.set_value() — 代わりに frappe.db.set_single_value() を使用します
• job_name は非推奨です — enqueue() の job_id パラメーターを使用します
• frappe.new_doc() の引数 — parent_doc、parentfield、as_dict は必ずキーワード引数として指定してください
• frappe.get_installed_apps() — sort 引数と frappe_last 引数は受け付けなくなりました
• メソッドのオーバーライド順序が逆転 — 最後のオーバーライドが優先されるようになりました
• タイムゾーン関数の名称変更 — convert_utc_to_user_timezone → convert_utc_to_system_timezone

フロントエンドの破壊的変更

• Vue 2 → Vue 3 — すべての Vue コンポーネントを移行する必要があります
• ウィンドウのグローバル変数を削除 — get_today → frappe.datetime.get_today、user → frappe.session.user
• クライアントスクリプト内の this — ローカルスコープへのアクセスはサポートされなくなりました
• 画像の遅延読み込み — website-image-lazy クラスをネイティブの loading="lazy" に置き換えます

セキュリティ上の変更

• サーバースクリプトはデフォルトで無効 — 有効化するには bench set-config -g server_script_enabled 1 を実行します
• 「Desk User」ロールを追加 — Desk ユーザーの権限では「All」ロールに代わって使用されます
• currentsite.txt を削除 — bench use sitename または FRAPPE_SITE 環境変数を使用します

削除された機能

• Event Streaming は別のアプリに移動しました
• Cordova のサポートを削除しました
• setup.py を削除しました（pyproject.toml を使用してください）
• --make_copy と --restore のビルドフラグを削除しました（--hard-link を使用してください）

一覧は breaking-changes.md を参照してください。

---

v15 → v16 の破壊的変更

環境要件

要件	v15	v16
Node.js	v18+	v24+
Python	3.10+	3.14+

バックエンドの破壊的変更

• デフォルトのソート順が変更されました — すべてのリストクエリで、modified ではなく creation を使用します
• has_permission フック — 明示的に True を返す必要があります。None は受け付けられなくなりました
• frappe.get_doc(doctype, name, field=value) — 値を更新しなくなりました
• ドキュメントフック内の DB コミット — データ整合性の問題を防ぐため、許可されなくなりました
• frappe.sendmail(now=True) — トランザクションを暗黙的にコミットしなくなりました
• Singles に対する db.get_value() — 文字列ではなく、適切な型を返すようになりました
• 状態を変更するメソッドには POST が必要です — /api/method/logout、/api/method/upload_file など

分離されたモジュール（個別にインストール）

• Energy Points → frappe/eps
• Newsletter → frappe/newsletter
• Backup Integrations → frappe/offsite_backups
• Blog → frappe/blog

フロントエンドの破壊的変更

• Report／Dashboard／Page の JS は IIFE として評価されます（グローバルスコープを汚染しません）
• Awesome Bar が再設計され、サイドバーに移動しました（Cmd+K）
• リストビューの右サイドバーが削除されました
• /apps エンドポイントは非推奨になりました。/app は /desk にリダイレクトします

設定の変更

• サイト設定は最大 1 分間キャッシュされます（変更はすぐには反映されません）
• Country フィールドには、有効な ISO 3166 ALPHA-2 コードが必要です
• bench version の出力形式が「plain」に変更されました（以前の形式を使うには -f legacy を指定します）
• override_doctype フッククラスは、オーバーライド対象のクラスを継承する必要があります

完全な一覧については、breaking-changes.md を参照してください。

---

パッチシステム

パッチの仕組み

パッチは、bench migrate の実行時に実行される一度限りのデータ移行スクリプトです。各アプリの patches.txt ファイルで定義します。

patches.txt の形式 [v14+]

[pre_model_sync]
# Runs BEFORE schema sync — use for data prep
myapp.patches.v15_0.prepare_data_for_migration

[post_model_sync]
# Runs AFTER schema sync — use for data that needs new schema
myapp.patches.v15_0.migrate_data_to_new_fields

パッチの実行ルール

• パッチは patches.txt に定義された順序で実行されます
• 各パッチは厳密に 1 回だけ実行され、__patches テーブルで追跡されます
• パッチを再実行するには、日付コメントを追記します：myapp.patches.v15_0.fix #2025-03-20
• 一度限りのステートメント：execute:frappe.delete_doc('Page', 'old_page', ignore_missing=True)

パッチの作成

# myapp/patches/v15_0/migrate_field_data.py
import frappe

def execute():
    # ALWAYS reload if you need the NEW schema
    frappe.reload_doc("module_name", "doctype", "doctype_name")

    # Perform data migration
    frappe.db.sql("""
        UPDATE `tabSales Invoice`
        SET new_field = old_field
        WHERE old_field IS NOT NULL
    """)

停止したパッチのデバッグ

# Check which patches have run
bench --site mysite console
>>> frappe.db.sql("SELECT * FROM __patches WHERE patch LIKE '%stuck_patch%'")

# Remove a patch record to force re-run
>>> frappe.db.sql("DELETE FROM __patches WHERE patch = 'myapp.patches.v15_0.broken_patch'")
>>> frappe.db.commit()

# Then re-run migrate
bench --site mysite migrate

---

ロールバック手順

即時ロールバック（数時間以内）

# 1. Stop all processes
bench stop

# 2. Restore database from pre-upgrade backup
bench --site mysite restore /path/to/pre-upgrade-backup.sql.gz \
  --with-public-files /path/to/files.tar \
  --with-private-files /path/to/private-files.tar

# 3. Switch back to previous version branch
bench switch-to-branch version-14 frappe erpnext

# 4. Install old dependencies
bench setup requirements

# 5. Build old assets
bench build

# 6. Start bench
bench start  # or: sudo bench restart (production)

ロールバックに関する重要なルール

• 必ず、アップグレード前のバックアップを少なくとも 7 日間保持してください
• 古いブランチに復元した後は、決して bench migrate を実行しないでください — スキーマはすでに適切な状態です
• 必ず、データベースと一緒にファイルも復元してください — そうしないと、ファイル参照が壊れる可能性があります
• アップグレード後のバージョンでユーザーが新しいデータを作成した後は、決してロールバックしないでください

---

Frappe パッケージ：サイト間でカスタマイズを移動する

Frappe Packages（v14+）は、UI で作成する軽量なアプリケーションです。.tar.gz 形式の tarball として配布される Custom Module Def のバンドルです。標準 DocType の Custom Fields、Property Setters、DocPerms には、代わりに Fixtures を使用してください。

クイックリファレンス：Package、Fixtures、App の比較

仕組み	使用する場面	CLI コマンド
Package	UI で作成する DocType、Script、Web Page	UI のみ（Package Import/Release）
Fixtures	Custom Fields、Property Setters、DocPerms	bench --site mysite export-fixtures
Frappe App	完全な開発ワークフロー、CI/CD、テスト	bench get-app、bench install-app

Package のワークフロー（UI ベース）

1. Package ドキュメントを作成し、Custom Module Def を割り当てます
2. Package Release を作成すると、[bench]/sites/[site]/packages/ に [package]-[version].tar.gz としてエクスポートされます
3. 移行先のサイトで Package Import を作成し、tarball を添付して、Activate にチェックを入れます
4. システムはアプリの移行と同様にデータを移行します。既存のファイルを上書きするには Force を使用します

Fixtures のワークフロー（CLI ベース）

# hooks.py — define what to export
fixtures = [
    "Custom Field",
    "Property Setter",
    {"dt": "Client Script", "filters": [["module", "=", "My Module"]]}
]

# Export fixtures to JSON in your app
bench --site mysite export-fixtures --app myapp

# Fixtures auto-sync on: bench --site mysite migrate

標準／コアの DocType の変更には、決して Packages を使用しないでください。Fixtures を備えた Frappe App を使用してください。

判断ツリー、制限事項、ベストプラクティスを含む完全なリファレンスについては、frappe-packages.md を参照してください。

---

カスタムアプリの互換性チェック

アップグレードする前に、各カスタムアプリを監査してください。

1. 非推奨の API を確認する — 破壊的変更に記載されている削除済み関数を検索します
2. setup.py を確認する — v15 以降では pyproject.toml への移行が必要です
3. Vue コンポーネントを確認する — v15 以降では Vue 3 との互換性が必要です
4. patches.txt を確認する — パッチで [pre_model_sync]／[post_model_sync] セクションが使用されていることを確認します [v14+]
5. hooks.py を確認する — 削除済みのフックが使用されていないことを確認します
6. テストを実行する — bench --site test_site run-tests --app myapp

---

判断フロー：インプレースアップグレードと新規インストール

Choosing upgrade strategy:
├── Small site (< 10 GB database)?
│   └── In-place upgrade is usually fine
├── Large site (> 50 GB database)?
│   ├── Many custom apps? → Fresh install + data migration
│   └── Standard apps only? → In-place with extended downtime window
├── Skipping multiple versions (v13 → v15)?
│   └── ALWAYS fresh install — sequential upgrades are too risky
└── Critical production with zero-downtime requirement?
    └── Fresh install on parallel server + DNS switch

---

バージョンの違いの概要

機能	v14	v15	v16
Python パッケージング	setup.py	pyproject.toml	pyproject.toml
Vue のバージョン	Vue 2	Vue 3	Vue 3
Node.js の最小バージョン	v14	v18	v24
Python の最小バージョン	3.8	3.10	3.14
サーバースクリプト	有効	デフォルトで無効	無効
デフォルトの並べ替え	modified	modified	creation
patches.txt のセクション	あり	あり	あり
ワークスペースのサイドバー	なし	なし	あり
分離されたモジュール	—	Event Streaming	Blog, Newsletter, EPS

---

参考ファイル

ファイル	内容
examples.md	アップグレードのワークフローの完全な例
anti-patterns.md	よくあるアップグレードの誤りと修正方法
breaking-changes.md	バージョンごとの破壊的変更の詳細
frappe-packages.md	パッケージ、フィクスチャ、およびサイト間でのカスタマイズの移行