[danielmarbach]

This moves RavenDB.Embedded from 6.2.18 to 7.2.7. The upgrade changes the on-disk data format and raises the minimum server version for external databases, so we should ship it as ServiceControl 7.

Why now

RavenDB 6.2 support ends in 2027. The RavenDB policy page says June 30 and the support page says December 31. ServiceControl 6 remains supported for one year after ServiceControl 7 ships, so the earlier we ship, the more of that year RavenDB still covers. 7.2 is the only supported 7.x line, because 7.0 and 7.1 were short-term releases. 7.2.7 includes the compaction fix for migrated databases from 7.2.5, the storage fixes from 7.2.7, and a fix for excessive memory use in sorted queries.

What changes

We squash-merge, so here are the individual steps:

1. Retry database load timeouts for external RavenDB servers. Until now, only the embedded lifecycle retried DatabaseLoadTimeoutException. An instance that connects to an external server or the container now waits for the server to finish loading a large database instead of failing to start. Like the embedded loop, it retries until host startup is cancelled.

2. Publish the shared embedded RavenDB test server only after its setup completes. Tests that started together could reach the server before it was ready.

3. Add characterization tests for the RavenDB contracts we depend on. These tests change no production code. They cover:

   • the client-generated definition of every primary, throughput, and audit index
   • the JSON fields we read from /admin/debug/memory/stats and /license/status
   • deploying each index on its own
   • @expires set by patches and bulk inserts, and the JavaScript patch semantics
   • throughput time series, audit queries on Lucene and Corax, and server log output

   The approvals were created on 6.2.18 and pass unchanged on 7.2.7.

4. Update RavenDB to 7.2.7.

   • RavenDB 7 refuses to start with --Logs.Mode, so we pass --Logs.MinLevel.
   • RavenDBLogLevel accepts NLog level names as they are and translates the legacy names the same way RavenDB does: None to Off, Operations to Info, Information to Debug.
   • The default stays Warn, and Storage.LogLevel in the usage report now says Warn instead of Operations.
   • The client-side Raven.Embedded log is gone, because RavenDB 7 removed the Sparrow logging API it relied on.
   • OptimisticConcurrencyMode.Writes replaces the obsolete UseOptimisticConcurrency and keeps the same behavior.
   • SingleNodeBatchCommand no longer takes the session context.
   • The container is now based on ubuntu.24.04, because ravendb/ravendb publishes only those tags from 7.2.4 on.

5. Escape control characters in throughput endpoint document IDs. Databases created by RavenDB 7.2.5 or later reject them. Every other ID stays byte-for-byte the same, so existing documents still resolve. A name that already contains a literal %01 maps to the same ID as one with the control character. We accept that, because we don't expect endpoint names like that.

6. Save enums as integers in RavenDB patches. SaveEnumsAsIntegersForPatching is now set wherever SaveEnumsAsIntegers is, so a future typed patch cannot write enums as strings.

7. Leave unused RavenDB server libraries out of the package. The ONNX runtime libraries and the local embeddings model no longer ship in RavenDBServer.zip, which saves about 19 MB. The managed AI assemblies stay, because the server does not start without them.

8. Reject RavenDB 7.2 servers that corrupt migrated databases on compaction. The check keeps RavenDB's compatibility rule, which ignores the patch: the server's major.minor must be at least the client's. On top of that, it rejects 7.2.0 to 7.2.4, because those versions corrupt the attachments index when an operator compacts a database migrated from 6.2 or 7.1. 7.2.5 fixed this and repairs the schema when the database loads, so refusing to start moves operators to a server that repairs their database. The 7.2.5 floor is fixed, so a later client patch does not raise the server requirement. The check handles suffixes such as -nightly.

9. Require the latest 6.x before upgrading to 7. The installer requires 6.21.0 before an upgrade to 7.0, the same way 5.11.0 gated the move to 6.0.

What operators need to know

• External RavenDB servers and the servicecontrol-ravendb container must run 7.2.5 or later before the instances are upgraded. We recommend 7.2.7, the version ServiceControl 7 ships with. A 6.x instance still starts against a 7.2 server, because its check only rejects servers with a lower major.minor version. We have not smoke-tested that order yet.
• The data upgrade is one-way. Rolling back requires a backup taken before the first start on 7.2.7.
• Particular.PlatformSample.ServiceControl needs the .NET 10 runtime 10.0.12 or later, because the RavenDB 7.2.7 server is framework-dependent.
• On Corax databases, results that share a sort key, for example in a message_type sort, can come back in a different order than on 6.2.18. Totals and result sets stay the same.

