Merge pull request #10741 from nextcloud/feat/add-missing-indices-event

feat(dev): Add documentation for new AddMissingIndicesEvent

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
 ^^^^^^^^^^^^^^^^^
 

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``
 ************************************************
 

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