Skip to content

ADR: Record how the namespace of a RavenDB index decides its database - #6147

Open
mauroservienti wants to merge 1 commit into
masterfrom
ravendb-index-database-placement-adr
Open

mauroservienti wants to merge 1 commit into
masterfrom
ravendb-index-database-placement-adr

Conversation

@mauroservienti

Copy link
Copy Markdown
Member

Adds an ADR for how the error persister decides which database a RavenDB index is deployed to. #6099 fixed #6123 by deploying the index classes in the ServiceControl.Persistence.RavenDB.Throughput.Indexes namespace to the throughput database and all others to the error database. That check is a naming convention the compiler does not enforce, and it fails silently, so the rationale, the risks, and the rules for adding an index need a record that outlives the pull request.

The ADR

  • Context: two databases in one persister, index classes that carry no information about their database, and how EndpointIndex ended up in the error database from 5.4.0 without anyone noticing.
  • Decision: the namespace split in DatabaseSetup, the target database parameter of IndexDeployment.CreateIndexesAsync, and the deletion of the old copy from the error database, including locked copies.
  • Consequences, each with a mitigation or an acceptance:
    • a throughput index in another or a nested namespace goes to the error database; tests that run the query catch it, thanks to Query<T, TIndex> and Make RavenDB throw on queries that would create an auto index in tests #6120
    • an error index moved into the throughput namespace is deleted from the error database at start-up; nothing catches it except review
    • renaming EndpointIndex's namespace moves the check for every throughput index
    • the approval test does not render the target database, so a placement change is invisible to it. Proposed follow-up: render it.
  • Adding a RavenDB index: six steps, from picking the database to never moving an index class between namespaces.
  • Alternatives: a per-database attribute or marker interface (the point of leverage for a future change), a separate assembly or base class, an explicit list, and deploying every index everywhere.

docs/README.md links the ADR under Decisions and rationale.

@danielmarbach

Copy link
Copy Markdown
Contributor

Can we wait for the agent.md changes to go in? I just rebased that one

@danielmarbach

Copy link
Copy Markdown
Contributor

The agent.md changes are in

#6099 fixed #6123 by deploying the index classes in the
Throughput.Indexes namespace to the throughput database and all others
to the error database. The ADR records that this is a weak, unenforced
convention, the risks and their mitigations, how to add a new index,
and the alternatives, including a per-database marker as the point of
leverage.
@danielmarbach
danielmarbach force-pushed the ravendb-index-database-placement-adr branch from b0a5571 to 841d5de Compare November 17, 2026 08:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Throughput queries create RavenDB auto indexes in the throughput database

2 participants