Merge pull request #28 from cardmagic/agent/trilogy-adapter

fix: select the MySQL adapter for Trilogy

Author: cardmagic

.github/workflows/ci.yml

@@ -94,6 +94,13 @@ jobs:
 
   mysql:
     runs-on: ubuntu-latest
+    # Both clients speak MySQL but report different adapter names, negotiate
+    # different connection collations, and name the same error code
+    # differently, so passing on one proves nothing about the other.
+    strategy:
+      fail-fast: false
+      matrix:
+        client: [ mysql2, trilogy ]
     services:
       mysql:
         image: mysql:8.4
@@ -110,7 +117,7 @@ jobs:
           --health-timeout 5s
           --health-retries 20
     env:
-      SOLID_OBJECTS_DATABASE_URL: mysql2://solid_objects:solid_objects@127.0.0.1:3306/solid_objects_test
+      SOLID_OBJECTS_DATABASE_URL: ${{ matrix.client }}://solid_objects:solid_objects@127.0.0.1:3306/solid_objects_test
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - uses: ruby/setup-ruby@95ef2b042f9d7a56d8268cba8559e2842e2ad01b # v1

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.10.1 - 2026-08-10
+
+- Support Trilogy. Adapter selection matched the client name rather than the
+  protocol, and Trilogy reports `"Trilogy"`, so every Solid Objects call raised
+  `UnsupportedDatabase: unsupported database adapter "Trilogy"` on a database
+  the gem fully supports. Adapter names now resolve through one table of
+  families, `DatabaseAdapter.family`, used by adapter selection, owner-id
+  casting, and wake-up adapter selection alike, so a client cannot be accepted
+  in one place and rejected in another.
+- Compare reconciliation owner ids in the column's own collation.
+  `Instance.orphaned` cast owner primary keys to `CHAR`, and a cast result
+  carries the connection collation rather than the column's. MySQL refuses to
+  compare two collations, so the query raised `Illegal mix of collations`
+  whenever the two differed. That is a property of the client rather than the
+  schema: mysql2 negotiates the database default while Trilogy negotiates
+  `utf8mb4_general_ci`. A mysql2 application that set `collation:` in
+  `database.yml` could already hit this.
+- Recognise a statement interruption from any MySQL client. A synchronous
+  deadline is enforced by asking the server to interrupt the statement, and the
+  interruption was matched only through mysql2's `error_number`. Trilogy names
+  it `error_code`, so a deadline surfaced as a raw
+  `ActiveRecord::StatementTimeout` instead of `SyncEnqueueTimeout`. Both names
+  are read, and Active Record's own classification is trusted first.
+- Run the MySQL suite against both mysql2 and Trilogy in CI, and key
+  adapter-specific test skips to the database family rather than the client
+  name, so a Trilogy run no longer silently skips every MySQL test.
+
 ## 0.10.0 - 2026-08-10
 
 - Report a denied CLI command as a policy decision rather than a crash.

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_objects (0.10.0)
+    solid_objects (0.10.1)
       actioncable (>= 8.0)
       actionpack (>= 8.0)
       actionview (>= 8.0)
@@ -253,6 +253,8 @@ GEM
       unicode-display_width (>= 1.1.1, < 4)
     thor (1.5.0)
     timeout (0.6.1)
