You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 5ee1d78
Browse filesBrowse the repository at this point in the historyBrowse files
Accept the RavenDB index search engine ADR and align it with the shipped behavior (#6138)
* Accept the RavenDB index search engine ADR and align it with the shipped behavior
The stack the ADR records is merged and shipped in 6.22.2. Since the ADR
was written, #6035 and #6036 changed behavior it describes:
- Rule 3 replaces Corax set on the index, so such an index no longer
stays on Corax across definition changes; rules 1 and 2 warn about a
non-Lucene engine.
- A locked index with a changed definition stops the start-up in either
lock mode, not only LockedError. #6107 makes maintenance mode skip the
database setup so the operator can unlock the index.
Also links the fixed bugs (#6094, #6095), the backports, the operator
guidance in docs.particular.net (#8639, #8645), and records the rejected
"refuse to start on Corax" alternative from #6035.
* Record in the ADR why ServiceControl queries only through static indexes
Auto indexes follow the database setting and have no search engine of
their own, so neither the rules in the ADR nor the per-index migration
can move them to Lucene. #5953, #6099, and #6100 replaced the remaining
dynamic queries with static indexes, and #6120 makes a dynamic query
throw in tests. The ADR now records the decision, its consequences for
existing auto indexes and swallowed exceptions, and the #6115 teardown
check as the alternative. docs/testing.md tells developers what to do
when a query throws.
Copy file name to clipboardExpand all lines: docs/README.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,7 +39,7 @@ This section points to sources that explain why ServiceControl is designed the w
39
39
## Decisions and rationale
40
40
41
41
-[Architecture and design decisions](decisions/)
42
-
-[RavenDB index search engine and rebuilds](decisions/2026-10-20-ravendb-index-search-engine-and-rebuilds.md) — which search engine a new or rebuilt index uses, why ServiceControl no longer writes database engine settings, and how developers and operators learn about an index rebuild
42
+
-[RavenDB index search engine and rebuilds](decisions/2026-10-20-ravendb-index-search-engine-and-rebuilds.md) — which search engine a new or rebuilt index uses, why ServiceControl no longer writes database engine settings, how developers and operators learn about an index rebuild, why a locked index with a changed definition stops the start-up, and why ServiceControl queries only through static indexes
- Released: #6034, #6035, and #6036 in 6.22.2 ([#6090](https://github.com/Particular/ServiceControl/pull/6090), [#6091](https://github.com/Particular/ServiceControl/pull/6091), [#6092](https://github.com/Particular/ServiceControl/pull/6092)). #6013, #6107, #6099, #6100, and #6120 are backported to `release-6.22` for 6.22.3 ([#6119](https://github.com/Particular/ServiceControl/pull/6119), [#6116](https://github.com/Particular/ServiceControl/pull/6116), [#6118](https://github.com/Particular/ServiceControl/pull/6118), [#6111](https://github.com/Particular/ServiceControl/pull/6111), [#6126](https://github.com/Particular/ServiceControl/pull/6126)).
6
8
- Builds on: [#4484](https://github.com/Particular/ServiceControl/pull/4484) (6.0.0), [#5833](https://github.com/Particular/ServiceControl/pull/5833) (6.20.0), [#5946](https://github.com/Particular/ServiceControl/pull/5946) (6.21.1).
7
9
8
10
## Context
@@ -31,22 +33,26 @@ ServiceControl no longer writes search engine settings to an existing database (
31
33
32
34
`IndexDeployment` resolves the engine of each index before deployment with these rules ([#6035](https://github.com/Particular/ServiceControl/pull/6035)), applied in order:
33
35
34
-
1. An engine set in the definition in code wins.
35
-
2.An engine set on the index on the server, or on its pending replacement, is kept. The pending replacement is checked first, because it holds the operator's latest choice.
36
-
3. A new index, or an index that RavenDB rebuilds because its definition changed, uses Lucene. When the database setting is Lucene, the index inherits it and gets no setting of its own. Otherwise Lucene is set on the index.
36
+
1. An engine set in the definition in code wins. A definition that sets an engine other than Lucene is logged as a warning; none of ServiceControl's definitions sets one.
37
+
2.Lucene set on the index on the server, or on its pending replacement, is kept. The pending replacement is checked first, because it holds the operator's latest choice. Another engine set on the index is kept only while the definition is unchanged, and is logged as a warning, because dropping the setting would itself rebuild the index.
38
+
3. A new index, or an index that RavenDB rebuilds because its definition changed, uses Lucene. When the database setting is Lucene, the index inherits it and gets no setting of its own. Otherwise Lucene is set on the index. This also replaces Corax set on the index.
37
39
4. An unchanged index without an engine of its own is left alone.
38
40
39
-
Rule 3 is the point of leverage. A Corax index without its own setting moves to Lucene at its next rebuild, which the definition change triggers anyway, so the migration costs no extra rebuild. A Lucene index never falls back to Corax.
41
+
Rule 3 is the point of leverage. A Corax index moves to Lucene at its next rebuild, which the definition change triggers anyway, so the migration costs no extra rebuild. A Lucene index never falls back to Corax. Lucene is the only engine ServiceControl supports: it never creates a Corax index.
40
42
41
-
A rebuild is made visible instead of avoided. An approval test renders every index definition the persisters deploy, so a definition change fails review until the upgrade guide records it ([#6013](https://github.com/Particular/ServiceControl/pull/6013)). At start-up, `IndexDeployment` reports each index's engine, each rebuild, and each locked index ([#6036](https://github.com/Particular/ServiceControl/pull/6036)). Operators get general guidance for upgrades that rebuild indexes ([docs#8577](https://github.com/Particular/docs.particular.net/pull/8577)).
43
+
A rebuild is made visible instead of avoided. An approval test renders every index definition the persisters deploy, so a definition change fails review until the upgrade guide records it ([#6013](https://github.com/Particular/ServiceControl/pull/6013)). At start-up, `IndexDeployment` reports each database's engine setting, each index's engine and where it comes from, each rebuild with the differences that cause it, and each locked index ([#6036](https://github.com/Particular/ServiceControl/pull/6036)). A locked index whose definition changed, in either lock mode, stops the start-up with an error that names the index, instead of keeping the old definition silently (`LockedIgnore`) or failing with a RavenDB exception that does not name it (`LockedError`). Operators get general guidance for upgrades that rebuild indexes and for unlocking changed indexes before upgrading ([docs#8577](https://github.com/Particular/docs.particular.net/pull/8577), [docs#8645](https://github.com/Particular/docs.particular.net/pull/8645)).
44
+
45
+
ServiceControl queries only through static indexes. A dynamic query makes RavenDB create an auto index, which follows the database setting `Indexing.Auto.SearchEngineType` and has no search engine setting of its own, so none of the rules above, nor the per-index migration in the documentation, can move it to Lucene. The search engine custom check and the start-up warning keep reporting such an index after every static index uses Lucene. The retry batches ([#5953](https://github.com/Particular/ServiceControl/pull/5953)), the throughput endpoints ([#6099](https://github.com/Particular/ServiceControl/pull/6099)), and the event log ([#6100](https://github.com/Particular/ServiceControl/pull/6100)) were the dynamic queries left, and now use static indexes. The test servers run with `Indexing.DisableQueryOptimizerGeneratedIndexes`, so a new dynamic query throws in the tests that exercise it ([#6120](https://github.com/Particular/ServiceControl/pull/6120)). A query without a filter or sort, or only on the document id, is a collection query and creates no index. Production instances do not set this option.
42
46
43
47
## Consequences
44
48
45
-
- Existing databases keep whatever engine settings they have, including a Corax pin from 6.0.0 to 6.21.2. Accepted, because the database default no longer decides the engine of a rebuilt index. The setting still applies to auto indexes and to a reset made in Studio.
46
-
- An index migrates from Corax to Lucene without operator action at its next definition change. The upgrade guide entry for the first release that changes a definition on a pinned database must say so, and the documented "Migrating the whole database" procedure needs to be checked against the new behavior.
47
-
- An index with Corax set on the index itself stays on Corax across definition changes (rule 2). Accepted: it is an explicit operator choice.
48
-
- A pending replacement started by 6.20.0 to 6.21.2 for an index without an engine of its own, in a database whose setting is not Lucene, has no engine of its own either. After the upgrade, rule 3 sets Lucene on the index, so the deployed definition no longer matches that replacement, and RavenDB is expected to build a new one, losing the progress made so far. #6035 does not discuss this case, and no test covers it. Mitigation: the upgrade guide tells operators to let a running rebuild finish before upgrading. Keeping the replacement on Corax would leave that index on Corax until its next definition change.
49
-
- A `LockedError` index whose definition changed fails start-up with `IndexCreationException`, after the error that #6036 logs. Mitigation: the upgrade guide covers `LockedError` next to `LockedIgnore`, which only postpones the change.
49
+
- Existing databases keep whatever engine settings they have, including a Corax pin from 6.0.0 to 6.21.2. Accepted, because the database default no longer decides the engine of a rebuilt index. The setting still applies to a reset made in Studio, and to auto indexes, which ServiceControl's own queries no longer create.
50
+
- Auto indexes created by earlier versions are not deleted at start-up. RavenDB marks an auto index idle after 30 minutes without queries and deletes it after 72 hours, and an operator can delete it in RavenDB Studio. Until then, the search engine check keeps reporting it if it uses Corax. Accepted, because they cover small collections (retry batches, the event log, and throughput endpoints) and go away without operator action.
51
+
- A dynamic query in a component whose exceptions are caught and logged throws in the tests without failing them, unless the test depends on the result. Mitigation: the error persistence tests also fail at teardown when a test leaves an auto index in the error database (#6100). In production the query still works and creates the auto index, which the search engine check reports.
52
+
- An index migrates from Corax to Lucene without operator action at its next definition change. The upgrade guide entry for the first release that changes a definition on a pinned database must say so. The search engine documentation describes the behavior from 6.22.2, and warns that the "Migrating the whole database" procedure does not work on 6.20.0 to 6.22.1 when the server default is Lucene ([docs#8639](https://github.com/Particular/docs.particular.net/pull/8639)).
53
+
- An index with Corax set on the index itself moves to Lucene at its next definition change (rule 3). Accepted, because Lucene is the only supported engine and the rebuild happens anyway. Until then the index keeps Corax and start-up logs a warning. An operator who needs Corax for an index has to lock it, and then receives no definition changes for it.
54
+
- A pending replacement started by 6.20.0 to 6.21.2 for an index without an engine of its own, in a database whose setting is not Lucene, has no engine of its own either. After the upgrade, rule 3 sets Lucene on the index, so the deployed definition no longer matches that replacement, and RavenDB is expected to build a new one, losing the progress made so far. #6035 does not discuss this case, and no test covers it. Mitigation: let a running rebuild finish before upgrading. The upgrade guide does not say so yet. Keeping the replacement on Corax would leave that index on Corax until its next definition change.
55
+
- A locked index whose definition changed stops the start-up, in either lock mode. Accepted, because a `LockedIgnore` index would otherwise run with a definition the new version's queries may not match, and the error names the index to unlock. Mitigation: the upgrade guide tells operators to unlock changed indexes before upgrading ([docs#8645](https://github.com/Particular/docs.particular.net/pull/8645)). In 6.22.2 maintenance mode ran the same setup and failed too, which left a Windows deployment with an embedded database no way to reach RavenDB Studio without support. From 6.22.3 maintenance mode skips the database setup ([#6107](https://github.com/Particular/ServiceControl/pull/6107)), so the operator can unlock the index there.
50
56
- A false positive in change detection on a database whose setting is not Lucene adds Lucene to an unchanged index and starts the rebuild that rule 4 exists to prevent. Mitigated by comparing with the deployed conventions and by tests that assert an unchanged index is not rebuilt.
51
57
- The approval test adds a re-approval and an upgrade-guide entry to every index change. Accepted. Re-approving is a file copy, so the test is a reminder, not a gate.
52
58
- An operator still learns about a rebuild only from the logs once it has started. The document count, an opt-in setting that refuses an unplanned rebuild, and a pre-upgrade check in ServiceControl Management remain open in [#6015](https://github.com/Particular/ServiceControl/issues/6015).
@@ -57,6 +63,8 @@ A rebuild is made visible instead of avoided. An approval test renders every ind
57
63
- Set Lucene on every index at start-up. This migrates every installation in one step. It is rejected because adding the setting changes every definition and rebuilds every index on every existing database at once, which is exactly the multi-day rebuild 6.20.0 left to the operator.
58
64
- Set the database default to Lucene during the upgrade. This makes rebuilt and new indexes inherit Lucene without a per-index setting. It is rejected because it overrides an operator's database setting, the same flaw as the Corax pin in the other direction.
59
65
- Keep following the database default for rebuilt indexes, as 6.21.1 did. This changes nothing that an operator configured. It is rejected because a definition change in a pinned database silently moves a Lucene index back to Corax, and because it wastes the one rebuild in which switching engine is free.
66
+
- Refuse to start when Corax is set on an index. This would enforce Lucene as the only supported engine. It is rejected because it stops a production service for a rare case, removes the escape hatch for support, and relies on telling an engine set on the index from an inherited one, which is not verified against a 6.x database. The warning in rule 2 gives the same message without the outage.
67
+
- Only check after each test that no auto index was created ([#6115](https://github.com/Particular/ServiceControl/pull/6115)), instead of making a dynamic query throw. It also catches a query whose exception a background component swallows. It is not adopted as the only guard because it fails at teardown without pointing to the query; making the query throw gives a stack trace. The error persistence tests keep a teardown check from #6100 next to it.
60
68
- Ask RavenDB whether an index will change with `IndexHasChangedOperation`, as [#6015](https://github.com/Particular/ServiceControl/issues/6015) proposes, instead of a client-side `Compare`. It uses the server's own rule. It is deferred: it needs one round trip per index, and it compares the definition after the engine is resolved, so it cannot inform the rule that resolves it.
61
69
- Rely on upgrade-guide entries alone to warn about rebuilds. It costs nothing in code. It is rejected because 6.20.0 shows an entry depends on someone noticing the change. The approval test makes the change visible in review.
62
70
- Gate index changes in CI or at release time: a pull request label with a required acknowledgement, or a release check that compares approved files with the previous tag. A release check would have caught 6.20.0, because it sees changes spread across several pull requests. These remain candidates for a follow-up; they were proposed in the [#6013](https://github.com/Particular/ServiceControl/pull/6013) review and not implemented.
Copy file name to clipboardExpand all lines: docs/testing.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,6 +28,8 @@ Persistence tests check assumptions at the persistence seam level by exercising
28
28
29
29
The RavenDB persistence test projects contain an `IndexDefinitionApprovals` test that approves the definition of every index the persister deploys. RavenDB rebuilds an index side by side when its definition changes, and the rebuild of a large database can take days. When the test fails, record the changed indexes in the upgrade guide of the next release before you approve the new definition. An operator who locked an index must unlock it to receive the change.
30
30
31
+
The RavenDB test servers run with `Indexing.DisableQueryOptimizerGeneratedIndexes`, so a query that would make RavenDB create an auto index throws. Query through a static index instead. Auto indexes have no search engine setting of their own, so the Lucene migration cannot reach them. See the [RavenDB index search engine ADR](decisions/2026-10-20-ravendb-index-search-engine-and-rebuilds.md).
32
+
31
33
The SQL Server and PostgreSQL persistence test projects contain a `SlowMigrationOperationApprovals` test. It approves the migration steps that can block writes on a large table: index, primary key, and unique constraint changes, new foreign keys and check constraints, altered columns, raw SQL, and new columns that are NOT NULL with a default or are stored computed columns. Other steps, such as renames and drops of columns, tables, and constraints, are not listed. The test lists these steps for each migration and leaves out steps on a table that the same migration creates, because that table is empty. Raw SQL is always listed. When the test fails because a step changed, record the change in the upgrade guide of the next release before you approve the new list. If a step changed inside an existing migration, for example through a shared SQL constant, add a new migration instead. Databases that already ran the old migration never run it again.
0 commit comments