diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst
index 8b3ca93ec4c..3e040c9b6f4 100644
--- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst
+++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst
@@ -98,6 +98,11 @@ If you want to support Nextcloud 27 and Nextcloud 28:
 		$eventSource = \OCP\Server::get(IEventSourceFactory::class)->create();
 	}
 
+Added events
+^^^^^^^^^^^^
+
+* ``\OCP\DB\Events\AddMissingIndicesEvent`` to add missing indices to the database schema.
+
 Deprecated events
 ^^^^^^^^^^^^^^^^^
 
diff --git a/developer_manual/basics/events.rst b/developer_manual/basics/events.rst
index 9bb3afa7a2c..2d98328011b 100644
--- a/developer_manual/basics/events.rst
+++ b/developer_manual/basics/events.rst
@@ -453,6 +453,17 @@ It is an event that allows apps to notify other components about an interaction
 
 Emitters should add at least one identifier (uid, email, federated cloud ID) of the recipient of the interaction.
 
+``\OCP\DB\Events\AddMissingIndicesEvent``
+************************************************
+
+.. versionadded:: 28
+
+Event to allow apps to register information about missing database indices
+
+This event will be dispatched for checking on the admin settings and when running
+``occ db:add-missing-indices`` which will then create those indices or can be used
+to generate the SQL statements for manual execution.
+
 ``\OCP\DirectEditing\RegisterDirectEditorEvent``
 ************************************************
 
diff --git a/developer_manual/basics/storage/migrations.rst b/developer_manual/basics/storage/migrations.rst
index 239b50b1e71..2587fbb325c 100644
--- a/developer_manual/basics/storage/migrations.rst
+++ b/developer_manual/basics/storage/migrations.rst
@@ -141,3 +141,20 @@ Nextcloud **in debug mode**:
 
 .. note:: After generating a migration, you might need to run `composer dump-autoload`
    to be able to execute it.
+
+Adding indices
+--------------
+
+Adding indices to existing tables can take long time, especially on large tables. Therefore it is recommended to not add the indices in the migration itself, but to indicate the index requirement to the server by adding a listener for the ``AddMissingIndicesEvent``. This way the migration can be executed in a separate step and do not block the upgrade process. For new installations the index should still be added to the migration that creates the table.
+
+.. code-block:: php
+
+   class AddMissingIndicesListener implements IEventListener {
+      public function handle(Event $event): void {
+         if (!$event instanceof AddMissingIndicesEvent) {
+            return;
+         }
+
+         $event->addMissingIndex('my_table', 'my_index', ['column_a', 'column_b']);
+      }
+   }