+    trilogy (2.12.6)
+      bigdecimal
     tsort (0.2.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
@@ -292,6 +294,7 @@ DEPENDENCIES
   sqlite3 (>= 2.1)
   standard
   steep
+  trilogy (>= 2.7)
 
 CHECKSUMS
   actioncable (8.1.3.1) sha256=e318528295c878a3efdfe25f0f2267c80cb7a76eba41bb5f64d44aa380a3d91b
@@ -380,7 +383,7 @@ CHECKSUMS
   rubocop-rails-omakase (1.1.0) sha256=2af73ac8ee5852de2919abbd2618af9c15c19b512c4cfc1f9a5d3b6ef009109d
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   securerandom (0.4.1) sha256=cc5193d414a4341b6e225f0cb4446aceca8e50d5e1888743fac16987638ea0b1
-  solid_objects (0.10.0)
+  solid_objects (0.10.1)
   sqlite3 (2.9.5-aarch64-linux-gnu) sha256=78075b6337d3d182c6d2b4691049ed45cd220826160c9ea18946bf6a1de200dc
   sqlite3 (2.9.5-aarch64-linux-musl) sha256=18c801185deb4adc01ddb281e8f672a39e3d1729979ca91e39439cd3eac0402d
   sqlite3 (2.9.5-arm-linux-gnu) sha256=1bdfca0c7d63998c60b0f4a8e3c8df2d33800ccc4abd2d612eddbbbc92a4c48b
@@ -397,6 +400,7 @@ CHECKSUMS
   terminal-table (4.0.0) sha256=f504793203f8251b2ea7c7068333053f0beeea26093ec9962e62ea79f94301d2
   thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
   timeout (0.6.1) sha256=78f57368a7e7bbadec56971f78a3f5ecbcfb59b7fcbb0a3ed6ddc08a5094accb
+  trilogy (2.12.6) sha256=2e0f97092150c92fec41acc304c382ad52f5ea98e1eb11073e4f501f80159cf7
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
   tzinfo (2.0.6) sha256=8daf828cc77bcf7d63b0e3bdb6caa47e2272dcfaf4fbfe46f8c3a9df087a829b
   unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42

README.md

@@ -956,7 +956,8 @@ shutdown, retention, and backup guidance.
 Solid Objects supports:
 
 - PostgreSQL 14 or newer
-- MySQL 8.0 or newer using InnoDB
+- MySQL 8.0 or newer using InnoDB, through either the `mysql2` or `trilogy`
+  client
 - SQLite 3.35 or newer
 
 PostgreSQL and MySQL use `FOR UPDATE SKIP LOCKED` when claiming hot-table rows.

app/models/solid_objects/instance.rb

@@ -56,7 +56,7 @@ def orphaned(actor_type:, owner:)
         )
         owner_ids = owner_relation
           .except(:select)
-          .select(cast_id)
+          .select(collated(cast_id))
 
         where(actor_type:).where.not(actor_id: owner_ids)
       end
@@ -70,12 +70,39 @@ def states_for(actor_type:, actor_ids:)
 
       private
 
+      # A cast result carries the connection collation, not the column's, and
+      # MySQL refuses to compare two collations. Which collation a connection
+      # uses is a property of the client rather than the schema: mysql2
+      # negotiates the database default while Trilogy negotiates
+      # utf8mb4_general_ci, so the comparison is pinned to the column's own.
+      # @rbs (untyped) -> untyped
+      def collated(node)
+        collation = owner_id_collation
+        return node unless collation
+
+        Arel::Nodes::InfixOperation.new(
+          "COLLATE",
+          node,
+          Arel::Nodes::SqlLiteral.new(collation)
+        )
+      end
+
+      # @rbs () -> String?
+      def owner_id_collation
+        return nil unless DatabaseAdapter.family(connection) == :mysql
+
+        collation = columns_hash["actor_id"]&.collation
+        return nil unless collation&.match?(/\A[a-zA-Z0-9_]+\z/)
+
+        collation
+      end
+
       # @rbs () -> String
       def owner_id_cast_type
-        case connection.adapter_name
-        when /mysql/i
+        case DatabaseAdapter.family(connection)
+        when :mysql
           "CHAR"
-        when /postgres/i
+        when :postgresql
           "VARCHAR"
         else
           "TEXT"

docs/architecture.md

@@ -41,6 +41,10 @@ The host application owns:
 ## Database coordination adapters
 
 Solid Objects supports PostgreSQL 14+, MySQL 8.0+ with InnoDB, and SQLite 3.35+.
