rails-profiler 0.30.8 → 0.30.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7edf1c383b05c79e4013d76c96fa57077b376f3a312c27aa355927ca1bb7e362
-  data.tar.gz: b1b9b6bd25f7f739c14d2afe72309fac7455e8f2c62b5e7d81e206a09b8ba4fa
+  metadata.gz: a3a3ebc22965fd603d63bafecef777474fc488912625ac2950e618566bce8f09
+  data.tar.gz: e82aa1ce06e0f24cfb65b86fe01a942557851735f596edb3172c3fd00d7941f3
 SHA512:
-  metadata.gz: ca0ca79568606603601b5b33aa3ee69fb54d6497e8c8e2087f45cb8d78092ad0264ed8a8794472955e6b5608f743d198de31fcdf63493e40b7f538fd4c4d8298
-  data.tar.gz: fd3f7cb5326209b731f11abbca7e7e0b3b226ce019ea62f32636a137d1d402c26f692dc11754e27d3144bae0814524ea7be282031d8adacfe3bda5a97d3d4cc9
+  metadata.gz: 857313cb42832f5992a26897cbe6cef4d7dd66d6f59b5fccc63c8758db55da54cd6e3587e254e3d1410db561b668782ef8f3fcda73e4535235efba1e9a34c9be
+  data.tar.gz: 1bd504a236e7c548011ceed8dcc1488b21bc89400d824306c2f90d8b1817290768a10264265ee093f78d295f873b72a250a00a96fc5fe04f54f85cd2d63597db

data/CHANGELOG.md

@@ -19,6 +19,34 @@ 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 -->

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/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.8"
+  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.8
+  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