rails-profiler 0.30.7 → 0.30.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f606ebbea7d5aecac4c62d789f07ddab9b4942269d4f8246441b3f37bc3220e7
-  data.tar.gz: 53f89719e215f799ba93d436fbace90ee45b38b0ec8d7f453cd2d2410e50cc0e
+  metadata.gz: a3a3ebc22965fd603d63bafecef777474fc488912625ac2950e618566bce8f09
+  data.tar.gz: e82aa1ce06e0f24cfb65b86fe01a942557851735f596edb3172c3fd00d7941f3
 SHA512:
-  metadata.gz: 3fe0149c4be61248f1fbfdfa381083a01710248c81a8e02dfec015bd721e7ff0238c2296dbcb4df141701603f8f1a3b03cabd4ef839c3031006215680e34bed9
-  data.tar.gz: 1aca6f23e91b25b303db9d68f970f4878a222bb02cb5d1e5b89533f07c99306d38bec2f004b8471d8790bb6990b8a59a2a68a86cc00e50becb23b85020f8bdae
+  metadata.gz: 857313cb42832f5992a26897cbe6cef4d7dd66d6f59b5fccc63c8758db55da54cd6e3587e254e3d1410db561b668782ef8f3fcda73e4535235efba1e9a34c9be
+  data.tar.gz: 1bd504a236e7c548011ceed8dcc1488b21bc89400d824306c2f90d8b1817290768a10264265ee093f78d295f873b72a250a00a96fc5fe04f54f85cd2d63597db

data/CHANGELOG.md

@@ -19,6 +19,78 @@ every commit of every tag interval is accounted for one way or the other.
 
 ## [Unreleased]
 
+## [0.30.9] - 2026-10-04
+
+<!-- stamped -->
+
+### Security
+
+- **Database:** Explain only read-only queries. The **Explain** button, `POST /_profiler/api/explain`
+  and the MCP `explain_query` tool ran `EXPLAIN ANALYZE` on any stored query, and PostgreSQL's
+  `EXPLAIN ANALYZE` runs the statement it explains: explaining a `DELETE`, `UPDATE` or `INSERT` the
+  application had just run ran it a second time, for real. Only statements starting with `SELECT`,
+  `WITH`, `TABLE` or `VALUES` are explained now, and a writing CTE, `SELECT ... INTO`, `FOR UPDATE`
+  or a second statement is refused too, with a 422 from the endpoint and an error from the MCP tool.
+  The probe also runs in a transaction that is always rolled back, read-only on PostgreSQL.
+  Upgrading: nothing to set, and no setting brings back the explaining of writes, since the old
+  behaviour was to run them again; to see the plan of a write, run it yourself in `psql` between
+  `BEGIN` and `ROLLBACK`, as the README shows.
+- **Database:** Run the Explain probe on a connection of its own, opened outside the pool and closed
+  afterwards, so that nothing it does to its session outlives it: a `SELECT pg_try_advisory_lock(...)`
+  explained from a profile left the lock held by a connection of the pool. On PostgreSQL the probe
+  is also limited to 30 seconds (`statement_timeout`), and its EXPLAIN goes by the extended
+  protocol, which refuses a second statement.
+
+### Fixed
+
+- **Database:** Put bind values back correctly when explaining a query with ten binds or more
+  (`$10` was read as `$1` followed by `0`), and leave alone a `?` or `$1` inside a string literal or
+  inside a value already put back.
+
+## [0.30.8] - 2026-10-04
+
+<!-- stamped -->
+
+### Fixed
+
+- **Env overrides:** Keep every override when several are set, deleted or reset at the same
+  time, from threads of the web process or from Sidekiq processes. Each writer read the file,
+  changed it and saved it over the others' changes, and a reader could see a half-written file as
+  no override at all. The file is now changed under a lock (`env_overrides.json.lock`, next to
+  it) and replaced in one step.
+
+### Security
+
+- **Env overrides:** Stop applying the environment variable overrides saved from the Env tab or
+  the MCP env tools in production, and while the profiler is disabled. They were written into
+  `ENV` at every boot whatever `enabled` said and whatever the environment, so an
+  `env_overrides.json` left under `tmp/` and shipped with a deployment changed the environment of
+  the production application, and an application with `config.enabled = false` still had them
+  applied without a word. Sidekiq jobs and console evaluations, which apply them again, follow the
+  same rules. When overrides are left out, the boot logs one warning to `Rails.logger` with the
+  file, the number of overrides and the reason, never a name or a value.
+- **Env overrides:** Apply them at boot once the application's `config/initializers` have run,
+  where `enabled` is decided, instead of before. An initializer of the application that reads
+  `ENV` while it runs no longer sees them; requests, jobs, eager loading and `after_initialize`
+  still do.
+- **Env overrides:** Resetting one override, or all of them, from the Env tab or the MCP env
+  tools no longer writes into `ENV` the "original" values saved in `env_overrides.json` in
+  production, nor while the profiler is disabled: those values come from the machine that wrote
+  the file, so a reset could put a development value into a production variable, or delete it.
+  There, a reset restores only the variables the running process changed itself, to the values
+  they had before.
+- **Env overrides:** In production, or with the profiler disabled, typing back in the Env tab the
+  original value the overrides file shows for a variable now records the running value first, so
+  a later reset puts it back instead of keeping the file's value. A reset also restores a variable
+  this process changed even when its entry has gone from the file. The `reset_env_var` MCP tool
+  now says whether the original value was restored in the process or `ENV` was left unchanged,
+  and no longer prints a value, masked or not.
+- **Upgrading:** to apply the env overrides while the profiler is disabled outside production,
+  as before, set `config.apply_env_overrides_when_disabled = true`. Nothing applies them in
+  production. If an initializer of yours needs them, call `Profiler.env_override_store.apply!` at
+  the end of `config/initializers/profiler.rb`; initializers loaded after it then see them, under
+  the same rules.
+
 ## [0.30.7] - 2026-10-04
 
 <!-- stamped -->

