INTEREST JOURNAL DRUPAL & WEB

Drupal 12 beta2のDB更新を検証:公式手順・失敗時の復元・限定的なPHP救済案

約3,800文字 読了目安:約8分

English ↗
この記事の目次

Drushが使えない場合のDB更新を確かめる

コアCLIとPHPの比較検証 では、Drupal 12.0.0-beta2でキャッシュ再構築などを実行できましたが、この環境のコアCLIにはupdatedbがありませんでした。今回はDB更新について、公式手順で案内されるWebのupdate.phpと、PHPからの限定的な救済案を検証しました。

公式のWeb更新は、認証した管理者で実行できました。途中失敗とバックアップからの復元も確認できています。 PHPの救済案は検証用の処理に限定して確認したもので、公式推奨の更新手順・汎用ツールではありません。

元の環境を複製し、保留中の更新を用意する

2026年11月7日、MacBookのDDEV上でDrupal 12.0.0-beta2/PHP 8.5.12を検証しました。元の環境interest-dr12からDBをエクスポートし、コード・ファイルも複製して、別プロジェクトinterest-dr12-db-labへ復元しています。DB更新は複製側だけで行いました。

元データには保留中のDB更新もpost-updateもありませんでした。この状態で「更新なし」と表示されるだけでは、実際の更新処理の検証になりません。

そこで複製側だけに、検証用モジュールcli_db_labを導入しました。導入後に、検証テーブルを作る更新12001と、完了状態を記録するpost-updateを追加しています。後の失敗試験では、意図的にエラーを起こす12002、その後にフィールドを加える12003と、別のpost-updateも用意しました。

Drupalコア自体を旧版から更新した試験ではありません。 検証用の更新フックで、実行経路・履歴・停止・復元を確認した記録です。

公式手順:認証してupdate.phpを実行する

公式のコア更新手順 ↗ は、DB更新の方法としてDrushとWebのupdate.phpを案内しています。今回は複製環境の/update.phpをブラウザーで開きました。

匿名アクセスでは更新権限が必要と表示され、更新画面には進めませんでした。管理者として認証した後は、必要条件の確認、更新対象の確認、実行、結果表示へ進めています。update_free_accessを有効にして認証を外す方法は使っていません。

画面には検証用モジュールのDB更新とpost-updateの2件が表示されました。実行後は、テーブルが作られ、スキーマ番号が12001に進み、post-updateの完了状態が記録され、保留中の更新はなくなりました。

途中で失敗した場合、何が残るか

次に、12002で検証用テーブルへ1行を書き込んだ後、意図的に例外を発生させました。Web更新の結果画面には失敗が表示され、スキーマ番号は12001のまま、12002と12003は保留中に残りました。後続のフィールド追加と、新しいpost-updateも実行されていません。

一方で、失敗する前に書き込んだ1行は残りました。 このケースでは、更新全体が自動的に取り消されたわけではありません。

原因を調べずに再実行すると、処理によっては途中までの書き込みが重複する可能性があります。更新履歴だけを進めて「完了したことにする」のではなく、エラー内容、実際のDB状態、再実行できる処理かを確認する必要があります。

この失敗は検証用コードで作ったもので、Drupalコアや実在する追加モジュールで同じ障害が起きたという報告ではありません。

救済の基本:更新前のバックアップへ戻す

失敗を確認した後、複製DBを検証前のSQLバックアップから復元しました。検証テーブルがなくなり、スキーマ番号は8000、最初のpost-updateも未実行の状態へ戻ったことを確認しています。ノード60件・ユーザー2件も維持されていました。

今回使ったDDEVの操作は、DBの保存と復元です。次は説明用のパス例で、実行前には対象プロジェクトと保存先を確認します。

# 対象のDDEVプロジェクトを確認する
ddev describe

# Web公開領域の外にある、作成済みの保存先へ保存する
ddev export-db --file=/path/outside-web/db-before.sql.gz

# 今回は複製プロジェクト側でのみ実行。対象DBが置き換わる
ddev import-db --file=/path/outside-web/db-before.sql.gz

