Reject RavenDB 7.2 servers that corrupt migrated databases on compaction

RavenDB 7.2.0 to 7.2.4 corrupt the attachments index when an operator
compacts a database migrated from 6.2 or 7.1. 7.2.5 fixed it and repairs
the stale schema when the database loads, so refusing to start on those
patches moves operators to a server that repairs their database before a
compaction can damage it.

The check keeps RavenDB's compatibility rule, which ignores the patch:
the server's major.minor must be at least the client's. The 7.2.5 floor is
fixed, so a later client patch does not raise the server requirement.

Author: danielmarbach

src/ServiceControl.Persistence.Tests.RavenDB/StartupChecksTests.cs

@@ -0,0 +1,96 @@
+namespace ServiceControl.Persistence.Tests.RavenDB;
+
+using System;
+using NUnit.Framework;
+using ServiceControl.RavenDB;
+
+[TestFixture]
+class StartupChecksTests
+{
+    static readonly Version Client727 = new(7, 2, 7);
+
+    [TestCase("6.2.0")]
+    [TestCase("6.2.20")]
+    [TestCase("7.1.9")]
+    public void Should_reject_servers_with_a_lower_major_minor_version_than_the_client(string serverVersion)
+    {
+        var isValid = StartupChecks.TryValidateServerVersion(serverVersion, Client727, out var error);
+
+        using (Assert.EnterMultipleScope())
+        {
+            Assert.That(isValid, Is.False);
+            Assert.That(error, Does.Contain("expects RavenDB Server version 7.2 or higher")
+                .And.Contain($"the server is using {serverVersion}")
+                .And.Contain("servicecontrol-ravendb container"));
+        }
+    }
+
+    [Test]
+    public void Should_reject_servers_with_a_lower_major_minor_version_than_a_newer_client()
+    {
+        var isValid = StartupChecks.TryValidateServerVersion("7.2.9", new Version(7, 3, 0), out var error);
+
+        using (Assert.EnterMultipleScope())
+        {
+            Assert.That(isValid, Is.False);
+            Assert.That(error, Does.Contain("expects RavenDB Server version 7.3 or higher").And.Contain("the server is using 7.2.9"));
+        }
+    }
+
+    [TestCase("7.2.0", "7.2.0")]
+    [TestCase("7.2.4", "7.2.4")]
+    [TestCase("7.2.4-nightly-20260101-0100", "7.2.4")]
+    public void Should_reject_servers_with_the_known_attachments_index_corruption(string serverVersion, string reportedVersion)
+    {
+        var isValid = StartupChecks.TryValidateServerVersion(serverVersion, Client727, out var error);
+
+        using (Assert.EnterMultipleScope())
+        {
+            Assert.That(isValid, Is.False);
+            Assert.That(error, Does.Contain($"RavenDB Server {reportedVersion} can corrupt the attachments index")
+                .And.Contain("to 7.2.5 or later")
+                .And.Contain("servicecontrol-ravendb container"));
+        }
+    }
+
+    [TestCase("7.2.5")]
+    [TestCase("7.2.6")]
+    [TestCase("7.2.7")]
+    [TestCase("7.2.10")]
+    [TestCase("7.2.7+441f983")]
+    [TestCase("7.2.8-nightly-20260101-0100")]
+    [TestCase("7.3.0")]
+    [TestCase("8.0.0")]
+    public void Should_accept_compatible_servers_without_the_known_corruption(string serverVersion)
+    {
+        var isValid = StartupChecks.TryValidateServerVersion(serverVersion, Client727, out var error);
+
+        using (Assert.EnterMultipleScope())
+        {
+            Assert.That(isValid, Is.True);
+            Assert.That(error, Is.Null);
+        }
+    }
+
+    [TestCase("7.2.5")]
+    [TestCase("7.2.7")]
+    public void Should_not_raise_the_floor_with_the_client_patch_version(string serverVersion)
+    {
+        var isValid = StartupChecks.TryValidateServerVersion(serverVersion, new Version(7, 2, 10), out _);
+
+        Assert.That(isValid, Is.True);
+    }
+
+    [TestCase("")]
+    [TestCase("unknown")]
+    public void Should_reject_unreadable_server_versions(string serverVersion)
+    {
+        var isValid = StartupChecks.TryValidateServerVersion(serverVersion, Client727, out var error);
+
+        using (Assert.EnterMultipleScope())
+        {
+            Assert.That(isValid, Is.False);
+            Assert.That(error, Does.Contain($"could not read the server version '{serverVersion}'"));
+        }
+    }
+}