data/app/controllers/profiler/api/env_vars_controller.rb

@@ -32,7 +32,8 @@ module Profiler
           render json: { key: key, value: nil, deleted: true, override: redacted_override(key) }
         else
           current_original = Profiler.env_override_store.all_overrides.dig(key, "original")
-          if current_original == value.to_s
+          # Where the overrides are blocked, set records this process's value, which reset would not.
+          if current_original == value.to_s && Profiler.env_override_store.blocked_reason.nil?
             Profiler.env_override_store.reset(key)
           else
             Profiler.env_override_store.set(key, value.to_s)

data/lib/profiler/configuration.rb

@@ -35,6 +35,7 @@ module Profiler
                   :track_http, :slow_http_threshold, :http_skip_hosts, :http_backtrace_depth,
                   :track_jobs,
                   :track_console,
+                  :apply_env_overrides_when_disabled,
                   :track_tests,
                   :track_mailers, :capture_mail_body, :sanitize_mailer_recipients, :mailer_skip_actions,
                   :compress_bodies, :compress_body_threshold,
@@ -77,6 +78,7 @@ module Profiler
       @http_backtrace_depth = 40
       @track_jobs = true
       @track_console = true
+      @apply_env_overrides_when_disabled = false
       @track_tests = false
       @track_mailers = true
       @capture_mail_body = false

data/lib/profiler/env_override_store.rb

@@ -8,63 +8,108 @@ module Profiler
     DELETED_SENTINEL = "__profiler_deleted__"
     RESTORE_SENTINEL = "__profiler_restore__"
 
+    # Why the persisted overrides are left out of ENV, as logged at boot.
+    BLOCKED_REASONS = {
+      production: "persisted overrides are never applied in production; " \
+                  "delete the file if it was deployed by mistake",
+      disabled: "the profiler is disabled; set " \
+                "config.apply_env_overrides_when_disabled = true to apply them anyway"
+    }.freeze
+
     # File format: { "KEY" => { "value" => "...", "original" => "..." } }
     # Sentinels for "value":
     #   DELETED_SENTINEL  → ENV.delete(key)
     #   RESTORE_SENTINEL  → restore ENV[key] to "original" (cleaned up after apply!)
 
+    def initialize
+      # What ENV held in this process before set, delete or apply! changed a key. Where the
+      # overrides are blocked, a reset restores these and never the file's "original" values,
+      # which come from whatever machine wrote the file.
+      @process_originals = {}
+      @process_originals_lock = Mutex.new
+    end
+
     def set(key, value)
