Keep the search engine configured on an index when deploying index definitions

[mauroservienti]

Problem

6.20.0 recommends migrating RavenDB indexes from Corax to Lucene. The documented per-index procedure changes the search engine on the index's Configuration tab in RavenDB Studio, which stores Indexing.Static.SearchEngineType in the index configuration.

At every start-up ServiceControl deploys its index definitions with IndexCreation.CreateIndexesAsync. Those definitions carry no search engine, so RavenDB sees a definition difference and builds a side-by-side ReplacementOf/<index> that falls back to the database default. For databases created before 6.20 the default is Corax, because UpdateDatabaseSettings pins it. Unless the migrated index is locked, it gets reset to Corax and rebuilt.

A customer hit this after unlocking a migrated MessagesViewIndexWithFullTextSearch, following the docs, which state that locking is no longer needed from 6.20.0.

Fix

New IndexDeployment helper in ServiceControl.RavenDB, used by both the Primary and Audit DatabaseSetup instead of IndexCreation.CreateIndexesAsync. Before deploying, it reads the existing index definitions and copies the Indexing.Static.SearchEngineType configured on the existing index onto the definition being deployed. A pending replacement's configuration takes precedence over the original's.

• An index migrated in Studio is left alone: the definitions match, so nothing is rebuilt and no lock is needed.
• Intentional definition changes still roll out, and the rebuilt index keeps the operator's search engine.
• Other manual customizations are still reset at start-up, as before.
• A pending Corax replacement created by 6.20.0/6.21.0 is discarded at start-up once the migrated index is unlocked, because the deployed definition matches the original index again.

Tests

Audit IndexSetupTests:

• Indexes_should_be_reset_on_setup asserted the old behavior. It is replaced by:
  • Search_engine_configured_on_the_index_should_be_preserved_on_setup: no replacement, index not recreated.
  • Indexes_should_be_reset_on_setup_keeping_the_configured_search_engine: a hand-edited field is reset, the engine is kept.
• Pending_replacement_using_the_database_default_should_be_discarded_in_favor_of_the_configured_search_engine: reproduces the customer's state. Indexing is stopped so the replacement can't swap.
• The two lock-mode tests now customize a field instead of the search engine, since an engine-only difference no longer triggers an update.

Primary IndexSetupTests (new): covers the assembly-scanning path.

The three new Audit tests fail without the fix. Locally, both RavenDB persistence suites pass: Audit 55/55, Primary 349/349.

Related

• Docs: Index locking is still required for ServiceControl 6.20.0 to 6.21.0 docs.particular.net#8521 (locking still required before 6.21.1, plus recovery steps)
• Planned for 6.21.1

🤖 Generated with Claude Code