+MySQL is reached through either the `mysql2` or `trilogy` client. Adapter names
+are client names rather than protocol names, so every decision that depends on
+the database resolves through `DatabaseAdapter.family` rather than matching an
+adapter name in place.
 
 One adapter capability object is selected from the Active Record connection. It supplies claim locking and database-time expressions. Unsupported adapter families fail when first used. Minimum server-version and storage-engine checks are documented operating requirements; automatic boot-time enforcement and classified contention retries remain hardening work.
 

docs/local-testing.md

@@ -48,10 +48,17 @@ docker run -d --name so-redis -p 6380:6379 redis:7-alpine
 SOLID_OBJECTS_DATABASE_URL=mysql2://solid_objects:solid_objects@127.0.0.1:3307/solid_objects_test \
   bundle exec rake test
 
+SOLID_OBJECTS_DATABASE_URL=trilogy://solid_objects:solid_objects@127.0.0.1:3307/solid_objects_test \
+  bundle exec rake test
+
 SOLID_OBJECTS_REDIS_URL=redis://127.0.0.1:6380/15 \
   bundle exec rake test TEST=test/integration/redis_wake_up_test.rb
 ```
 
+Run both MySQL clients. They report different adapter names, negotiate
+different connection collations, and name the same error code differently, so a
+pass on one says nothing about the other. Recreate the database between them.
+
 Stop them with `docker rm -f so-mysql so-redis`.
 
 ## Recreating a database between runs

docs/roadmap.md

@@ -45,7 +45,9 @@
   shutdown is requested, and dead process records plus expired message and
   process history are pruned on their own intervals without an application
   scheduling its own job
-- SQLite, PostgreSQL, and MySQL integration suites
+- SQLite, PostgreSQL, and MySQL integration suites, with MySQL run against both
+  the `mysql2` and `trilogy` clients because an adapter name, a connection
+  collation, and an error code name all differ between them
 - Opt-in cross-process wake-up on PostgreSQL through `WakeUpAdapters.for`, with
   a listening connection per waiting thread and release on supervisor shutdown
 - Opt-in cross-process wake-up on Redis, the option for MySQL applications,

lib/solid_objects.rb

@@ -46,6 +46,7 @@
 require "solid_objects/actor_view"
 require "solid_objects/actor_channel"
 require "solid_objects/action_cable_broadcast_adapter"
+require "solid_objects/database_adapter"
 require "solid_objects/wake_up"
 require "solid_objects/wake_up_adapters/postgresql"
 require "solid_objects/wake_up_adapters/redis"

lib/solid_objects/database_adapter.rb

@@ -7,15 +7,35 @@ class DatabaseAdapter
     TRANSACTION_CLOCK = :solid_objects_transaction_clock
     TRANSACTION_CLOCK_SCOPE = :solid_objects_transaction_clock_scope
 
+    # An adapter name is a client name, not a protocol name. Trilogy reports
+    # "Trilogy" while speaking MySQL, so a pattern that only knows the mysql2
+    # gem rejects a database Solid Objects fully supports. Every decision that
+    # depends on the database goes through this one table, so a client cannot
+    # be accepted in one place and rejected in another.
+    FAMILIES = {
+      postgresql: /postgres/i,
+      mysql: /mysql|trilogy/i,
+      sqlite: /sqlite/i
+    }.freeze
+
     class << self
+      # @rbs (untyped) -> Symbol?
+      def family(connection)
+        adapter_name = connection.adapter_name
+        FAMILIES.each do |family, pattern|
+          return family if adapter_name.match?(pattern)
+        end
+        nil
+      end
+
       # @rbs (untyped) -> DatabaseAdapter
       def for(connection)
-        case connection.adapter_name
-        when /postgres/i
+        case family(connection)
+        when :postgresql
           DatabaseAdapters::Postgresql.new(connection)
-        when /mysql/i
+        when :mysql
           DatabaseAdapters::Mysql.new(connection)
-        when /sqlite/i
+        when :sqlite
           DatabaseAdapters::Sqlite.new(connection)
         else
           raise UnsupportedDatabase, "unsupported database adapter #{connection.adapter_name.inspect}"