From 1d545c87a75577e08089efafafaea8140ef9f01d Mon Sep 17 00:00:00 2001 From: Mauro Servienti Date: Fri, 2 Oct 2026 15:45:11 +0200 Subject: [PATCH 1/4] Index locking is still required for ServiceControl 6.20.0 to 6.21.0 Versions 6.20.0 and 6.21.0 still reset a migrated index to the database default (Corax) at start-up when it is not locked. The fix ships in 6.21.1. Also document how to recover from an index that was reset to Corax after being unlocked. Co-Authored-By: Claude Opus 5.5 --- servicecontrol/ravendb/search-engine.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/servicecontrol/ravendb/search-engine.md b/servicecontrol/ravendb/search-engine.md index 9c4d429e201..e6da3d47987 100644 --- a/servicecontrol/ravendb/search-engine.md +++ b/servicecontrol/ravendb/search-engine.md @@ -66,10 +66,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. +The migration is performed per 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, 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. The indexes with the highest load, and therefore the ones that benefit most, are: @@ -111,14 +111,21 @@ 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. +> Locking the index is required on ServiceControl versions prior to 6.21.1. Starting with version 6.21.1, ServiceControl keeps the search engine configured on an index when it updates its index definitions at start-up, and this step can be skipped. 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. +> 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. On version 6.21.1 and later, the index can instead be unlocked permanently: definition changes are then applied automatically and the index stays on Lucene. + +#### Index reset to Corax after unlocking + +On versions 6.20.0 to 6.21.0, unlocking a migrated index causes ServiceControl to reset it at the next start-up. RavenDB then builds a replacement index named `ReplacementOf/` that uses Corax. To recover: + +- Upgrade to version 6.21.1 or later and make sure the migrated index is unlocked. At start-up, ServiceControl keeps the search engine configured on the migrated index (Lucene) and RavenDB discards the Corax replacement index without rebuilding the migrated index. +- If upgrading is not possible, stop the instance, lock the migrated index again as `🔒 Locked (ignore)`, and delete the `ReplacementOf/` index in the Studio. ### 5. Restart the instance From 94dc4df34697799f4d0617029da1ee34fce35e8a Mon Sep 17 00:00:00 2001 From: Ramon Smits Date: Mon, 5 Oct 2026 12:13:07 +0200 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9D=20Cover=20the=20already-swappe?= =?UTF-8?q?d=20case=20in=20the=20Corax=20reset=20recovery=20and=20note=20t?= =?UTF-8?q?he=20audit=20index=20rebuild=20in=20the=206.20=20upgrade=20guid?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- servicecontrol/ravendb/search-engine.md | 6 +++--- servicecontrol/upgrades/6.19to6.20.md | 13 ++++++++++++- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/servicecontrol/ravendb/search-engine.md b/servicecontrol/ravendb/search-engine.md index e6da3d47987..dc28b1df777 100644 --- a/servicecontrol/ravendb/search-engine.md +++ b/servicecontrol/ravendb/search-engine.md @@ -122,10 +122,10 @@ A locked index is left untouched when ServiceControl recreates its index definit #### Index reset to Corax after unlocking -On versions 6.20.0 to 6.21.0, unlocking a migrated index causes ServiceControl to reset it at the next start-up. RavenDB then builds a replacement index named `ReplacementOf/` that uses Corax. To recover: +On versions 6.20.0 to 6.21.0, unlocking a migrated index causes ServiceControl to reset it at the next start-up. RavenDB then builds a replacement index named `ReplacementOf/` that uses Corax, and swaps it in once the replacement is no longer stale. The recovery steps depend on whether the swap has already happened. Check the **List of Indexes** in the Studio: -- Upgrade to version 6.21.1 or later and make sure the migrated index is unlocked. At start-up, ServiceControl keeps the search engine configured on the migrated index (Lucene) and RavenDB discards the Corax replacement index without rebuilding the migrated index. -- If upgrading is not possible, stop the instance, lock the migrated index again as `🔒 Locked (ignore)`, and delete the `ReplacementOf/` index in the Studio. +- **The replacement is still being built**: `ReplacementOf/` is listed and the migrated index still shows Lucene. Upgrade to version 6.21.1 or later and make sure the migrated index is unlocked. At start-up, ServiceControl keeps the search engine configured on the migrated index (Lucene) and RavenDB discards the Corax replacement index without rebuilding the migrated index. If upgrading is not possible, stop the instance, lock the migrated index again as `🔒 Locked (ignore)`, and delete the `ReplacementOf/` index in the Studio. +- **The replacement has already been swapped in**: no `ReplacementOf/` is listed and the index shows Corax. The Lucene configuration is lost. Upgrade to version 6.21.1 or later, then repeat [step 2](#migrating-existing-indexes-to-lucene-2-change-the-search-engine-of-the-index) for the index. On small or idle databases the swap completes within seconds after start-up, so this is the more common state. ### 5. Restart the instance diff --git a/servicecontrol/upgrades/6.19to6.20.md b/servicecontrol/upgrades/6.19to6.20.md index 443a66eed1f..1fa6c50ff40 100644 --- a/servicecontrol/upgrades/6.19to6.20.md +++ b/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 + +The definition of the audit instance index `MessagesViewIndex`, or `MessagesViewIndexWithFullTextSearch` when [full-text search on message bodies](/servicecontrol/audit-instances/configuration.md#performance-tuning-servicecontrol-auditenablefulltextsearchonbodies) is enabled, changed in version 6.20. At the first start-up after the upgrade, RavenDB builds the new definition as a replacement index next to the existing one and swaps it in once the replacement is no longer stale. On large audit databases the rebuild takes time, and ingestion and indexing rates are degraded while it runs. Plan the upgrade of audit instances in a maintenance window. + +The rebuilt index uses the search engine of the existing index: Corax for databases created before version 6.20, unless the index was migrated to Lucene. + +If the index was migrated to Lucene and **locked**, the new definition is not applied while the lock is in place. To apply it: + +- On version 6.20.0 and 6.21.0, unlock the index, let ServiceControl rebuild it at the next start-up, and repeat the [migration](/servicecontrol/ravendb/search-engine.md#migrating-existing-indexes-to-lucene) for it. Unlocking resets the index to Corax on these versions, see [Index reset to Corax after unlocking](/servicecontrol/ravendb/search-engine.md#migrating-existing-indexes-to-lucene-4-lock-the-index-index-reset-to-corax-after-unlocking). +- On version 6.21.1 and later, unlock the index. The index is rebuilt with the new definition at the next start-up and 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. From ace0967302870ffc7e47cf50e946593840f680b9 Mon Sep 17 00:00:00 2001 From: Ramon Smits Date: Mon, 5 Oct 2026 12:20:37 +0200 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=93=9D=20Rewrite=20the=20search=20eng?= =?UTF-8?q?ine=20lock=20and=20recovery=20text=20in=20Simplified=20Technica?= =?UTF-8?q?l=20English?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- servicecontrol/ravendb/search-engine.md | 14 +++++++------- servicecontrol/upgrades/6.19to6.20.md | 10 +++++----- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/servicecontrol/ravendb/search-engine.md b/servicecontrol/ravendb/search-engine.md index dc28b1df777..57e1f781ba3 100644 --- a/servicecontrol/ravendb/search-engine.md +++ b/servicecontrol/ravendb/search-engine.md @@ -66,10 +66,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.21.1, 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 after the migration. 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. The indexes with the highest load, and therefore the ones that benefit most, are: @@ -111,21 +111,21 @@ In the **List of Indexes**, the index shows the replacement being built. Once th ### 4. Lock the index > [!NOTE] -> Locking the index is required on ServiceControl versions prior to 6.21.1. Starting with version 6.21.1, ServiceControl keeps the search engine configured on an index when it updates its index definitions at start-up, and this step can be skipped. +> The lock is necessary on ServiceControl versions before 6.21.1. From version 6.21.1, ServiceControl keeps the search engine configured on an index when it updates its index definitions at start-up. On these versions, this step is not necessary. 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. On version 6.21.1 and later, the index can instead be unlocked permanently: definition changes are then applied automatically and the index stays on Lucene. +> 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. On version 6.21.1 and later, the index can stay unlocked. ServiceControl then applies definition changes automatically and the index stays on Lucene. #### Index reset to Corax after unlocking -On versions 6.20.0 to 6.21.0, unlocking a migrated index causes ServiceControl to reset it at the next start-up. RavenDB then builds a replacement index named `ReplacementOf/` that uses Corax, and swaps it in once the replacement is no longer stale. The recovery steps depend on whether the swap has already happened. Check the **List of Indexes** in the Studio: +On versions 6.20.0 to 6.21.0, ServiceControl resets an unlocked migrated index at the next start-up. RavenDB then builds a replacement index with the name `ReplacementOf/` that uses Corax. When the replacement is no longer stale, RavenDB swaps it in. The recovery steps depend on the state of the swap. Check the **List of Indexes** in the Studio: -- **The replacement is still being built**: `ReplacementOf/` is listed and the migrated index still shows Lucene. Upgrade to version 6.21.1 or later and make sure the migrated index is unlocked. At start-up, ServiceControl keeps the search engine configured on the migrated index (Lucene) and RavenDB discards the Corax replacement index without rebuilding the migrated index. If upgrading is not possible, stop the instance, lock the migrated index again as `🔒 Locked (ignore)`, and delete the `ReplacementOf/` index in the Studio. -- **The replacement has already been swapped in**: no `ReplacementOf/` is listed and the index shows Corax. The Lucene configuration is lost. Upgrade to version 6.21.1 or later, then repeat [step 2](#migrating-existing-indexes-to-lucene-2-change-the-search-engine-of-the-index) for the index. On small or idle databases the swap completes within seconds after start-up, so this is the more common state. +- **The replacement is not swapped in yet**: `ReplacementOf/` is in the list and the migrated index shows Lucene. Upgrade to version 6.21.1 or later and make sure that the migrated index is unlocked. At start-up, ServiceControl keeps the Lucene search engine configured on the migrated index. RavenDB discards the Corax replacement and does not rebuild the migrated index. If an upgrade is not possible, stop the instance, lock the migrated index again as `🔒 Locked (ignore)`, and delete the `ReplacementOf/` index in the Studio. +- **The replacement is swapped in**: `ReplacementOf/` is not in the list and the index shows Corax. The Lucene configuration is lost. Upgrade to version 6.21.1 or later. Then do [step 2](#migrating-existing-indexes-to-lucene-2-change-the-search-engine-of-the-index) again for the index. On small or idle databases, the swap completes in seconds after start-up. This state is the more common one. ### 5. Restart the instance diff --git a/servicecontrol/upgrades/6.19to6.20.md b/servicecontrol/upgrades/6.19to6.20.md index 1fa6c50ff40..ba7499293b2 100644 --- a/servicecontrol/upgrades/6.19to6.20.md +++ b/servicecontrol/upgrades/6.19to6.20.md @@ -36,14 +36,14 @@ Instances without these symptoms should be migrated in the next planned maintena ## Audit message index definition changed -The definition of the audit instance index `MessagesViewIndex`, or `MessagesViewIndexWithFullTextSearch` when [full-text search on message bodies](/servicecontrol/audit-instances/configuration.md#performance-tuning-servicecontrol-auditenablefulltextsearchonbodies) is enabled, changed in version 6.20. At the first start-up after the upgrade, RavenDB builds the new definition as a replacement index next to the existing one and swaps it in once the replacement is no longer stale. On large audit databases the rebuild takes time, and ingestion and indexing rates are degraded while it runs. Plan the upgrade of audit instances in a maintenance window. +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. -The rebuilt index uses the search engine of the existing index: Corax for databases created before version 6.20, unless the index was migrated to Lucene. +The rebuilt index uses the search engine of the existing index. For databases created before version 6.20, this is Corax, unless the index was migrated to Lucene. -If the index was migrated to Lucene and **locked**, the new definition is not applied while the lock is in place. To apply it: +A **locked** index does not receive the new definition. To apply the new definition to a locked index that was migrated to Lucene: -- On version 6.20.0 and 6.21.0, unlock the index, let ServiceControl rebuild it at the next start-up, and repeat the [migration](/servicecontrol/ravendb/search-engine.md#migrating-existing-indexes-to-lucene) for it. Unlocking resets the index to Corax on these versions, see [Index reset to Corax after unlocking](/servicecontrol/ravendb/search-engine.md#migrating-existing-indexes-to-lucene-4-lock-the-index-index-reset-to-corax-after-unlocking). -- On version 6.21.1 and later, unlock the index. The index is rebuilt with the new definition at the next start-up and stays on 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#migrating-existing-indexes-to-lucene-4-lock-the-index-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 From 22019f38f977595acde47f25b6075338c4c9aef0 Mon Sep 17 00:00:00 2001 From: Mauro Servienti Date: Mon, 5 Oct 2026 13:21:40 +0200 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=9D=20Fix=20anchors,=20recovery=20?= =?UTF-8?q?steps=20and=206.20/6.21=20rebuild=20behavior=20in=20the=20searc?= =?UTF-8?q?h=20engine=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix anchor links to numbered headings, the docs engine drops the step number - On 6.20.0 and 6.21.0 a rebuilt index uses the database search engine, not the one of the existing index - Delete the Corax replacement before locking the migrated index, and restart RavenDB on Windows in between: while the index is locked the delete can have no effect, and RavenDB can keep files of a deleted replacement open - Give the already-swapped case a path for 6.20.0 and 6.21.0 as well - Move the recovery steps out of the migration procedure into their own section and state once that the lock is not necessary from 6.21.1 - Document that from 6.21.1 new indexes in existing databases use Lucene Co-Authored-By: Claude Opus 5.5 --- servicecontrol/ravendb/search-engine.md | 46 +++++++++++++++++++------ servicecontrol/upgrades/6.19to6.20.md | 4 +-- 2 files changed, 38 insertions(+), 12 deletions(-) diff --git a/servicecontrol/ravendb/search-engine.md b/servicecontrol/ravendb/search-engine.md index 57e1f781ba3..bfeb406295c 100644 --- a/servicecontrol/ravendb/search-engine.md +++ b/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. @@ -69,7 +71,7 @@ Instances without these symptoms should be migrated in the next planned maintena Do the migration for each index in RavenDB Studio. > [!IMPORTANT] -> On ServiceControl versions before 6.21.1, also **lock** the migrated index after the migration. 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. +> 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,25 +113,49 @@ In the **List of Indexes**, the index shows the replacement being built. Once th ### 4. Lock the index > [!NOTE] -> The lock is necessary on ServiceControl versions before 6.21.1. From version 6.21.1, ServiceControl keeps the search engine configured on an index when it updates its index definitions at start-up. On these versions, this step is not necessary. +> 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] -> 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. On version 6.21.1 and later, the index can stay unlocked. ServiceControl then applies definition changes automatically and the index stays on Lucene. +> 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. -#### Index reset to Corax after unlocking +### 5. Restart the instance -On versions 6.20.0 to 6.21.0, ServiceControl resets an unlocked migrated index at the next start-up. RavenDB then builds a replacement index with the name `ReplacementOf/` that uses Corax. When the replacement is no longer stale, RavenDB swaps it in. The recovery steps depend on the state of the swap. Check the **List of Indexes** in the Studio: +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. -- **The replacement is not swapped in yet**: `ReplacementOf/` is in the list and the migrated index shows Lucene. Upgrade to version 6.21.1 or later and make sure that the migrated index is unlocked. At start-up, ServiceControl keeps the Lucene search engine configured on the migrated index. RavenDB discards the Corax replacement and does not rebuild the migrated index. If an upgrade is not possible, stop the instance, lock the migrated index again as `🔒 Locked (ignore)`, and delete the `ReplacementOf/` index in the Studio. -- **The replacement is swapped in**: `ReplacementOf/` is not in the list and the index shows Corax. The Lucene configuration is lost. Upgrade to version 6.21.1 or later. Then do [step 2](#migrating-existing-indexes-to-lucene-2-change-the-search-engine-of-the-index) again for the index. On small or idle databases, the swap completes in seconds after start-up. This state is the more common one. +## Index reset to Corax after unlocking -### 5. Restart the instance +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/` 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. -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. +To find the state of the index, open the **List of Indexes** in RavenDB Studio. + +### The replacement is not swapped in yet + +`ReplacementOf/` 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 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/` 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/` 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 diff --git a/servicecontrol/upgrades/6.19to6.20.md b/servicecontrol/upgrades/6.19to6.20.md index ba7499293b2..b15ec3aa2c7 100644 --- a/servicecontrol/upgrades/6.19to6.20.md +++ b/servicecontrol/upgrades/6.19to6.20.md @@ -38,11 +38,11 @@ Instances without these symptoms should be migrated in the next planned maintena 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. -The rebuilt index uses the search engine of the existing index. For databases created before version 6.20, this is Corax, unless the index was migrated to Lucene. +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#migrating-existing-indexes-to-lucene-4-lock-the-index-index-reset-to-corax-after-unlocking). +- 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