feat: verify the database server at startup

Each adapter now reports its version against the oldest server Solid Objects is exercised against, and MySQL additionally confirms Solid Objects tables use InnoDB, since a non-transactional engine would silently break fenced commits. The doctor reports this as database_server and warns rather than failing, because refusing to run on an untested server would be a worse failure than running on one. PostgreSQL reports a packed integer, so it is normalised: comparing 170010 directly would make a 9.6 server look newer than any minimum, which the PostgreSQL run caught.

Author: cardmagic

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+- Verify the database server. Each adapter reports its version against the
+  oldest one Solid Objects is exercised against, PostgreSQL 13, MySQL 8.0, and
+  SQLite 3.35, and MySQL additionally confirms that Solid Objects tables use
+  InnoDB, since a non-transactional engine would silently break fenced commits.
+  The doctor reports this as `database_server` and warns rather than failing:
+  refusing to run on an untested server would be a worse failure than running
+  on one.
+
 ## 0.8.0 - 2026-08-10
 
 - Replace a supervised role whose thread died. A role that raised left its

docs/roadmap.md

@@ -24,6 +24,9 @@
 - Reconciliation read APIs
 - Installation doctor, authorization reference, fit guide, and legacy-state
   migration cookbook
+- Database server verification: each adapter reports its version against a
+  tested minimum, MySQL confirms Solid Objects tables use InnoDB, and the
+  doctor warns rather than refusing to run on an untested server
 - Handler Active Record write isolation, same-database commit actions, ambient
   transaction rejection, adapter lock/query deadlines, bounded SQLite lock
   retries outside those deadlines, structured sync timeout diagnostics, and
@@ -81,13 +84,12 @@
    benchmark, and its concurrency tests are implemented.
 2. Add result lookup by request ID and broader deadlock retry classification.
 3. Add scheduled retention and stale-process maintenance.
-4. Add database/server-version checks and MySQL InnoDB verification at boot.
-5. Add Turbo append intents and expand reconnect coverage in a full browser.
-6. Add distributed rate limits, global admission hooks, and cache-capacity
+4. Add Turbo append intents and expand reconnect coverage in a full browser.
+5. Add distributed rate limits, global admission hooks, and cache-capacity
    eviction.
-7. Expand security scanning and run compatibility CI across supported Rails and
+6. Expand security scanning and run compatibility CI across supported Rails and
    Ruby versions.
-8. Benchmark all workloads under documented hardware/database settings and
+7. Benchmark all workloads under documented hardware/database settings and
    publish adapter-specific adoption measurements. Throughput, synchronous
    latency, query counts, and the three reactive delivery paths are measured on
    SQLite; adapter-specific and end-to-end browser measurements are not.

lib/solid_objects/database_adapter.rb

@@ -32,6 +32,40 @@ def initialize(connection)
       @fixed_connection = connection_pool ? nil : connection
     end
 
+    # The oldest server the adapter has been exercised against. Reported rather
+    # than enforced: refusing to boot on an untested server would be a worse
+    # failure than running on one.
+    # @rbs () -> Gem::Version?
+    def minimum_server_version
+      nil
+    end
+
+    # @rbs () -> Gem::Version
+    def server_version
+      with_connection do |connection|
+        Gem::Version.new(connection.database_version.to_s)
+      end
+    end
+
+    # @rbs () -> Array[String]
+    def unsupported_server_reasons
+      reasons = []
+      minimum = minimum_server_version
+      if minimum && server_version < minimum
+        reasons << "#{self.class.name.demodulize} #{server_version} is older than " \
+          "Solid Objects requires, which is #{minimum}"
+      end
+      reasons.concat(additional_server_reasons)
+      reasons
+    rescue => error
+      [ "the database server could not be verified: #{error.class}: #{error.message}" ]
+    end
+
+    # @rbs () -> Array[String]
+    def additional_server_reasons
+      []
+    end
+
     # @rbs () -> bool
     def supports_skip_locked?
       false

lib/solid_objects/database_adapters/mysql.rb

@@ -13,6 +13,34 @@ def claim_lock
         "FOR UPDATE SKIP LOCKED"
       end
 
