From cb7c18730a0159fbca12d1b9e457d6824515c4bd Mon Sep 17 00:00:00 2001 From: Christoph Wurst <1374172+ChristophWurst@users.noreply.github.com> Date: Tue, 18 Aug 2026 10:22:08 +0200 Subject: [PATCH] feat(devmanual): refine how additional indices should be added The old instructions resulted in missing indices for new setups. Signed-off-by: Christoph Wurst <1374172+ChristophWurst@users.noreply.github.com> --- developer_manual/basics/storage/migrations.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/developer_manual/basics/storage/migrations.rst b/developer_manual/basics/storage/migrations.rst index 70e94431239..e4aaa9af19b 100644 --- a/developer_manual/basics/storage/migrations.rst +++ b/developer_manual/basics/storage/migrations.rst @@ -222,7 +222,7 @@ Show which migrations have been executed and which are pending for an app:: 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. +Adding an index to an existing table can take a long time on large tables, and the migration runs during the upgrade while the instance is in maintenance mode. To keep the index off the upgrade path, do not add it in the migration. Register it with a listener for the ``AddMissingIndicesEvent`` instead, so it is created separately through ``occ db:add-missing-indices``. .. code-block:: php @@ -236,6 +236,13 @@ Adding indices to existing tables can take long time, especially on large tables } } +New installations still need the index from the start. Add it to the migration that creates the table, or, if the index needs a column from a later migration, to the migration that adds that column. This edits an already released migration, so add a comment that the index was added later. Existing installations have already run that migration and get the index from the ``AddMissingIndicesEvent`` instead. + +.. code-block:: php + + // my_index was added later and may not exist until optional indices are created + $table->addIndex(['column_a', 'column_b'], 'my_index'); + Replacing indices -----------------