2026年11月6日、当社で運用しているDrupalサイトをDrupal 11へアップグレードしました。今回は、Codexと対話しながら、調査、コード修正、テスト、本番移行までを進めました。
Codexが実際の環境を調べ、コード修正や検証を繰り返し、人間が方針や本番に影響する操作を判断する進め方です。この記事では、その過程で分かったことをまとめます。
1. 既存のデータと機能を保ったまま更新する
既存のコンテンツや添付ファイルに加え、勤務表、申請ワークフロー、カレンダー、SSOなどの機能を使い続けることが前提でした。
主な変更は次のとおりです。
- Drupal：10.1.8 → 11.4.11
- PHP：8.2.35 → 8.4.27
- 関連モジュール：Drupal 11やPHP 8.4に合わせて更新・互換性を調整
PHPの更新後には、公式情報と実際の稼働状況を照合しました。CLIのバージョンに加え、Webリクエストを処理するPHP-FPMのバージョンと、古いワーカーが残っていないことも確認しています。
データベースエンジンは既にMySQL 8.4系だったため、その更新は行わず、Drupal側のデータベース更新とは分けて扱いました。
まずCodexに既存の構成、Composerの依存関係、カスタムモジュール、外部サービスとの連携を調べてもらいました。その情報をもとに、維持する機能と更新する範囲を決めました。
2. 一度に更新せず、段階を分ける
DrupalとPHP、関連モジュールを一度に切り替えると、失敗したときに原因を絞りにくくなります。今回は次の順序で進めました。
- PHP 8.2のまま、Drupalを10.6系へ更新する。
- Drupal 10.6系の状態で、PHP 8.4と関連モジュールを更新する。
- Drupal 11.4系へ更新する。
各段階で依存関係を固定し、データベース更新とキャッシュ再構築を確認しました。本番には、検証したものと同じcomposer.lockを使って依存パッケージを導入しています。
Drupal 11へ移るときには、データベース更新を先に実行する順序も重要でした。この環境では、更新前にキャッシュ再構築を行うと、新旧のテーブル定義の違いで失敗するためです。
段階を分けることは、Codexに作業を依頼するときにも役立ちました。「次の段階へ進んでよい状態」を、コマンドの成功だけでなく、保留更新や画面表示まで含めて確認できるからです。
3. カスタムモジュールは、警告と実際の動作の両方を見る
コアや公開モジュールを更新するだけでは、既存のカスタムコードの互換性は確認できません。PHPStanやUpgrade Statusの結果、実際のログ、画面操作を合わせて調べました。
今回修正した例には、次のようなものがあります。
- PHPのプロパティ宣言や例外クラスの名前空間の不整合
- フォームの戻り値や入力値の扱い
- JavaScriptライブラリへの古い依存と、Ajax処理に合わせた検索条件の保存
- 既存カレンダー連携ライブラリのPHP互換性
- Linux上で問題になる、ルート設定とクラス名の大文字・小文字の違い
Codexがコードを直したあとに画面を確認すると、静的解析だけでは見つからなかった問題もありました。検索条件の保存では、通常のクリックとDrupalのAjaxが処理を始めるタイミングの違いが影響していました。修正案を出して終わりにせず、ブラウザで再現し、保存・再読み込み・復元まで確認する必要がありました。
Upgrade Statusについては、検査対象のバージョンにも注意が必要です。Drupal 11へ移行したあとの表示には、次のDrupal 12に向けた警告が含まれていました。今回必要な修正と、将来のメジャーアップグレード向けの情報を分けて扱っています。移行前に対象バージョンの互換性を確認することが大切です。
4. Codexが作った修正も、別の方法で確かめる
検証環境では、移行向けのPHPUnitテスト48件・109アサーションと、JavaScriptテスト5件が成功しました。静的解析の結果も確認し、既存の指摘と今回の変更に関係する問題を分けて管理しました。
さらに、次のような確認を行っています。
- 勤務表の入力・保存と再表示
- 申請ワークフローの操作
- Paragraphsを使った既存コンテンツの編集
- 公開ファイルと非公開ファイルのアクセス権
- カレンダーへの読み取り接続
- 検証環境でのSSO認証と、既存ユーザーの対応関係
メールや通知は、検証中に実際の利用者へ送られないよう制御しました。また、検証で追加したデータは検証環境にとどめ、本番へ持ち込まない方針にしています。
単体テスト、画面操作、外部サービスとの接続確認は、それぞれ別の結果として記録しました。単体テストが通ったことを、業務全体の確認が完了したことと混同しないためです。
5. 本番切り替えでも、環境の違いが見つかった
検証で成功した手順でも、本番では追加の調整が必要でした。
一つは、Drushが起動する子プロセスへの環境変数の引き継ぎです。親プロセスでは動いていても、子プロセスでは設定値の読み込み方が異なり、更新処理を開始できませんでした。PHPの環境変数読み込み設定を調整してから、同じ段階の処理を再実行しました。
もう一つは、ロードバランサーのヘルスチェックです。Webサイトのドメインでは正常に表示できても、ヘルスチェックで使われるHostが旧サーバー向けの設定に残っていると、新サーバーは正常と判定されません。移行先に合わせて調整し、正常性を確認してから公開先を変更しました。
このように、Codexが手順を作ったことと、その手順が本番環境で成立することは別です。実際の応答とログを見ながら進める必要がありました。
6. 本番移行で確認したこと
本番では、スナップショットとデータベースのバックアップを用意し、書き込みを止めてから最終同期を行いました。ファイルは事前に同期しておき、停止中は差分を転送したうえで、内容のハッシュ一致を確認しています。
Drupalの更新後は、コンテンツ、ユーザー、添付ファイル、Paragraphsの主要件数と、保留中のデータベース更新がないことを確認しました。その後に公開先を変更し、トップページ、勤務表、月間カレンダー、申請書一覧などの表示とログを確認しました。
最終切り替え時のメンテナンス時間は約22分でした。 調査・修正・事前検証はこの前に行っており、22分は最終切り替え時の停止時間です。
また、データベースの構造を更新したあとは、接続先だけを旧サーバーへ戻しても切り戻しは完了しません。コードとデータベースの両方を考えた復旧手順と、切り替え後に増えたデータを保全する方針も必要です。
7. Codexに任せる作業と、人間が判断すること
今回、Codexは依存関係の調査、コード修正、テストの追加・実行、ブラウザでの確認、ログの調査、移行手順や実施記録の整理を担当しました。人間は更新対象や進め方を決め、本番への影響や一時的なアクセス経路などを確認・承認しました。
役立ったのは、短い指示から調査と実行をつなげ、エラーが出たときにも、その結果をもとに次の確認へ進められたことです。一方で、依頼範囲、検証の完了条件、本番操作の境界を明確にしておくことは欠かせません。
Codexによる提案も、実際のバージョン、公式情報、テスト結果、画面やログで確かめる。その繰り返しが、今回のアップグレードの進め方でした。
おわりに
既存のDrupalサイトを更新する作業には、パッケージの更新以外にも、カスタムコード、外部連携、データ、運用設定の確認が伴います。Codexはその一連の作業を進めるパートナーになりました。
今回の経験から、Codexを使う場合も、段階を分けた更新、独立した検証、切り戻しの準備が重要だと分かりました。実行結果を追える形で記録し、人間の判断と組み合わせることが、既存システムを保ちながら更新を進めるうえで役立ちます。
参考資料
本記事は2026年11月6日の作業記録をもとに、Codexの支援でまとめたものです。バージョンや確認結果は、この作業時点の情報です。
- 閲覧数 20
コメントを追加