アップデート後に発生するNextcloud WebGUIの「データベースエラー」を修正する：実践的な復旧ガイド

Nextcloud WebGUIで、アップデート直後に「例外: データベースエラー」などのメッセージが表示される場合、通常はWebアプリケーションがデータベース層に到達するまでロードされているものの、クエリ、マイグレーション、スキーマ要件、接続、またはアプリケーション固有のデータベース操作のいずれかが失敗していることを意味します。テーブルの削除、Nextcloudの再インストール、または古いコードディレクトリを新しいディレクトリに上書きするなどの操作から始めないでください。より安全な手順は、失敗しているSQLまたはマイグレーションを特定し、サポートされているアップデートパスを完了し、Nextcloudが修復できる部分のみを修復し、アクセスを再開する前にデータベースサービスとスキーマを確認することです。

/var/www/nextcloudこのリファレンスは、2026年10月に公開された最新のNextcloud 35管理ドキュメントに基づいています。以下のコマンドは、Webサーバーユーザーが である一般的なDebian/Ubuntuスタイルのインストールを前提としていますwww-data。ご使用の環境に合わせて、パス、PHPバイナリ、コンテナコマンド、またはHTTPユーザーを調整してください。

迅速な診断：エラーが通常示すもの

1. データベースを変更する前に現在の状態を保持する

アップデート前のバックアップが残っている場合は、そのままにしておいてください。Nextcloudはアップデート前に必ずバックアップを取ることを推奨しており、内蔵のアップデーターバックアップはコードベースをカバーしますが、データベースやデータディレクトリはバックアップしません。最新のデータベースバックアップがない場合は、手動でSQLの変更や復元を行う前に、データベースプラットフォームの通常のバックアップツールを使用してバックアップを作成してください。

応急処置としてダウングレードは避けてください。Nextcloud は、ダウングレードはサポートされておらず、データが破損する可能性があると述べています。ロールバックが必要になった場合、サポートされている復旧方法は、古いバージョンを新規インストールし、対応するバックアップを復元することです。既に移行が開始されているデータベースに古いプログラムファイルをコピーすることは推奨されません。Nextcloudの組み込みアップデーターのドキュメントを参照してください。

2. Nextcloudログでデータベース例外の詳細を確認してください。

ファイルログの場合、デフォルトのログはnextcloud.log設定済みのデータディレクトリ内に保存されます。Nextcloudのトラブルシューティングガイドでは、そのログ、および必要に応じてWebサーバーとPHPのログを確認することを推奨しています。エラーページにリクエストIDが表示されている場合は、そのIDを検索して該当するトランザクションを特定してください。

sudo -u www-data tail -n 100 /var/www/nextcloud/data/nextcloud.log

ログを「データベースエラー」というフレーズだけで済ませないでください。SQLSTATEコード、例外クラス、エラーが発生したテーブルまたは列、スタックトレースに表示されているアプリまたはコアコンポーネントをすべて取得してください。たとえば、「テーブルが存在しません」というエラーは、「接続が多すぎます」や「MySQLサーバーが応答しなくなりました」というエラーとは全く異なります。Nextcloudは、一般的なトラブルシューティングドキュメントで、SQLSTATE形式の一般的なエラーをいくつか紹介しています。

3. アップデートが実際に完了したかどうかを確認します。

組み込みのアップデーターは、まず Nextcloud のコードを置き換えます。データベースとアプリの移行は別のフェーズで行われます。コマンドラインモードでは、アップデーターがocc upgrade自動的に実行されますが、そうでない場合は、移行処理を後で手動で行う必要があります。この違いにより、アップデーターの処理が完了したように見えても、通常の WebGUI でデータベース例外が発生するケースが多数発生します。

cd /var/www/nextcloud
sudo -E -u www-data php occ status

トラブルシューティング中にインスタンスを保護する必要がある場合は、メンテナンスモードを有効にしてください。Nextcloudでは、メンテナンスモードは新規ログインを防止し、アクティブなセッションをロックするため、アップグレードを目的としたモードであると説明しています。