src/ServiceControl.RavenDB/StartupChecks.cs

@@ -43,27 +43,55 @@ public static async Task<string[]> FindIndexesUsingCorax(IDocumentStore store, s
 
         public static async Task EnsureServerVersion(IDocumentStore store, CancellationToken cancellationToken = default)
         {
-            // RavenDB compatibility policy is that the major/minor version of the server must be
-            // equal or higher than the client and ignores the patch version.
-            //
-            // https://docs.ravendb.net/6.2/client-api/faq/backward-compatibility/#compatibility---ravendb-42-and-higher
-            //
-            // > Starting with version 4.2, RavenDB clients are compatible with any server of their own version and higher.
-            // > E.g. -
-            // >
-            // > Client 4.2 is compatible with Server 4.2, Server 4.5, Server 5.2, and any other server of a higher version.
-
             var build = await store.Maintenance.Server.SendAsync(new GetBuildNumberOperation(), cancellationToken);
-            var serverProductVersion = new Version(build.ProductVersion);
 
-            var clientVersion = typeof(Raven.Client.Constants).Assembly.GetCustomAttributes<AssemblyInformationalVersionAttribute>().First().InformationalVersion;
-            var parts = clientVersion.Split('.');
-            var clientProductVersion = new Version($"{parts[0]}.{parts[1]}");
+            if (!TryValidateServerVersion(build.FullVersion, ClientVersion, out var error))
+            {
+                throw new Exception(error);
+            }
+        }
+
+        public static bool TryValidateServerVersion(string serverFullVersion, Version clientVersion, out string error)
+        {
+            var clientMajorMinor = new Version(clientVersion.Major, clientVersion.Minor);
+
+            // FullVersion can carry a suffix such as "7.2.8-nightly-20260101-0100" or "7.2.7+commit"
+            var numericPart = serverFullVersion.Split('-', '+')[0];
+
+            if (!Version.TryParse(numericPart, out var serverVersion))
+            {
+                error = $"ServiceControl expects RavenDB Server version {clientMajorMinor} or higher, but could not read the server version '{serverFullVersion}'.";
+                return false;
+            }
 
-            if (clientProductVersion > serverProductVersion)
+            // RavenDB ignores the patch for compatibility: https://docs.ravendb.net/7.2/client-api/faq/backward-compatibility
+            if (new Version(serverVersion.Major, serverVersion.Minor) < clientMajorMinor)
             {
-                throw new Exception($"ServiceControl expects RavenDB Server version {clientProductVersion} or higher, but the server is using {serverProductVersion}.");
+                error = $"ServiceControl expects RavenDB Server version {clientMajorMinor} or higher, but the server is using {serverVersion}. " +
+                        "Upgrade the external RavenDB server or the servicecontrol-ravendb container before starting ServiceControl.";
+                return false;
             }
+
+            // Compacting a migrated database corrupts its attachments index before 7.2.5: https://github.com/ravendb/ravendb/releases/tag/7.2.5
+            if (serverVersion.Major == 7 && serverVersion.Minor == 2 && serverVersion < FirstServerWithAttachmentsIndexFix)
+            {
+                error = $"RavenDB Server {serverVersion} can corrupt the attachments index of migrated databases during compaction. " +
+                        $"Upgrade the external RavenDB server or the servicecontrol-ravendb container to {FirstServerWithAttachmentsIndexFix} or later before starting ServiceControl.";
+                return false;
+            }
+
+            error = null;
+            return true;
+        }
+
+        static readonly Version FirstServerWithAttachmentsIndexFix = new(7, 2, 5);
+
+        static readonly Version ClientVersion = ParseClientVersion();
+
+        static Version ParseClientVersion()
+        {
+            var clientVersion = typeof(Raven.Client.Constants).Assembly.GetCustomAttributes<AssemblyInformationalVersionAttribute>().First().InformationalVersion;
+            return Version.Parse(clientVersion.Split('-', '+')[0]);
         }
 
         static readonly ILogger Logger = LoggerUtil.CreateStaticLogger(typeof(StartupChecks));