Introducing Trilogy: a new database adapter for Ruby on Rails

A third adapter for Rails and MySQL

GitHub has open sourced the database adapter that connects its Ruby on Rails applications to MySQL-compatible servers. The new activerecord-trilogy-adapter lets Rails applications use the Trilogy client library in place of the default mysql2-based adapter.

Trilogy itself—a client library for MySQL-compatible databases built for performance, flexibility, and embeddability—was released with its Ruby wrapper in December. The Active Record adapter rounds out the offering.

Why GitHub built another client

Trilogy is tuned for environments like the Ruby VM, where handling blocking syscalls and managing dynamic memory allocation carefully makes a measurable difference. It implements the MySQL network protocol itself, which minimizes compilation dependencies and improves portability. That design also avoids the libmariadb/libmysqlclient dependency the mysql2 gem carries, cutting down on installation friction and version mismatch problems, and reduces the number of times data is copied in memory when packets are built and parsed.

GitHub started with the original mysql gem, moved to mysql2 in 2011, and eventually found that still wasn't sufficient for its performance and reliability needs. Hailey Somerville and Brian Lopez developed Trilogy to close that gap, and it has handled all query activity for GitHub's Rails monolith since 2015. The name is a nod to its place in the sequence: it's the third adapter GitHub has used, and it queries sequel.

Getting the adapter open sourced has been a long effort, championed first by Aaron Patterson and then by Eileen M. Uchitelle. Their goal was to extract the database-communication behavior GitHub had accumulated and feed it back into Active Record itself, most recently in the form of deferred connection verification and automatic reconnection.

Considerations before switching

For applications running against MySQL-compatible servers, the Trilogy adapter should be a drop-in replacement for the mysql2-based adapter and is likely to be more efficient under heavy query loads. That said, Trilogy is production-tested primarily against GitHub's own workloads; it may not support every protocol feature other database configurations rely on. Testing in a staging environment first is advisable.

One important caveat: the adapter currently works only with the in-development main branch of rails/rails, the version GitHub uses internally. Once Active Record 7.1.0 ships, the team will maintain a release compatible with the current supported release series.