-      overrides = load_overrides
-      original = original_for(overrides, key)
-      overrides[key] = { "value" => value.to_s, "original" => original }
-      save_overrides(overrides)
+      remember_process_original(key)
+      update_overrides do |overrides|
+        overrides[key] = { "value" => value.to_s, "original" => original_for(overrides, key) }
+      end
     rescue => e
       warn "[Profiler] EnvOverrideStore: failed to set #{key}: #{e.message}"
     end
 
     def delete(key)
-      overrides = load_overrides
-      original = original_for(overrides, key)
-      overrides[key] = { "value" => DELETED_SENTINEL, "original" => original }
-      save_overrides(overrides)
+      remember_process_original(key)
+      update_overrides do |overrides|
+        overrides[key] = { "value" => DELETED_SENTINEL, "original" => original_for(overrides, key) }
+      end
     rescue => e
       warn "[Profiler] EnvOverrideStore: failed to delete #{key}: #{e.message}"
     end
 
+    # Returns whether ENV was written in this process.
     def reset(key)
-      overrides = load_overrides
-      entry = overrides[key]
-      return unless entry
-
-      original = entry["original"]
-      # Keep a RESTORE entry so Sidekiq workers pick it up on next job
-      overrides[key] = { "value" => RESTORE_SENTINEL, "original" => original }
-      save_overrides(overrides)
+      entry = nil
+      update_overrides do |overrides|
+        entry = overrides[key]
+        # Keep a RESTORE entry so Sidekiq workers pick it up on next job
+        overrides[key] = { "value" => RESTORE_SENTINEL, "original" => entry["original"] } if entry
+      end
 
       # Apply immediately to the current (web) process
-      original.nil? ? ENV.delete(key) : ENV[key] = original
+      restore_env(key, entry, blocked: blocked_reason)
     rescue => e
       warn "[Profiler] EnvOverrideStore: failed to reset #{key}: #{e.message}"
     end
 
     def reset_all
-      overrides = load_overrides
-      restore_overrides = {}
-
-      overrides.each do |key, entry|
-        original = entry.is_a?(Hash) ? entry["original"] : nil
-        # Apply immediately to the current (web) process
-        original.nil? ? ENV.delete(key) : ENV[key] = original
-        # Leave a RESTORE sentinel for Sidekiq workers to pick up
-        restore_overrides[key] = { "value" => RESTORE_SENTINEL, "original" => original }
+      originals = {}
+      update_overrides do |overrides|
+        overrides.each do |key, entry|
+          originals[key] = entry.is_a?(Hash) ? entry["original"] : nil
+          # Leave a RESTORE sentinel for Sidekiq workers to pick up
+          overrides[key] = { "value" => RESTORE_SENTINEL, "original" => originals[key] }
+        end
       end
 
-      restore_overrides.empty? ? clear : save_overrides(restore_overrides)
+      # Apply immediately to the current (web) process
+      blocked = blocked_reason
+      originals.each { |key, original| restore_env(key, { "original" => original }, blocked: blocked) }
     rescue => e
       warn "[Profiler] EnvOverrideStore: failed to reset all: #{e.message}"
     end
 
+    # Why the persisted overrides must not reach ENV in this process, or nil when they may.
+    def blocked_reason
+      return :production if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+
+      config = Profiler.configuration
+      return :disabled unless config.enabled || config.apply_env_overrides_when_disabled
+
+      nil
+    end
+
+    # Applies the overrides at boot, or says once in the log why they are left out. The message
+    # carries the file and the number of keys only, never a key or a value.
+    def apply_at_boot!(logger)
+      reason = blocked_reason
+      return apply! unless reason
+      return if @boot_warning_logged
+
+      count = all_overrides.size
+      return if count.zero?
+
+      @boot_warning_logged = true
+      noun, verb = count == 1 ? %w[override was] : %w[overrides were]
+      logger&.warn("[Profiler] #{count} persisted environment #{noun} in #{override_file_path} " \
+                   "#{verb} not applied: #{BLOCKED_REASONS.fetch(reason)}.")
+    rescue => e
+      warn "[Profiler] EnvOverrideStore: failed to check overrides at boot: #{e.message}"
+    end
+
     def apply!
+      return if blocked_reason
+
       overrides = load_overrides
       restore_keys = []
 
@@ -72,6 +117,8 @@ module Profiler
         value    = entry.is_a?(Hash) ? entry["value"]    : entry
         original = entry.is_a?(Hash) ? entry["original"] : nil
 
