Skip to content

SYSTEM Cited by 1 source

activerecord-sql_commenter gem

What it is

activerecord-sql_commenter is a PlanetScale-authored Ruby gem that makes Rails 7's native query_log_tags feature emit query-annotation comments in the SQLCommenter format (Google's open standard) instead of Rails's default tag format.

Why it exists

Rails 7 added native support for automatically annotating every ActiveRecord-issued SQL query with structured metadata (controller, action, job, etc.) under config.active_record.query_log_tags_enabled. The default emission format is a Rails convention — /*application:Api,controller:users,action:show*/ — which is not what the SQLCommenter spec defines. The SQLCommenter format uses single-quoted values with = separators: /*application='Api',controller='users',action='show'*/.

Query-analysis tools that parse SQLCommenter natively (Google Cloud SQL Insights, PlanetScale Insights, observability vendors) can't extract tags from the Rails-default format. The activerecord-sql_commenter gem rewrites the Rails emission into SQLCommenter bytes so the downstream tooling just works.

How to use it

One Gemfile entry + the standard Rails query_log_tags envelope:

# Gemfile
gem "activerecord-sql_commenter", require: "active_record/sql_commenter"

# config/application.rb
config.active_record.query_log_tags_enabled = true
config.active_record.query_log_tags = [:application, :controller, :action, :job]
config.active_record.cache_query_log_tags = true

After which every ActiveRecord query is emitted with a trailing SQLCommenter-formatted comment carrying the configured keys for the current request (Source: sources/2026-04-21-planetscale-identifying-slow-rails-queries-with-sqlcommenter).

Relationship to other PlanetScale Rails gems

  • planetscale_rails — orthogonal system. That gem runs ActiveRecord migrations against PlanetScale branches + opens deploy requests; this gem rewrites the query-comment emission format. They solve completely different problems (schema-change lifecycle vs query-log-emission bytes) and are used independently. A Rails app talking to PlanetScale MySQL typically uses both — planetscale_rails in the CI/deploy path, activerecord-sql_commenter in the production runtime.
  • Marginalia — pre-history. Basecamp's original Rails-query-tagging gem that Rails 7 absorbed into the framework. activerecord-sql_commenter composes with Rails 7's absorbed framework feature; Marginalia is no longer required.

Relationship to the Rails framework

The gem is a thin format shim on top of Rails 7's query_log_tags primitive. It does not add new tag vocabulary, does not replace the tag selection DSL, and does not intercept queries outside the Rails 7 QueryLogs pipeline. require: "active_record/sql_commenter" is the activation hook — once required, the gem registers its formatter as the active one.

Rails 8 and later are expected to make SQLCommenter format a first-class built-in option, which would eventually obsolete the gem. At 2022-06-29 publication date + 2026-04-21 re-surface date, the gem remains in active maintenance.

Seen in

Scope the source does not cover

  • Internal implementation details — is the gem a subscriber? a monkey-patch? a custom ActiveRecord::QueryLogs formatter registration? The post does not say.
  • Which Rails versions are supported (Rails 7+ implied by query_log_tags dependency; exact minimum not disclosed).
  • Whether the gem propagates OpenTelemetry traceparent headers (SQLCommenter spec supports traceparent; not mentioned in the post).
  • Interaction with custom tag providers (Rails 7's query_log_tags supports custom key-value procs; gem's handling of custom keys not specified).
  • Performance overhead of format rewriting per query (cache_query_log_tags memoisation mitigates; per-request cost not quantified).
Last updated · 378 distilled / 1,213 read