+      # A non-transactional engine would silently break fenced commits, so the
+      # storage engine is verified rather than assumed.
+      # @rbs () -> Array[String]
+      def additional_server_reasons
+        tables = non_innodb_tables
+        return [] if tables.empty?
+
+        [ "these Solid Objects tables do not use InnoDB, so their commits are " \
+          "not transactional: #{tables.join(", ")}" ]
+      end
+
+      # @rbs () -> Array[String]
+      def non_innodb_tables
+        names = SolidObjects::Doctor::EXPECTED_COLUMNS.keys.map { |name| SolidObjects.table_name(name) }
+        with_connection do |connection|
+          connection.select_rows(<<~SQL.squish).filter_map { |table, engine| table if engine != "InnoDB" }
+            SELECT table_name, engine FROM information_schema.tables
+            WHERE table_schema = DATABASE()
+              AND table_name IN (#{names.map { |name| connection.quote(name) }.join(", ")})
+          SQL
+        end
+      end
+
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("8.0")
+      end
+
       # @rbs () -> String
       def current_time_expression
         "CURRENT_TIMESTAMP(6)"

lib/solid_objects/database_adapters/postgresql.rb

@@ -3,6 +3,21 @@
 module SolidObjects
   module DatabaseAdapters
     class Postgresql < DatabaseAdapter
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("13")
+      end
+
+      # PostgreSQL reports a packed integer, 170010 for 17.10, so comparing it
+      # directly would make every server look newer than any minimum.
+      # @rbs () -> Gem::Version
+      def server_version
+        packed = with_connection { |connection| connection.database_version.to_i }
+        return super unless packed.positive?
+
+        Gem::Version.new("#{packed / 10_000}.#{packed % 10_000}")
+      end
+
       # @rbs () -> bool
       def supports_skip_locked?
         true

lib/solid_objects/database_adapters/sqlite.rb

@@ -8,6 +8,11 @@ class Sqlite < DatabaseAdapter
       LOCK_RETRY_MUTEX = Thread::Mutex.new
       LOCK_RETRY_CONDITION = Thread::ConditionVariable.new
 
+      # @rbs () -> Gem::Version?
+      def minimum_server_version
+        Gem::Version.new("3.35")
+      end
+
       # @rbs () -> String
       def current_time_expression
         "STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')"

lib/solid_objects/doctor.rb

@@ -111,6 +111,7 @@ def call
         configuration_check,
         schema_check,
         check_authorization,
+        check_database_server,
         schema_check.failed? ? skipped_runtime : check_runtime,
         ready_for_round_trip?(configuration_check, schema_check) ?
           check_sync_round_trip :
@@ -191,6 +192,20 @@ def check_authorization
       pass(:authorization, "#{allowed.length} of 5 policies allowed a neutral context")
     end
 
+    # @rbs () -> Check
+    def check_database_server
+      adapter = SolidObjects.database_adapter
+      reasons = adapter.unsupported_server_reasons
+      return warn_check(:database_server, reasons.join("; ")) unless reasons.empty?
+
+      pass(
+        :database_server,
+        "#{adapter.class.name.demodulize} #{adapter.server_version} meets the tested minimum"
+      )
+    rescue => error
+      warn_check(:database_server, "#{error.class}: #{error.message}")
+    end
+
     # @rbs () -> Check
     def check_runtime
       cutoff = SolidObjects.database_adapter.database_now -

sig/generated/lib/solid_objects/database_adapter.rbs

@@ -16,6 +16,21 @@ module SolidObjects
     # @rbs (untyped) -> void
     def initialize: (untyped) -> void
 
+    # The oldest server the adapter has been exercised against. Reported rather
+    # than enforced: refusing to boot on an untested server would be a worse
+    # failure than running on one.
+    # @rbs () -> Gem::Version?
+    def minimum_server_version: () -> Gem::Version?
+
+    # @rbs () -> Gem::Version
+    def server_version: () -> Gem::Version
+
+    # @rbs () -> Array[String]
+    def unsupported_server_reasons: () -> Array[String]
+
+    # @rbs () -> Array[String]
+    def additional_server_reasons: () -> Array[String]
+
     # @rbs () -> bool
     def supports_skip_locked?: () -> bool
 

sig/generated/lib/solid_objects/database_adapters/mysql.rbs

@@ -9,6 +9,17 @@ module SolidObjects
       # @rbs () -> String
       def claim_lock: () -> String
 
+      # A non-transactional engine would silently break fenced commits, so the
+      # storage engine is verified rather than assumed.
+      # @rbs () -> Array[String]
+      def additional_server_reasons: () -> Array[String]
+
+      # @rbs () -> Array[String]
+      def non_innodb_tables: () -> Array[String]
+
+      # @rbs () -> Gem::Version?
+      def minimum_server_version: () -> Gem::Version?
+
       # @rbs () -> String
       def current_time_expression: () -> String
 

sig/generated/lib/solid_objects/database_adapters/postgresql.rbs

@@ -3,6 +3,14 @@
 module SolidObjects
   module DatabaseAdapters
     class Postgresql < DatabaseAdapter
+      # @rbs () -> Gem::Version?
+      def minimum_server_version: () -> Gem::Version?
+
+      # PostgreSQL reports a packed integer, 170010 for 17.10, so comparing it
+      # directly would make every server look newer than any minimum.
+      # @rbs () -> Gem::Version
+      def server_version: () -> Gem::Version
+
       # @rbs () -> bool
       def supports_skip_locked?: () -> bool