sudo -E -u www-data php occ maintenance:mode --on
sudo -E -u www-data php occ status

4. occ upgrade を使用して、サポートされているデータベースとアプリケーションの移行を完了します。

コードが更新されたにもかかわらず移行が完了しなかった場合は、HTTPユーザーとしてアップグレードコマンドを実行してください。

cd /var/www/nextcloud
sudo -E -u www-data php occ upgrade

コマンドが成功を報告するか、特定のエラーで停止するまで出力を監視してください。失敗した場合は、コマンドを再度実行する前に、その前提条件を修正してください。よくある障害としては、互換性のないアプリケーション、サポートされていないPHP/データベースバージョン、利用できないデータベースサービス、または必要な更新作業を妨げる権限などが挙げられます。移行が失敗している間は、WebGUIを繰り返し更新しないでください。

Nextcloudのアップグレードに関するドキュメントにも、メジャーリリースを飛ばさないように注意喚起されています。メジャーバージョンをまたいでアップグレードする場合は、一度に1つのメジャーバージョンずつアップグレードしてください。

5. 移行の問題が解決したら、Nextcloudの修復ルーチンを実行します。

maintenance:repairNextcloudの修復手順を実行するもので、アップグレード時にも自動的に実行されます。アップデートを中断させた原因を修正した後は、手動で実行するのが適切です。

sudo -E -u www-data php occ maintenance:repair

これは、修復手順が Nextcloud コアとアプリによって提供されるため、SQL ステートメントを作成するよりも安全です。これは の魔法の代替手段ではなく、ダウンしたデータベース サーバーやサポートされていないデータベース リリースを修復するものではありません。このコマンドについては、 Nextcloud システムおよびメンテナンス コマンドのドキュメントocc upgradeを参照してください。

6. データベースサービス、接続設定、およびサポートされているバージョンを確認します。

ログがスキーマではなく接続性の問題を示している場合は、データベースサービスが実行されており、Nextcloud PHP環境からアクセスできることを確認してください。一般的なMariaDBホストでは、次のチェックが役立ちます。

sudo systemctl status mariadb

次に、データベースの種類、ホスト、データベース名、ユーザー、ソケットまたはポートの設定など、データベースの設定を確認してくださいconfig/config.php。Unixソケットのエラーは「そのようなファイルまたはディレクトリはありません」と表示されることがありますが、リモートデータベースはルーティング、DNS、TLS、ファイアウォールルール、認証情報、またはサーバー自体が原因で失敗する可能性があります。

Nextcloudのメジャーアップデート後は、バージョン互換性が重要になります。Nextcloud 35の公式リリースノートによると、MariaDB 10.6とMySQL 8.0はサポート対象外となり、最小要件はMariaDB 10.11 LTSとMySQL 8.4 LTSとなっています。データベースを個別にアップグレードする前に、ご使用のNextcloudメジャーバージョンの要件を必ずご確認ください。詳しくは「Nextcloud 35へのアップグレード」をご覧ください。

7. スキーマのずれを検査し、文書化されている不足している構造のみを追加する

Nextcloud 35 ではdb:schema:check、ライブスキーマを、インストール済みのコアおよびアプリの移行で想定されるスキーマと比較する機能が追加されました。この機能は読み取り専用であり、データベースを変更することなく差異を報告します。

sudo -E -u www-data php occ db:schema:check
sudo -E -u www-data php occ db:schema:check -v

管理概要またはコマンド出力で、オプションの列、インデックス、または主キーが不足していると報告された場合は、ドキュメントに記載されているメンテナンスコマンドを使用してください。

sudo -E -u www-data php occ db:add-missing-columns
sudo -E -u www-data php occ db:add-missing-indices
sudo -E -u www-data php occ db:add-missing-primary-keys

それぞれ、--dry-runSQL をプレビューしたい場合に役立ちます。これらのコマンドは、コア移行の失敗の代替として使用しないでください。db:schema:check予期しないオブジェクトや列プロパティの違いが報告された場合は、変更を加える前に結果を確認してください。Nextcloud では、データベース全体の一部のデフォルト値が、想定されるスキーマ モデルの範囲外であることに注意してください。公式のコマンド リファレンスは、Nextcloud DAV およびデータベース コマンドです。

