接続プールごとのクエリログタグ設定を拡張

Rails 7.2 以降、database.yml の query_log_tags キーで接続プール単位のタグ付け制御が可能になり、フォーマットやコメントの前置・後置を個別に上書きできるようになりました。

背景

接続プールごとに異なるタグ付けが必要になるケースが増えているという背景が本変更の出発点です。従来は config.active_record.query_log_tags_format と config.active_record.query_log_tags_prepend_comment で全プールに対して一律のフォーマットとコメント位置を決めていましたが、マルチデータベース構成ではデータベースごとに適切なフォーマットやコメントの有無が求められました。そこで query_log_tags キーをハッシュ化し、format と prepend_comment をプール単位で上書きできる設計が導入されました。これにより、グローバル設定を保持しつつ、個別プールで柔軟に振る舞いを変えることが可能になります。

技術的な変更

設定取得ロジックがハッシュ対応へ拡張されました。activerecord/lib/active_record/database_configurations/hash_config.rb に query_log_tags_config メソッドが追加され、query_log_tags キーの値（ハッシュまたは false）を取得します。続いて query_log_tags_format と query_log_tags_prepend_comment がそれぞれハッシュ内の :format と :prepend_comment を参照するよう変更されました。

@@
       def query_log_tags_config # :nodoc:
         configuration_hash[:query_log_tags]
       end

       def query_log_tags_format # :nodoc:
         return @query_log_tags_format if defined? @query_log_tags_format
-
-        @query_log_tags_format = configuration_hash[:query_log_tags_format]&.to_sym
+        config = query_log_tags_config
+        @query_log_tags_format = (config[:format]&.to_sym if config.is_a?(Hash))
       end

       def query_log_tags_prepend_comment # :nodoc:
         return @query_log_tags_prepend_comment if defined? @query_log_tags_prepend_comment
-
-        @query_log_tags_prepend_comment = (config[:prepend_comment] if config.is_a?(Hash))
+        config = query_log_tags_config
+        @query_log_tags_prepend_comment = (config[:prepend_comment] if config.is_a?(Hash))
       end

タグ付与ロジックがプール設定に応じて分岐するよう改修されました。activerecord/lib/active_record/query_logs.rb では、query_log_tags が false の場合はタグ付与をスキップし、format と prepend_comment の取得は新たに追加されたメソッドで行います。コメントの前置・後置もプールごとに上書き可能となり、従来のグローバル設定をそのまま利用したまま個別挙動をカスタマイズできます。

@@
   # The format can also be overridden per connection pool through the +query_log_tags+
   # key of a +database.yml+ entry. Connections checked out from that pool use the
   # configured +format+, while setting +query_log_tags+ to +false+ instead opts the
   # pool out of tagging entirely. Pools without any explicit configuration fall back
   # to the global defaults:
@@
-    with_query_log_tags_format("sqlcommenter") do |connection|
+    with_db_config(query_log_tags: { format: "sqlcommenter" }) do |connection|
@@
-    with_query_log_tags_format(nil) do |connection|
+    with_db_config do |connection|
@@
+    with_db_config(query_log_tags: false) do |connection|
+      assert_equal "select 1", ActiveRecord::QueryLogs.call("select 1", connection)
+    end

CHANGELOG に新機能が追記され、ユーザーへの可視化が行われました。activerecord/CHANGELOG.md では「Allow query log tags to be configured per connection pool」として、format と prepend_comment のハッシュ指定、タグ付けの無効化オプションが記載されています。

@@ -67,19 +67,29 @@
-    *   Allow the query log tags format to be configured per connection pool.
+    *   Allow query log tags to be configured per connection pool.
@@
-        query_log_tags_format: sqlcommenter
+        query_log_tags:
+          format: sqlcommenter
+          prepend_comment: false
+      replica:
+        database: replica
+        replica: true
+        query_log_tags: false

設計判断

既存キーの拡張で後方互換性を維持する方針が採用されました。新たに query_log_tags_format キーを別に追加する代わりに、既存の query_log_tags キーをハッシュ化し、format と prepend_comment をサブキーとして扱うことで、query_log_tags = true/false の既存挙動を壊さずに機能追加が実現されています。false がプール全体のタグ付け無効化として解釈される点も、設定ミスを防ぐシンプルな設計といえます。

設定取得の集中化によりコードベースのシンプル化が図られました。hash_config.rb に集約されたアクセサメソッドは、プールごとの設定取得を一元化し、query_logs.rb からはシンプルな呼び出しだけで済む構造になっています。この分離はテスト容易性と将来の拡張性を高める意図です。

テストが拡充され、振る舞いの明確化が保証されました。query_logs_test.rb に with_db_config ヘルパを用いた per‑pool の format 上書き、prepend_comment 上書き、タグ付け無効化のテストが追加され、実装とドキュメントの乖離が防がれています。テスト範囲の拡大はリリース時のリグレッションリスク低減に直結します。

まとめ

本PRは、接続プール単位でクエリログタグのフォーマット、コメント前置／後置、さらにはタグ付けの無効化までを柔軟に設定できる機能を追加しました。既存キーのハッシュ化とメソッドの集中化により後方互換性とコードの可読性を保ちながら、マルチデータベース環境での運用性が大幅に向上します。