+        remember_process_original(key) unless value == RESTORE_SENTINEL
+
         case value
         when DELETED_SENTINEL
           ENV.delete(key)
@@ -84,8 +131,13 @@ module Profiler
       end
 
       if restore_keys.any?
-        restore_keys.each { |k| overrides.delete(k) }
-        save_overrides(overrides)
+        # Read again under the lock: another writer may have changed the file since.
+        update_overrides do |current|
+          restore_keys.each do |k|
+            entry = current[k]
+            current.delete(k) if entry.is_a?(Hash) && entry["value"] == RESTORE_SENTINEL
+          end
+        end
       end
     rescue => e
       warn "[Profiler] EnvOverrideStore: failed to apply overrides: #{e.message}"
@@ -105,13 +157,34 @@ module Profiler
     end
 
     def clear
-      FileUtils.rm_f(override_file_path)
+      with_lock { FileUtils.rm_f(override_file_path) }
     rescue => e
       warn "[Profiler] EnvOverrideStore: failed to clear: #{e.message}"
     end
 
     private
 
+    def remember_process_original(key)
+      @process_originals_lock.synchronize do
+        @process_originals[key] = ENV[key] unless @process_originals.key?(key)
+      end
+    end
+
+    # Puts a reset key back to its original value and returns whether ENV was written. Where the
+    # overrides are blocked, or the file has no entry for the key, only a key this process
+    # changed itself is touched, back to the value it had here; ENV is left alone for any other.
+    def restore_env(key, file_entry, blocked:)
+      changed_here, process_original = @process_originals_lock.synchronize do
+        [@process_originals.key?(key), @process_originals.delete(key)]
+      end
+      from_process = blocked || file_entry.nil?
+      return false if from_process && !changed_here
+
+      original = from_process ? process_original : file_entry["original"]
+      original.nil? ? ENV.delete(key) : ENV[key] = original
+      true
+    end
+
     def original_for(overrides, key)
       overrides.key?(key) ? overrides[key]["original"] : ENV[key]
     end
@@ -129,10 +202,36 @@ module Profiler
       {}
     end
 
-    def save_overrides(overrides)
+    # Reads, changes and writes the file under the lock, so that the web process, its threads and
+    # the Sidekiq processes never save over each other's changes. The file is removed when the
+    # block leaves it empty.
+    def update_overrides
+      with_lock do
+        overrides = load_overrides
+        yield overrides
+        overrides.empty? ? FileUtils.rm_f(override_file_path) : save_overrides(overrides)
+      end
+    end
+
+    # An exclusive flock on a file next to the overrides file. Not reentrant: never nest it.
+    def with_lock
       path = override_file_path
       FileUtils.mkdir_p(path.dirname)
-      File.write(path, JSON.generate(overrides))
+      File.open("#{path}.lock", File::RDWR | File::CREAT, 0o644) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    # Written to a temporary file then renamed over the old one, so that a reader never sees a
+    # half-written file, which would parse as no override at all.
+    def save_overrides(overrides)
+      path = override_file_path
+      tmp = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
+      File.write(tmp, JSON.generate(overrides))
+      File.rename(tmp, path)
+    ensure
+      FileUtils.rm_f(tmp) if tmp
     end
   end
 end

data/lib/profiler/explain_runner.rb

@@ -1,9 +1,23 @@
 # frozen_string_literal: true
 
+require "profiler/sql_statement"
+
 module Profiler
   # Shared service for running EXPLAIN ANALYZE on a stored query.
   # Used by both the HTTP API controller and the MCP explain_query tool.
+  #
+  # Only read-only statements are explained: PostgreSQL's EXPLAIN ANALYZE runs the
+  # statement, so explaining a write would replay it. The probe itself runs, for
+  # what no reading of the statement can rule out (a function with a side effect),
+  # on a connection of its own that is closed afterwards, in a transaction that is
+  # always rolled back, read-only and time-limited on PostgreSQL.
   module ExplainRunner
+    # An ArgumentError, so callers answer it as a bad request (422, MCP error).
+    class UnsafeStatementError < ArgumentError; end
+
+    # PostgreSQL's EXPLAIN ANALYZE runs the query: a slow one is stopped after this.
+    PROBE_STATEMENT_TIMEOUT = "30s"
+
     # @param profile_token [String]
     # @param query_index   [Integer]
     # @return [Hash] { result:, format: "json"|"text", adapter: String }