8. WebGUIを再度開く前に、サードパーティ製アプリの障害を切り分けてください。

スタックトレースに同梱されていないアプリの名前が表示されている場合、そのアプリの移行は新しいサーバーバージョンと互換性がない可能性があります。Nextcloud のトラブルシューティング ガイドでは、アップグレードやトラブルシューティングの際にサードパーティ製アプリや同梱されていないアプリを無効にすることを推奨しています。インストールされているバージョンで利用可能なアプリ コマンドを使用して、疑わしいアプリをコマンドラインから無効にし、再度実行してからocc upgrade、互換性のあるリリースを確認してからアプリを再度有効にしてください。

この分岐は、コアテーブルは正常に見えるものの、例外がベンダーの名前空間や特定のアプリケーションに属するテーブルを指している場合に特に重要です。そのアプリケーションのテーブルを手動で削除すると、アプリケーションがまだ必要としているデータが失われる可能性があるため、危険です。

9. メンテナンスモードを終了し、ログインページ以上のものを確認します。

完了後occ upgrade、修復/スキーマチェックでブロックの問題が表示されなくなり、データベースサービスが安定したら、メンテナンスモードを無効にします。

sudo -E -u www-data php occ maintenance:mode --off

次に、インスタンスを段階的に検証します。ログインページを読み込み、サインインし、ファイルを開き、いくつかのフォルダを参照し、ファイルのアップロード/ダウンロードをテストし、管理設定で警告がないか確認し、最新のnextcloud.logエントリを確認します。また、cronジョブやバックグラウンドジョブが正常に実行されていることも確認してください。ホームページが復旧しただけでは、アプリの移行、ファイル操作、バックグラウンドタスクが正常に動作しているとは言えません。

復旧チェックリスト

• アップデート前のバックアップを保持し、サポート対象外のダウングレードは避けてください。
• nextcloud.logトレースで指定された SQLSTATE およびコンポーネントを含む、完全なデータベース例外を で読みます。
• occ status修復中は、インスタンスの状態を確認し、メンテナンスモードに設定してください。
• occ upgradeサポートされているコアおよびアプリケーションの移行を完了するために実行します。
• データベーステーブルを闇雲に編集するのではなく、まずは最初の具体的な問題点を修正しましょう。
• maintenance:repair根本的な障害が修正された後に実行してください。
• データベースサービスの健全性、接続設定、およびバージョン互換性を確認してください。
• db:schema:checkNextcloud 35 で使用し、db:add-missing-*必要に応じてドキュメントに記載されているコマンドを使用してください。
• トレースログで明らかに問題の原因となっているサードパーティ製アプリが特定された場合は、そのアプリを無効にしてからアップグレードを再試行してください。
• CLIチェックに合格してからメンテナンスモードをオフにし、その後、ファイル、転送、管理者警告、ログ、およびバックグラウンドジョブをテストしてください。

修復ではなく復元すべき場合

データベース自体が破損した場合、移行によってデータが部分的に変更され安全に元に戻せない場合、または必要なテーブルやデータが Nextcloud の外部で削除された場合は、既知の正常で内部的に整合性のあるバックアップから復元してください。データベース、構成、データディレクトリ、およびコードバージョンは、互換性のある復元ポイントに属している必要があります。Nextcloud の有料サポートを受けている場合、または業務上重要なデプロイメントの場合は、破壊的な SQL 操作を行う前に作業を中止し、完全なログエントリ、正確なソースおよびターゲットの Nextcloud バージョン、データベースの種類/バージョン、PHP バージョン、および関連occコマンドの出力を添えてエスカレーションしてください。

基本原則はシンプルです。アップデート後の「データベースエラー」は、SQLを推測する理由にはなりません。ログでエラーの原因を特定し、occ upgrade意図した移行を完了させ、Nextcloud独自の修復ツールとスキーマツールを使用して、インスタンスを再起動する前にデータベースプラットフォームを検証してください。