DBのSQLバックアップだけでは、コードやアップロードファイルは元に戻りません。実際の復旧では、DBと組み合わせるコード・ファイルの時点もそろえます。今回の試験はコアの版を固定し、複製したコードと検証用フックを管理したうえで行っています。DDEVのコマンド資料 と、公式のDB更新トラブルシューティング ↗ も参照してください。

限定的なPHP救済案:公式推奨の方法ではありません

Webから操作できず、Drushも利用できない場合を考えるため、複製環境でPHPの検証用実装も作成しました。

この実装は、本サイト独自の限定実験です。公式推奨の更新手順・サポートされた汎用CLIではありません。本番環境や任意のモジュールに、そのまま適用するためのコードとして案内するものではありません。

実装はWeb公開領域の外に置き、複製プロジェクトとbeta2に限定しました。対象は検証用モジュールの12001〜12003と、確認済みのpost-updateだけです。対象外の更新や満たせない依存、要件のエラー・警告があれば拒否し、最初に処理予定を確認できる形にしています。

検証に使った主な部品

独自PHPの検証は、PHP 8.5.12上で、Drupalに同梱されている次の部品を利用しました。追加のライブラリは導入していません。

  • Composerのオートローダー:Drupalや依存ライブラリのクラスを読み込みます。
  • Symfony HttpFoundationのRequest:対象サイトのURLを表すリクエストを作り、Drupalの起動へ渡します。
  • Drupalコアの更新API:UpdateKernelで更新用の環境を起動し、DatabaseUpdate::doOne()などで検証用のDB更新・post-updateを処理します。

前回紹介したコアCLIのvendor/bin/drはSymfony Consoleを利用しますが、今回の独自PHPはConsoleのコマンドとして実装したものではありません。

更新履歴をSQLで直接書き換えたり、失敗した処理を飛ばして完了扱いにしたりする方式ではありません。ただし、内部の仕組みを利用していても、それだけで公式の更新手順と同じ範囲・互換性・保守性が得られるわけではありません。

検証用実装にも、実際につまずく点がありました。最初は旧来のREQUIREMENT_ERRORを参照したため、beta2では未定義の定数として停止しました。手元のコアに合わせてRequirementSeverityを使うよう修正しています。古いPHPの例をコピーするだけでは動かないことも、今回確認した制約です。

修正後の実装でも、意図的な更新エラーでは終了コード1で停止し、後続の更新とpost-updateは実行しませんでした。原因となる検証フックを、途中まで書いたデータを考慮して修正した後に再実行すると、残りの更新と2件のpost-updateが成功しています。

完了後は、スキーマ番号12003、検証テーブルの行数1件、後続フィールドあり、保留中の更新・post-updateなしを確認しました。再度実行しても実行対象は0件で、フックが重複実行されないことも確認しています。

この実装では、失敗時にはメンテナンス状態を維持します。成功後も保留中の更新を確認し、最後に明示的に解除しました。一般の更新に適用するなら、長時間のバッチ、複雑な依存、並行実行、別のDB、更新中に変わるサービスなど、今回の単純な検証で扱っていない点が残ります。

方法ごとの結果と使える範囲

方法 今回の結果 位置付け・制約
Webのupdate.php DB更新・post-update成功。意図的な失敗の表示も確認 公式手順で案内される経路。必要な権限・認証を保って実施
コアCLIのupdatedb 前回の一覧で未登録 今回の環境に同名コマンドなし。全Drupal 12環境への断定ではない
Drushのupdatedb 未実行 この環境はDrush未導入。最新の対応可否を再判定した試験ではない
DDEVのDB復元 更新前の状態へ復元成功 復旧手段。DB更新の代用ではなく、コード・ファイルの整合も必要
独自PHPの限定実装 検証フックで停止・原因修正後の成功・再実行0件を確認 公式推奨ではない実験。任意の更新に使える汎用ツールではない

今回確認できたのは、同じbeta2環境で、認証したWeb更新を使えることと、失敗時にはバックアップから戻せることです。PHPの限定実験は、代替を実装する際に必要になる処理を調べるためのものとして位置付けています。

Drupal 11・12の検証とサンプル · CLI比較表 · Drupal 12ベータの検証記録

Drupal 11・12の検証とサンプルへ ↗