Index locking is still required for ServiceControl 6.20.0 to 6.21.0

servicecontrol/ravendb/search-engine.md

@@ -1,7 +1,7 @@
 ---
 title: RavenDB search engine
 summary: Selecting Corax or Lucene as the search engine for ServiceControl and how to migrate existing indexes between them
-reviewed: 2026-10-02
+reviewed: 2026-10-05
 component: ServiceControl
 related:
 - servicecontrol/ravendb/accessing-database
@@ -29,6 +29,8 @@ Meanwhile, Corax demonstrated more performance and stability issues on large Ser
 
 As the table above illustrates, upgrading ServiceControl does not impact the search engine of existing databases. This is because changing the engine triggers a full rebuild of every index which, depending on the available computing power, can take days on very large databases. In addition, while the rebuild runs, the ingestion and indexing rates are degraded. Thus, migration should be planned and scheduled for each environment. See [Should existing indexes be migrated?](#should-existing-indexes-be-migrated) and [Migrating existing indexes to Lucene](#migrating-existing-indexes-to-lucene) for more details.
 
+From version 6.21.1, indexes that ServiceControl creates in an existing database also use Lucene. For example, this applies to an index that a new version adds, or to the audit message index that is created when [full-text search on message bodies](/servicecontrol/audit-instances/configuration.md#performance-tuning-servicecontrol-auditenablefulltextsearchonbodies) is turned on or off. Indexes that exist already keep their search engine.
+
 > [!NOTE]
 > Monitoring instances do not use RavenDB and are not affected.
 
@@ -66,10 +68,10 @@ Instances without these symptoms should be migrated in the next planned maintena
 
 ## Migrating existing indexes to Lucene
 
-The migration is performed per index in RavenDB Studio. 
+Do the migration for each index in RavenDB Studio.
 
 > [!IMPORTANT]
-> On ServiceControl versions before 6.20, the migrated index must also be **locked** afterward. These versions recreate their index definitions at every start-up and will reset the index to the database default (Corax) and trigger another rebuild otherwise.
+> On ServiceControl versions before 6.21.1, also **lock** the migrated index, see [step 4](#migrating-existing-indexes-to-lucene-lock-the-index).
 
 The indexes with the highest load, and therefore the ones that benefit most, are:
 
@@ -111,19 +113,50 @@ In the **List of Indexes**, the index shows the replacement being built. Once th
 ### 4. Lock the index
 
 > [!NOTE]
-> Locking the index is required to keep a non-default index configuration on ServiceControl versions prior to 6.20.0. On version 6.20.0 and later, this step can be skipped.
+> The lock is necessary on ServiceControl versions before 6.21.1. Those versions deploy their index definitions at each start-up. Without the lock, they reset the index to the database default, Corax, and start another rebuild.
+>
+> From version 6.21.1, this step is not necessary. ServiceControl keeps the search engine configured on an index when it updates its index definitions at start-up. An unlocked index receives definition changes from new ServiceControl versions and stays on Lucene.
 
 While still in RavenDB Studio, click the `🔓 Unlocked` button of the migrated index and change it to `🔒 Locked (ignore)` ([lock modes](https://ravendb.net/docs/article-page/7.0/csharp/client-api/operations/maintenance/indexes/set-index-lock#lock-modes)). RavenDB Studio confirms with _Lock mode was set to: Locked (ignore)_.
 
 A locked index is left untouched when ServiceControl recreates its index definitions at start-up, so the index stays on Lucene.
 
 > [!WARNING]
-> Locking an index also means that index definition changes shipped with future ServiceControl versions are not applied to it. Check the upgrade guide of each new version for changes to the locked indexes; if an index definition changes, unlock the index, let ServiceControl update it, and repeat this migration for it.
+> A locked index does not receive index definition changes from new ServiceControl versions. Check the upgrade guide of each new version for changes to the locked indexes. If an index definition changes, unlock the index, let ServiceControl update it, and do this migration again for it.
 
 ### 5. Restart the instance
 
 Stop maintenance mode or start the ServiceControl container. The next start-up no longer logs a warning for the migrated index, and the `Error Database Search Engine` / `Audit Database Search Engine` custom check passes once all indexes use Lucene.
 
+## Index reset to Corax after unlocking
+
+On versions 6.20.0 and 6.21.0, ServiceControl resets an unlocked migrated index at the next start-up. RavenDB then builds a replacement index with the name `ReplacementOf/<index>` that uses Corax. When the replacement is no longer stale, RavenDB swaps it in, and the Lucene configuration is lost. On a large database the rebuild takes a long time, so the replacement can stay in the list for hours or days.
+
+To find the state of the index, open the **List of Indexes** in RavenDB Studio.
+
+### The replacement is not swapped in yet
+
+`ReplacementOf/<index>` is in the list and the migrated index shows Lucene.
+
+On version 6.21.1 and later:
+
+1. Make sure that the migrated index is unlocked. RavenDB ignores definition updates to a locked index.
+2. Start the instance. ServiceControl keeps the Lucene search engine configured on the migrated index. RavenDB discards the Corax replacement and does not rebuild the migrated index.
+
+On versions 6.20.0 and 6.21.0:
+
+1. Stop the instance. For a Windows deployment, use [maintenance mode](/servicecontrol/ravendb/accessing-database.md#windows-deployment-maintenance-mode).
+2. Keep the migrated index unlocked and delete the `ReplacementOf/<index>` index in RavenDB Studio. Do the delete before the lock: while the migrated index is locked, the delete can have no effect.
+3. On Windows, restart RavenDB before you continue. RavenDB can keep files of a deleted replacement index open until it restarts. For a Windows deployment, stop maintenance mode and start it again right away. Do not start the instance in between.
+4. Make sure that `ReplacementOf/<index>` is not in the list.
+5. Lock the migrated index as described in [step 4](#migrating-existing-indexes-to-lucene-lock-the-index).
+6. Reload the **List of Indexes** and make sure that the migrated index shows `🔒 Locked (ignore)`.
+7. Start the instance.
+
+### The replacement is swapped in
+
+`ReplacementOf/<index>` is not in the list and the index shows Corax. Do the [migration](#migrating-existing-indexes-to-lucene) again for the index. On versions 6.20.0 and 6.21.0, also lock the index. On version 6.21.1 and later, the lock is not necessary.
+
 ## Migrating the whole database
 
 Instead of migrating indexes one by one, the database default can be changed so that all indexes, including future ones, use Lucene without locking:

servicecontrol/upgrades/6.19to6.20.md

@@ -1,7 +1,7 @@
 ---
 title: Upgrade ServiceControl from Version 6.19 to Version 6.20
 summary: Instructions on how to upgrade ServiceControl from version 6.19 to 6.20
-reviewed: 2026-09-17
+reviewed: 2026-10-05
 isUpgradeGuide: true
 component: ServiceControl
 ---
@@ -34,6 +34,17 @@ Yes. Migration is recommended to avoid performance and stability issues as the d
 
 Instances without these symptoms should be migrated in the next planned maintenance window. Migrate development and test instances first to estimate the rebuild duration for production. See [Should existing indexes be migrated?](/servicecontrol/ravendb/search-engine.md#should-existing-indexes-be-migrated) for guidance on planning the migration and the [migration procedure](/servicecontrol/ravendb/search-engine.md#migrating-existing-indexes-to-lucene) for the steps.
 
+## Audit message index definition changed
+
+Version 6.20 changes the definition of the audit instance index `MessagesViewIndex`. When [full-text search on message bodies](/servicecontrol/audit-instances/configuration.md#performance-tuning-servicecontrol-auditenablefulltextsearchonbodies) is enabled, the index is `MessagesViewIndexWithFullTextSearch`. At the first start-up after the upgrade, RavenDB builds the new definition as a replacement index next to the existing index. When the replacement is no longer stale, RavenDB swaps it in. On a large audit database, the rebuild takes time. Ingestion and indexing rates are lower during the rebuild. Plan the upgrade of audit instances in a maintenance window.
+
+On versions 6.20.0 and 6.21.0, the rebuilt index uses the search engine of the database. For databases created before version 6.20, this is Corax, also for an unlocked index that was migrated to Lucene. From version 6.21.1, the rebuilt index keeps the search engine of the existing index.
+
+A **locked** index does not receive the new definition. To apply the new definition to a locked index that was migrated to Lucene:
+
+- On versions 6.20.0 and 6.21.0, unlock the index and let ServiceControl rebuild it at the next start-up. Then do the [migration](/servicecontrol/ravendb/search-engine.md#migrating-existing-indexes-to-lucene) again for the index. On these versions, the rebuild resets the index to Corax. See [Index reset to Corax after unlocking](/servicecontrol/ravendb/search-engine.md#index-reset-to-corax-after-unlocking).
+- On version 6.21.1 and later, unlock the index. ServiceControl rebuilds the index with the new definition at the next start-up. The index stays on Lucene.
+
 ## Previously migrated and locked indexes
 
 Indexes that were already migrated to Lucene and locked, as described in the [troubleshooting guide](/servicecontrol/troubleshooting.md#audit-instances-corrupted-indexes-or-corrupted-database-after-a-service-shutdown), remain locked and on Lucene after the upgrade. No action is required for them; the custom check only reports indexes that still use Corax.