feat(dev): Add documentation for new AddMissingIndicesEvent

Signed-off-by: Julius Härtl <jus@bitgrid.net>

Author: juliusknorr

developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_28.rst

@@ -51,6 +51,7 @@ Due to the popularity of CLI tools for development of Nextcloud apps, the likeli
 Added APIs
 ^^^^^^^^^^
 
+* ``\OCP\DB\Events\AddMissingIndicesEvent`` to add missing indices to the database schema.
 * ``\OCP\Mail\IMessage::setSubject`` to set an email subject. See :ref:`email` for an example.
 * ``\OCP\Mail\IMessage::setHtmlBody`` and ``\OCP\Mail\IMessage::setPlainBody`` to set an email body See :ref:`email` for an example.
 * ``\OCP\IEventSourceFactory`` to create a ``OCP\IEventSource`` instance.

developer_manual/basics/events.rst

@@ -446,6 +446,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``
 ************************************************
 

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']);
+      }
+   }