Alternatives we did not take

• Rebasing draft Ravendb upgrade #5978. I picked its changes one by one after checking each of them. Its logging mapping (Operations to Warn) differs from RavenDB's own translation, so I did not use it.
• Upgrading through 7.0 or 7.1. Both are out of support.
• Routing RavenDB client logs into ServiceControl logging. RavenLogManager.Set would need an adapter for an interface with about 52 members, and it has to run before any RavenDB type loads. That is a lot of code for a log that was only written at the most verbose level.
• Turning off bulk insert compression for the embedded server. With NoCompression, inserts were not faster and used more CPU overall.

Related pull requests

• Approve RavenDB index definitions to catch changes that trigger a rebuild #6013 adds index-definition approval tests for the same purpose as the ones in step 3. Once Approve RavenDB index definitions to catch changes that trigger a rebuild #6013 merges, I'll drop our index approvals in favor of it. Both PRs touch RavenExternalPersistenceLifecycle and EmbeddedDatabase, so whichever lands second needs a rebase.
• I'll rebase this branch on the search engine stack (Stop adding the Corax search engine setting to existing databases #6034, Use Lucene for new and rebuilt indexes #6035, Report locked indexes and index rebuilds at start-up #6036, and Record the RavenDB index search engine and rebuild decision #6043) as it merges. Use Lucene for new and rebuilt indexes #6035 also matches what the upgrade simulation below showed: master creates missing indexes with Lucene even in a Corax database.
• This supersedes Ravendb upgrade #5978 and the Renovate PR Update dependency RavenDB.Embedded to v7 #5079.

How this was verified

Tests ran on macOS arm64 in Release, after the rebase on master:

Project	Result
ServiceControl.Persistence.Tests.RavenDB	436 passed
ServiceControl.Audit.Persistence.Tests.RavenDB	104 passed
ServiceControl.AcceptanceTests.RavenDB	228 passed, 2 skipped (before the rebase)
ServiceControl.Audit.AcceptanceTests.RavenDB	74 passed (before the rebase)
ServiceControl.MultiInstance.AcceptanceTests	23 passed (before the rebase)
Unit tests, ServiceControlInstaller.Packaging.UnitTests	All passed

Beyond the test suites:

• The servicecontrol-ravendb image built locally from the 24.04 base, started, reported 7.2.7, and accepted the license.
• Against real servers, an earlier version of the external version check rejected 7.2.4 and 6.2.20 and accepted 7.2.7. The current check gives the same results for those versions in its unit tests, but I have not re-run it against the containers.
• A server with the excluded files removed started on Linux, Studio loaded, and creating and querying an index worked.
• I simulated the in-place upgrade in Docker:
  • Master instances ran against a 6.2.18 container with RabbitMQ and seeded data: failed messages, failure groups, retries, archives, audit messages with bodies, and saga snapshots.
  • I then moved the container to 7.2.7 on the same volume and started the instances from this branch against it.
  • On Lucene and on Corax databases, no index was reset or rebuilt. CreatedTimestamp, search engine, and entry counts stayed the same, and polling found no ReplacementOf/ index.
  • On Corax, 234 REST queries returned the same totals and result sets before and after the upgrade. Only the order of equal message_type sort keys changed.

Still to verify:

• ServiceControlInstaller.Engine.UnitTests targets net10.0-windows, so it needs CI. That covers PackagedRavenDBTests against the trimmed zip and the new upgrade gate tests. The gate logic already passed in a net10.0 copy.
• How long the upgrade takes on large databases, especially the attachment migration on the first start of 7.2, and how the installer's 120-second wait for the service to start behaves in the meantime.
• A consumer project running Particular.PlatformSample.ServiceControl.

Before this is ready for review

• Confirm the final 6.x version for the upgrade gate. The gate requires 6.21.0, but master builds as 6.22.0-alpha.
• Decide how the version becomes 7.0.0.
• Draft the release notes and the upgrade guide for the docs repository, covering the upgrade order, backup and rollback, and free disk space on external hosts.

[danielmarbach]

Left it in draft since we haven't made a decision to roll this out. We first want to make tests and then decide