@@ -35,11 +49,14 @@ module Profiler
 
       conn    = ActiveRecord::Base.connection
       adapter = conn.adapter_name.downcase
+      refusal = SqlStatement.read_only_refusal(sql, dialect: dialect_for(adapter))
+      raise UnsafeStatementError, refusal if refusal
+
       full_sql = reconstruct_sql(sql, binds, conn, adapter)
 
       explain_sql, format = build_explain_statement(full_sql, adapter)
 
-      rows = conn.exec_query(explain_sql, "EXPLAIN").to_a
+      rows = probe(explain_sql, adapter)
 
       result = if format == "json"
         # PostgreSQL / MySQL return JSON in rows[0]["QUERY PLAN"] or rows[0]["EXPLAIN"]
@@ -55,21 +72,51 @@ module Profiler
     private
 
     def self.reconstruct_sql(sql, binds, conn, adapter)
-      return sql if binds.empty?
+      SqlStatement.substitute(sql, binds, dialect: dialect_for(adapter)) { |value| conn.quote(value) }
+    end
 
-      if adapter.include?("postgresql")
-        result = sql.dup
-        binds.each_with_index do |value, i|
-          result = result.gsub("$#{i + 1}", conn.quote(value))
+    def self.dialect_for(adapter)
+      if adapter.include?("postgresql") then :postgresql
+      elsif adapter.include?("mysql") || adapter.include?("trilogy") then :mysql
+      else :sqlite
+      end
+    end
+
+    # Runs on a connection of its own, opened outside the pool and closed
+    # afterwards, so that nothing the probe does to its session outlives it (an
+    # advisory lock, a setting, a LISTEN), the application's own transaction is
+    # never touched, and a full pool does not keep Explain waiting.
+    # The transaction is always rolled back. On PostgreSQL it is also read-only and
+    # time-limited, and the EXPLAIN goes by the extended protocol, which refuses
+    # more than one statement: a COMMIT slipped in could not end the read-only
+    # transaction. Neither MySQL's EXPLAIN nor SQLite's EXPLAIN QUERY PLAN runs the
+    # statement.
+    def self.probe(explain_sql, adapter)
+      conn = open_probe_connection
+      begin
+        rows = nil
+        conn.transaction do
+          if adapter.include?("postgresql")
+            conn.execute("SET TRANSACTION READ ONLY")
+            conn.execute("SET LOCAL statement_timeout = #{conn.quote(PROBE_STATEMENT_TIMEOUT)}")
+            rows = conn.raw_connection.exec_params(explain_sql, []).to_a
+          else
+            rows = conn.exec_query(explain_sql, "EXPLAIN").to_a
+          end
+          raise ActiveRecord::Rollback
         end
-        result
+        rows
+      ensure
+        conn.disconnect!
+      end
+    end
+
+    def self.open_probe_connection
+      db_config = ActiveRecord::Base.connection_pool.db_config
+      if db_config.respond_to?(:new_connection) # Active Record 7.2 and later
+        db_config.new_connection
       else
-        # MySQL / SQLite: replace ? sequentially
-        result = sql.dup
-        binds.each do |value|
-          result = result.sub("?", conn.quote(value))
-        end
-        result
+        ActiveRecord::Base.public_send(db_config.adapter_method, db_config.configuration_hash)
       end
     end
 

data/lib/profiler/mcp/server.rb

