From aaed6b6eb508d755aaa8e70623a2fedfa749efae Mon Sep 17 00:00:00 2001 From: Josh Date: Sun, 23 Aug 2026 23:40:06 -0400 Subject: [PATCH 1/2] docs(admin): document db:schema:check command Documents new command that was added in nextcloud/server#63351 Assisted-by: Copilot:gpt-5.6-sol Signed-off-by: Josh --- admin_manual/occ_database.rst | 93 +++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/admin_manual/occ_database.rst b/admin_manual/occ_database.rst index 5fe40de80bc..27ff97635c0 100644 --- a/admin_manual/occ_database.rst +++ b/admin_manual/occ_database.rst @@ -370,6 +370,7 @@ The ``db`` commands manage database schema, indices, and data conversions:: db:convert-filecache-bigint convert the ID columns of the filecache to BigInt db:convert-mysql-charset convert charset of MySQL/MariaDB to utf8mb4 db:convert-type convert the Nextcloud database to a different type + db:schema:check compare the live database schema with the expected schema db:schema:expected export the expected database schema for a fresh installation db:schema:export export the current database schema @@ -417,6 +418,98 @@ Use ``--dry-run`` to preview the SQL statements without executing them. Schema inspection ^^^^^^^^^^^^^^^^^^ +db:schema:check +""""""""""""""" + +.. versionadded:: 35.0 + +Compare the live database schema with the schema expected for the +currently installed Nextcloud version:: + + sudo -E -u www-data php occ db:schema:check + The live database schema matches the expected schema. + +The expected schema is generated from the migrations provided by +Nextcloud core and all enabled apps. The command reports missing or +unexpected tables, columns, and indexes. It also reports column +properties that differ, such as the type, length, default value, or +whether the column is nullable. + +The command only inspects the schema and does not modify the database. +It exits with status ``0`` if the schemas match and status ``1`` if it +finds differences. This makes it suitable for use in monitoring scripts. + +Specify a table name to limit the comparison to that table:: + + sudo -E -u www-data php occ db:schema:check oc_filecache + +Use the complete table name, including the configured database table +prefix. Use ``--output=json`` or ``--output=json_pretty`` to produce +machine-readable output. For example: + +.. code-block:: console + + $ sudo -E -u www-data php occ db:schema:check --output=json_pretty + [ + { + "table": "oc_filecache", + "type": "modified_column", + "name": "size", + "changes": [ + "type", + "default" + ] + }, + { + "table": "oc_filecache", + "type": "missing_index", + "name": "fs_storage_path_hash" + }, + { + "table": "oc_example", + "type": "unexpected_table" + } + ] + +Each finding contains: + +* ``table`` — the complete database table name. +* ``type`` — one of ``missing_table``, ``unexpected_table``, + ``missing_column``, ``unexpected_column``, ``modified_column``, + ``missing_index``, or ``unexpected_index``. +* ``name`` — the affected column or index. This field is omitted for + table findings. +* ``changes`` — the changed column properties. This field is only + present when ``type`` is ``modified_column``. Possible values include + ``type``, ``length``, ``precision``, ``scale``, ``nullable``, + ``default``, ``autoincrement``, ``unsigned``, ``fixed``, and + ``comment``. + +When the schemas match, JSON output contains an empty array. + +.. note:: + + The expected schema does not account for all database-wide settings + or defaults, so some reported differences may be valid. Tables and + other objects belonging to disabled apps may also be reported as + unexpected. Review each finding before changing the database. + +The schema check also runs automatically after ``occ upgrade``. Any +differences are displayed as warnings but do not cause the upgrade to +fail. For example, the following output may appear near the end of an +upgrade: + +.. code-block:: console + + The database schema does not match what is expected for the installed version: + - oc_filecache: column 'size' differs in: type, default + - oc_filecache: missing index 'fs_storage_path_hash' + - unexpected table 'oc_example' + Run "occ db:schema:check" for details. + +Run ``occ db:schema:check`` separately to inspect the differences in +plain or machine-readable format. + db:schema:export """""""""""""""" From 67da3262244ab7f03c3ac77721634351341b8c06 Mon Sep 17 00:00:00 2001 From: Maksim Sukharev Date: Fri, 4 Sep 2026 15:44:02 +0200 Subject: [PATCH 2/2] docs(admin): update db:schema:check for disabled-app handling Assisted-by: ClaudeCode:claude-sonnet-5 Signed-off-by: Maksim Sukharev --- admin_manual/occ_database.rst | 68 ++++++++++++++++++++++++----------- 1 file changed, 47 insertions(+), 21 deletions(-) diff --git a/admin_manual/occ_database.rst b/admin_manual/occ_database.rst index 27ff97635c0..f49aedde80e 100644 --- a/admin_manual/occ_database.rst +++ b/admin_manual/occ_database.rst @@ -430,14 +430,26 @@ currently installed Nextcloud version:: The live database schema matches the expected schema. The expected schema is generated from the migrations provided by -Nextcloud core and all enabled apps. The command reports missing or -unexpected tables, columns, and indexes. It also reports column -properties that differ, such as the type, length, default value, or -whether the column is nullable. +Nextcloud core, all enabled apps, and any disabled apps whose code is +still present. The command reports missing or unexpected tables, +columns, and indexes. It also reports column properties that differ, +such as the type, length, default value, or whether the column is +nullable. The command only inspects the schema and does not modify the database. -It exits with status ``0`` if the schemas match and status ``1`` if it -finds differences. This makes it suitable for use in monitoring scripts. +It exits with status ``0`` if there are no findings for core or an +enabled app, and status ``1`` otherwise. This makes it suitable for use +in monitoring scripts. Findings that only concern a disabled app never +affect the exit status. They are excluded from the plain output unless +you add ``-v``:: + + sudo -E -u www-data php occ db:schema:check -v + oc_example: column 'size' differs in: type, default + Disabled apps (not affecting exit code): + If the schema for a disabled app differs from what is expected, this might indicate the app was + updated since it was disabled. Missing migrations will be applied once the app is enabled again. + files_external: + - oc_storages: missing column 'backend' Specify a table name to limit the comparison to that table:: @@ -445,7 +457,8 @@ Specify a table name to limit the comparison to that table:: Use the complete table name, including the configured database table prefix. Use ``--output=json`` or ``--output=json_pretty`` to produce -machine-readable output. For example: +machine-readable output. Unlike plain output, JSON output always +includes every finding, including those for disabled apps. For example: .. code-block:: console @@ -458,16 +471,22 @@ machine-readable output. For example: "changes": [ "type", "default" - ] + ], + "app": null, + "enabled": true }, { - "table": "oc_filecache", - "type": "missing_index", - "name": "fs_storage_path_hash" + "table": "oc_storages", + "type": "missing_column", + "name": "backend", + "app": "files_external", + "enabled": false }, { "table": "oc_example", - "type": "unexpected_table" + "type": "unexpected_table", + "app": null, + "enabled": true } ] @@ -484,20 +503,26 @@ Each finding contains: ``type``, ``length``, ``precision``, ``scale``, ``nullable``, ``default``, ``autoincrement``, ``unsigned``, ``fixed``, and ``comment``. +* ``app`` — the ID of the disabled app that owns the affected table, or + ``null`` if the table belongs to core or an enabled app. +* ``enabled`` — ``false`` if the finding only concerns a disabled app + and does not affect the exit status, ``true`` otherwise. When the schemas match, JSON output contains an empty array. .. note:: The expected schema does not account for all database-wide settings - or defaults, so some reported differences may be valid. Tables and - other objects belonging to disabled apps may also be reported as - unexpected. Review each finding before changing the database. + or defaults, so some reported differences may be valid. A table or + other object still counts as unexpected if it belongs to an app that + was disabled and then fully removed. Review each finding before + changing the database. -The schema check also runs automatically after ``occ upgrade``. Any -differences are displayed as warnings but do not cause the upgrade to -fail. For example, the following output may appear near the end of an -upgrade: +The schema check also runs automatically after ``occ upgrade``. +Findings for core or an enabled app are displayed as warnings but do +not cause the upgrade to fail; findings that only concern a disabled +app are not shown here. For example, the following output may appear +near the end of an upgrade: .. code-block:: console @@ -505,10 +530,11 @@ upgrade: - oc_filecache: column 'size' differs in: type, default - oc_filecache: missing index 'fs_storage_path_hash' - unexpected table 'oc_example' - Run "occ db:schema:check" for details. + Run "occ db:schema:check -v" for details. Run ``occ db:schema:check`` separately to inspect the differences in -plain or machine-readable format. +plain (add ``-v`` to include disabled-app findings) or machine-readable +format. db:schema:export """"""""""""""""