@@ -139,7 +139,7 @@ module Profiler
           ),
           define_tool(
             name: "explain_query",
-            description: "Run EXPLAIN ANALYZE on a specific query from a profile. Returns the query execution plan with cost and row estimates. Only available in development/test environments.",
+            description: "Run EXPLAIN ANALYZE on a specific query from a profile. Returns the query execution plan with cost and row estimates. Only read-only statements (SELECT, WITH ... SELECT, TABLE, VALUES) are explained, in a transaction always rolled back; other queries return an error. Only available in development/test environments.",
             input_schema: {
               properties: {
                 token: { type: "string", description: "Profile token, or 'latest' for the most recent profile (required)" },

data/lib/profiler/mcp/tools/reset_env_var.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "../slave_support"
-require_relative "../../redaction"
 
 require "uri"
 
@@ -24,11 +23,10 @@ module Profiler
             return [{ type: "text", text: "No active override for #{key}." }]
           end
 
-          original = overrides[key]["original"]
-          Profiler.env_override_store.reset(key)
+          restored = Profiler.env_override_store.reset(key)
 
-          restored = original.nil? ? "(unset)" : Profiler::Redaction.env_value(key, original)
-          [{ type: "text", text: "Reset #{key} to original value: #{restored}" }]
+          done = restored ? "original value restored" : "ENV left unchanged"
+          [{ type: "text", text: "Reset #{key}: override removed, #{done} in this process." }]
         end
       end
     end

data/lib/profiler/railtie.rb

@@ -6,10 +6,6 @@ module Profiler
   class Railtie < Rails::Railtie
     config.profiler = ActiveSupport::OrderedOptions.new
 
-    initializer "profiler.apply_env_overrides" do
-      Profiler.env_override_store.apply!
-    end
-
     initializer "profiler.set_configs" do |app|
       # Set default configuration for Rails environment
       Profiler.configure do |config|
@@ -103,6 +99,13 @@ module Profiler
       end
     end
 
+    # After the application's config/initializers, so that `enabled` is the application's own.
+    # Declared last: an initializer without `after:` runs after the one declared before it, so
+    # one declared below this one would move past the application's initializers too.
+    initializer "profiler.apply_env_overrides", after: :load_config_initializers do
+      Profiler.env_override_store.apply_at_boot!(Rails.logger)
+    end
+
     console do
       next unless Profiler.configuration.enabled && Profiler.configuration.track_console
 

data/lib/profiler/sql_statement.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Profiler
+  # Reads a stored SQL statement the way the database would, one token at a time:
+  # comments, string literals and quoted identifiers are never mistaken for keywords
+  # or placeholders. Used by ExplainRunner to refuse anything but a read, and to put
+  # the bind values back into the statement.
+  module SqlStatement
+    # The first keyword of a statement EXPLAIN may run.
+    READ_ONLY_VERBS = %w[SELECT WITH TABLE VALUES].freeze
+
+    # Keywords that make a read-only verb write or lock: a CTE that writes,
+    # SELECT ... INTO (and MySQL's INTO OUTFILE), FOR UPDATE / FOR SHARE,
+    # LOCK IN SHARE MODE. Matched as whole words outside literals, so a column
+    # named `updated_at` is fine and an unquoted column named `share` is refused.
+    WRITE_KEYWORDS = %w[INSERT UPDATE DELETE MERGE TRUNCATE DROP ALTER CREATE INTO LOCK SHARE].freeze
+
+    Token = Struct.new(:type, :text)
+
+    # 'it''s' everywhere; 'it\'s' too where a backslash escapes. An unterminated
+    # literal runs to the end: the database refuses such a statement anyway.
+    PLAIN_LITERAL = /[Nn]?'(?:[^']|'')*'?/m
+    BACKSLASH_LITERAL = /[Nn]?'(?:[^'\\]|''|\\.)*'?/m
+    ESCAPE_LITERAL = /[Ee]'(?:[^'\\]|''|\\.)*'?/m
+
+    # Dialects differ in what a literal or a comment is: a backslash escapes a quote
+    # in every MySQL string but only in PostgreSQL's E'...' strings, dollar quoting
+    # is PostgreSQL's, backticks quote identifiers in MySQL and SQLite, MySQL starts
+    # a comment with `#` and needs a space after `--`, and only PostgreSQL nests
+    # block comments.
+    DIALECTS = %i[postgresql mysql sqlite].freeze
+
+    # @param dialect [Symbol] one of DIALECTS
+    # @return [String, nil] why the statement must not be explained, or nil when it reads only
+    def self.read_only_refusal(sql, dialect:)
+      all = tokenize(sql, dialect)
+      if dialect == :mysql && all.any? { |t| t.type == :comment && t.text.start_with?("/*!") }
+        return refusal("it holds a MySQL executable comment (/*! ... */)")
+      end
+
+      tokens = all.reject { |t| %i[space comment].include?(t.type) }
+      first = tokens.find { |t| t.type != :punct || t.text != "(" }
+      return refusal("it is empty") if first.nil?
+
+      verb = first.text.upcase
+      return refusal("it starts with #{verb}") unless first.type == :word && READ_ONLY_VERBS.include?(verb)
+
+      tokens.each_with_index do |token, i|
+        if token.type == :word && WRITE_KEYWORDS.include?(token.text.upcase)
+          return refusal("it contains #{token.text.upcase}")
+        end
+        if token.type == :punct && token.text == ";" && i != tokens.size - 1
+          return refusal("it holds more than one statement")
+        end
+      end
+      nil
+    end
+
+    # Replaces each placeholder by its quoted value in a single pass: `$1`, `$10`...
+    # by number (PostgreSQL), or `?` in order (MySQL, SQLite). Placeholders inside
+    # literals or comments stay as they are, and a substituted value is never read
+    # again. A placeholder without a value is left in place.
+    def self.substitute(sql, binds, dialect:, &quote)
+      return sql if binds.empty?
+
+      position = 0
+      tokenize(sql, dialect).map do |token|
+        index = case token.type
+                when :numbered then token.text[1..].to_i - 1
+                when :question then (position += 1) - 1
+                end
+        index && index >= 0 && index < binds.size ? quote.call(binds[index]) : token.text
+      end.join
+    end
+
+    def self.refusal(reason)
+      "EXPLAIN refused: only read-only statements (SELECT, WITH ... SELECT, TABLE, VALUES) " \
+        "are explained, and #{reason}. PostgreSQL's EXPLAIN ANALYZE runs the statement it explains."
+    end
+
+    # Splits the statement into tokens whose texts, joined, give it back unchanged.
+    def self.tokenize(sql, dialect)
+      raise ArgumentError, "unknown SQL dialect: #{dialect.inspect}" unless DIALECTS.include?(dialect)
+
+      s = StringScanner.new(sql.to_s)
+      tokens = []
+      until s.eos?
+        tokens << if s.scan(/\s+/)
+          Token.new(:space, s.matched)
+        elsif s.scan(dialect == :mysql ? /(?:--(?=\s|\z)|#)[^\n]*/ : /--[^\n]*/)
+          Token.new(:comment, s.matched)
+        elsif s.check(%r{/\*})
+          Token.new(:comment, scan_block_comment(s, nested: dialect == :postgresql))
+        elsif s.scan(dialect == :mysql ? BACKSLASH_LITERAL : PLAIN_LITERAL) ||
+              (dialect == :postgresql && s.scan(ESCAPE_LITERAL))
+          Token.new(:literal, s.matched)
+        elsif s.scan(/"(?:[^"]|"")*"?/m) || (dialect != :postgresql && s.scan(/`(?:[^`]|``)*`?/m))
+          Token.new(:identifier, s.matched)
+        elsif dialect == :postgresql && s.scan(/\$\d+/)
+          Token.new(:numbered, s.matched)
+        elsif dialect == :postgresql && s.scan(/\$([A-Za-z_][A-Za-z0-9_]*)?\$/)
+          tag = s.matched
+          body = s.scan_until(/#{Regexp.escape(tag)}/) || s.rest.tap { s.terminate }
+          Token.new(:literal, tag + body)
+        elsif dialect != :postgresql && s.scan(/\?/)
+          Token.new(:question, s.matched)
+        elsif s.scan(/[A-Za-z_][A-Za-z0-9_$]*/)
+          Token.new(:word, s.matched)
+        else
+          Token.new(:punct, s.getch)
+        end
+      end
+      tokens
+    end
+
+    # An unterminated block comment runs to the end.
+    def self.scan_block_comment(s, nested:)
+      text = +""
+      depth = 0
+      until s.eos?
+        if s.scan(%r{/\*})
+          depth += 1 if nested || depth.zero?
+        elsif s.scan(%r{\*/})
+          depth -= 1
+        else
+          s.getch
+        end
+        text << s.matched
+        break if depth.zero?
+      end
+      text
+    end
+
+    private_class_method :refusal, :tokenize, :scan_block_comment
+  end
+end

data/lib/profiler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Profiler
-  VERSION = "0.30.7"
+  VERSION = "0.30.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-profiler
 version: !ruby/object:Gem::Version
-  version: 0.30.7
+  version: 0.30.9
 platform: ruby
 authors:
 - Sébastien Duplessy
@@ -210,6 +210,7 @@ files:
 - lib/profiler/models/timeline_event.rb
 - lib/profiler/railtie.rb
 - lib/profiler/redaction.rb
+- lib/profiler/sql_statement.rb
 - lib/profiler/sse/bus.rb
 - lib/profiler/sse/event_bus.rb
 - lib/profiler/sse/redis_event_bus.rb