rails_db_inspector 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 563499f106cd48b6fb921b627408e92cf17388416ab8980485e18e4060c2c1e6
-  data.tar.gz: 357910264b9a52d1e9c944e5ff53c8be679ec20ebc7bb4cebf5109866396d48b
+  metadata.gz: '08c6511ec0aa29b649a9939c4bf17ea042346cc99a5bdb645382764621589da6'
+  data.tar.gz: 9a171cdcd171cfd8a64488bb2b5f570175d9e26979866743c5f8571c3fd1ed5f
 SHA512:
-  metadata.gz: accc48fc04b30608198e8b02238a6bdc49de9b75936b60521a5002edfeef2c3bd98b9beb8e6afc63b2f9e9815838bde4dc4055f0addf27c814855c9178d30298
-  data.tar.gz: 25e5c3919cbbdf126c4f4ff6186b7abe10fb97fb8ade2a28c589de7249a2d7edc1370848ab9c29316906a69e7ade51827b03c6b0a20a595f43b0ddf8f362aa07
+  metadata.gz: 3a1df1506a50af86702c516e9994b54a1ec488c3dfa23115c27836c6699a3eae10f961239bc361da14771d26a995ef3c80864d0e11cdd7629e381a71d4d73db7
+  data.tar.gz: bc17122e5f23aadfb6edd76911f3d26b6fac1d88c13b8ac048f3134525a22ae5add60d188702055297f848cf18d7fffd1de2e8e4fd74c9f63eccea184ebbfcfb

data/README.md

@@ -22,6 +22,7 @@ Supports **PostgreSQL**, **MySQL**, and **SQLite**.
 - **EXPLAIN ANALYZE** — optionally run `EXPLAIN ANALYZE` to get real execution statistics, buffer usage, and timing (opt-in, SELECT only)
 - **Plan Analysis** — rich visual rendering of PostgreSQL plans including cost breakdown, row estimate accuracy, index usage analysis, performance hotspots, buffer statistics, and actionable recommendations
 - **Interactive Schema / ERD Visualization** — drag-and-drop entity relationship diagram with pan, zoom, search, column expansion, heat-map by row count, missing index warnings, polymorphic detection, and SVG export
+- **SQL Console** — interactive query editor with syntax-aware snippets, query history, table browser, EXPLAIN support, and read-only safety by default
 - **Dev Widget** — floating button injected into your app's pages in development for quick access to the dashboard
 - **Zero Dependencies** — no JavaScript build step, no external CSS frameworks, everything is self-contained
 
@@ -84,6 +85,11 @@ RailsDbInspector.configure do |config|
   # Default: false
   config.allow_explain_analyze = true
 
+  # Allow write queries (INSERT, UPDATE, DELETE) in the SQL Console.
+  # Destructive DDL (DROP, TRUNCATE, ALTER, CREATE, GRANT, REVOKE) is always blocked.
+  # Default: false
+  config.allow_console_writes = false
+
   # Show the floating dev widget on your app's pages in development.
   # The widget provides quick links to the query monitor and schema viewer.
   # Default: true
@@ -98,6 +104,7 @@ end
 | `enabled`               | Boolean | `true`   | Master switch — disables SQL subscription and widget when `false`           |
 | `max_queries`           | Integer | `2000`   | Max queries stored in memory (FIFO eviction)                                |
 | `allow_explain_analyze` | Boolean | `false`  | Permit EXPLAIN ANALYZE (executes the query — SELECT only)                   |
+| `allow_console_writes`  | Boolean | `false`  | Allow write queries (`INSERT`, `UPDATE`, `DELETE`) in the SQL Console       |
 | `show_widget`           | Boolean | `true`   | Inject floating widget into HTML pages in development                       |
 
 ---
@@ -168,6 +175,27 @@ Navigate to the **Schema** page to see an interactive entity relationship diagra
 - **Health summary** — table count, column count, index count, total rows, missing indexes, tables without timestamps, tables without primary keys, polymorphic columns
 - **Export SVG** — download the diagram as an SVG file
 
+### SQL Console
+
+Navigate to the **Console** page for an interactive SQL editor:
+
+- **Write and run** raw SQL queries against your development database
+- **Adapter-aware snippets** — pre-built queries organized by category (Overview, Explore, Performance, Schema) that adapt to your database adapter
+- **Table browser** — click any table in the sidebar to insert a `SELECT * FROM <table> LIMIT 20` query
+- **Query history** — the last 50 queries are kept in-session with duration and status
+- **EXPLAIN** — run an EXPLAIN plan on any query directly from the editor
+- **Keyboard shortcuts** — `⌘/Ctrl + Enter` to run, `⌘/Ctrl + E` to explain
+
+#### Safety
+
+The console is **read-only by default** — only `SELECT`, `EXPLAIN`, `ANALYZE`, `PRAGMA`, `SHOW`, `DESCRIBE`, and `WITH` statements are permitted. Enable write access with:
+
+```ruby
+config.allow_console_writes = true
+```
+
+Destructive DDL (`DROP`, `TRUNCATE`, `ALTER`, `CREATE`, `GRANT`, `REVOKE`) is **always blocked** regardless of settings.
+
 ### Dev Widget
 
 In development, a floating blue button (🛢️) appears in the bottom-right corner of every page. Click it to reveal quick links to:
@@ -197,7 +225,8 @@ EXPLAIN uses `FORMAT JSON` for PostgreSQL, standard `EXPLAIN` for MySQL, and `EX
 2. **Query Store** — an in-memory singleton (`QueryStore`) stores captured queries with thread-safe access. Oldest queries are evicted when `max_queries` is exceeded.
 3. **Explain** — wraps the captured SQL in an `EXPLAIN` statement appropriate for the database adapter and parses the result.
 4. **Schema Inspector** — introspects `ActiveRecord::Base.connection` for tables, columns, indexes, foreign keys, primary keys, row counts, associations, polymorphic columns, and missing indexes.
-5. **Dev Widget Middleware** — a Rack middleware that injects a small HTML snippet before `</body>` on HTML responses in development.
+5. **SQL Console** — runs user-provided SQL through `ActiveRecord::Base.connection.exec_query` with statement-level allow/deny lists to enforce read-only safety.
+6. **Dev Widget Middleware** — a Rack middleware that injects a small HTML snippet before `</body>` on HTML responses in development.
 
 ---
 

data/app/controllers/rails_db_inspector/console_controller.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RailsDbInspector
+  class ConsoleController < ApplicationController
+    DANGEROUS_KEYWORDS = /\b(DROP|TRUNCATE|ALTER|CREATE|GRANT|REVOKE)\b/i
+
+    def index
+      connection = ActiveRecord::Base.connection
+      @tables = connection.tables.reject { |t| t.match?(/^(schema_migrations|ar_internal_metadata)$/) }.sort
+      @adapter = connection.adapter_name.downcase
+      @allow_writes = RailsDbInspector.configuration.allow_console_writes
+    end
+
+    def execute
+      sql = params[:sql].to_s.strip
+      return render json: { error: "SQL query is required" }, status: :bad_request if sql.blank?
+
+      # Block destructive DDL regardless of config
+      if sql.match?(DANGEROUS_KEYWORDS)
+        return render json: { error: "Destructive DDL statements (DROP, TRUNCATE, ALTER, CREATE, GRANT, REVOKE) are not allowed." }, status: :forbidden
+      end
+
+      # Block writes unless explicitly enabled
+      unless RailsDbInspector.configuration.allow_console_writes
+        unless sql.match?(/\A\s*(SELECT|EXPLAIN|ANALYZE|PRAGMA|SHOW|DESCRIBE|DESC|\\.d|WITH)\b/i)
+          return render json: { error: "Write queries are disabled. Enable with: RailsDbInspector.configuration.allow_console_writes = true" }, status: :forbidden
+        end
+      end
+
+      connection = ActiveRecord::Base.connection
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      begin
+        result = connection.exec_query(sql)
+        elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round(2)
+
+        render json: {
+          columns: result.columns,
+          rows: result.rows,
+          row_count: result.rows.length,
+          duration_ms: elapsed
+        }
+      rescue StandardError => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      end
+    end
+  end
+end

data/app/controllers/rails_db_inspector/queries_controller.rb

@@ -28,6 +28,7 @@ module RailsDbInspector
 
       explainer = RailsDbInspector::Explain.for_connection(ActiveRecord::Base.connection)
       @explain = explainer.explain(@query.sql, analyze: analyze)
+      @tables = ActiveRecord::Base.connection.tables.reject { |t| t.match?(/^(schema_migrations|ar_internal_metadata)$/) }.sort
     rescue RailsDbInspector::Explain::DangerousQuery => e
       render plain: e.message, status: :unprocessable_entity
     rescue RailsDbInspector::Explain::UnsupportedAdapter => e

data/app/controllers/rails_db_inspector/schema_controller.rb

@@ -8,6 +8,32 @@ module RailsDbInspector
       inspector = RailsDbInspector::SchemaInspector.new
       @schema = inspector.introspect
       @relationships = inspector.relationships
+      @table_sizes = inspector.table_sizes
+    end
+
+    def analyze_table
+      table = params[:table].to_s.gsub(/[^a-zA-Z0-9_]/, "")
+      return render json: { error: "Table name required" }, status: :bad_request if table.blank?
+
+      connection = ActiveRecord::Base.connection
+      adapter = connection.adapter_name.downcase
+
+      begin
+        case adapter
+        when /postgres/
+          connection.execute("ANALYZE #{connection.quote_table_name(table)}")
+        when /mysql/
+          connection.execute("ANALYZE TABLE #{connection.quote_table_name(table)}")
+        when /sqlite/
+          connection.execute("ANALYZE #{connection.quote_table_name(table)}")
+        else
+          return render json: { error: "ANALYZE not supported for #{adapter}" }, status: :unprocessable_entity
+        end
+
+        render json: { success: true, table: table, adapter: adapter, message: "Statistics refreshed for '#{table}'" }
+      rescue StandardError => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      end
     end
   end
 end

data/app/helpers/rails_db_inspector/plan_renderer.rb

@@ -26,9 +26,12 @@ module RailsDbInspector
         buffer_stats = collect_buffer_stats(root_plan["Plan"]) if @analyze
         recommendations = generate_recommendations(root_plan, index_analysis, buffer_stats)
 
-        summary_html = <<~HTML
+        # Build verdict card
+        summary_html = render_verdict(execution_time, total_cost, index_analysis, recommendations)
+
+        summary_html += <<~HTML
           <div class="bg-gray-50 border border-gray-200 rounded-lg p-6 mb-6">
-            <h3 class="text-lg font-semibold text-gray-900 mb-4">Execution Summary</h3>
+            <h3 class="text-lg font-semibold text-gray-900 mb-4">Performance Metrics</h3>
             <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-4">
         HTML
 
@@ -81,6 +84,22 @@ module RailsDbInspector
           </div>
         HTML
 
+        # Add cardinality accuracy card (ANALYZE only)
+        if @analyze
+          accuracy = cardinality_accuracy(root_plan["Plan"])
+          if accuracy
+            accuracy_color = accuracy[:worst_ratio] <= 2.0 ? "border-green-400" : (accuracy[:worst_ratio] <= 10.0 ? "border-yellow-400" : "border-red-400")
+            accuracy_label = accuracy[:worst_ratio] <= 2.0 ? "Good" : (accuracy[:worst_ratio] <= 10.0 ? "Fair" : "Poor")
+            summary_html += <<~HTML
+              <div class="bg-white p-4 rounded-md border-l-4 #{accuracy_color}">
+                <div class="text-xs font-medium text-gray-500 uppercase tracking-wide">Cardinality Accuracy</div>
+                <div class="text-lg font-semibold text-gray-900 font-mono">#{accuracy_label}</div>
+                <div class="text-xs text-gray-400 mt-1">Worst estimate was #{accuracy[:worst_ratio]}x off#{accuracy[:worst_table] ? " on #{accuracy[:worst_table]}" : ""}. Run ANALYZE on tables with poor estimates.</div>
+              </div>
+            HTML
+          end
+        end
+
         # Add cache hit ratio if we have buffer stats
         if buffer_stats && buffer_stats[:total_blocks] > 0
           hit_ratio = ((buffer_stats[:hit_blocks].to_f / buffer_stats[:total_blocks]) * 100).round(1)
@@ -234,6 +253,70 @@ module RailsDbInspector
 
       private
 
+      def render_verdict(execution_time, total_cost, index_analysis, recommendations)
+        critical_count = recommendations.count { |r| r[:severity] == :critical }
+        warning_count = recommendations.count { |r| r[:severity] == :warning }
+        all_indexed = index_analysis[:total_scans] > 0 && index_analysis[:index_scans] == index_analysis[:total_scans]
+
+        if @analyze && execution_time
+          if execution_time > 1000 || critical_count > 0
+            verdict = :bad
+            icon = "🔴"
+            title = "This query needs attention"
+            desc = []
+            desc << "Took #{execution_time}ms to execute" if execution_time > 1000
+            desc << "#{critical_count} critical issue#{"s" if critical_count != 1}" if critical_count > 0
+            desc << "No indexes used" unless all_indexed || index_analysis[:total_scans] == 0
+            description = desc.join(" · ") + ". See the recommendations below for specific fixes."
+          elsif execution_time > 100 || warning_count > 0
+            verdict = :ok
+            icon = "🟡"
+            title = "Room for improvement"
+            desc = []
+            desc << "#{execution_time}ms execution time (aim for <50ms in web requests)" if execution_time > 100
+            desc << "#{warning_count} suggestion#{"s" if warning_count != 1}" if warning_count > 0
+            description = desc.join(" · ") + ". Review the recommendations below."
+          else
+            verdict = :good
+            icon = "🟢"
+            title = "This query looks good"
+            description = "Executed in #{execution_time}ms"
+            description += ", all scans use indexes" if all_indexed && index_analysis[:total_scans] > 0
+            description += ". No critical issues found."
+          end
+        else
+          # EXPLAIN without ANALYZE — evaluate based on cost and plan shape
+          if critical_count > 0
+            verdict = :bad
+            icon = "🔴"
+            title = "Potential problems detected"
+            description = "#{critical_count + warning_count} issue#{"s" if critical_count + warning_count != 1} found in the estimated plan. Run with ANALYZE to confirm with real metrics."
+          elsif warning_count > 0 || !all_indexed
+            verdict = :ok
+            icon = "🟡"
+            title = "Some concerns in the estimated plan"
+            description = "The planner's strategy has #{warning_count} suggestion#{"s" if warning_count != 1}. Run with ANALYZE to see actual performance."
+          else
+            verdict = :good
+            icon = "🟢"
+            title = "Estimated plan looks efficient"
+            description = "The planner chose index-based access"
+            description += " with an estimated cost of #{total_cost}" if total_cost
+            description += ". Run with ANALYZE to verify with real numbers."
+          end
+        end
+
+        <<~HTML
+          <div class="verdict-card verdict-#{verdict}" style="margin-bottom: 24px;">
+            <span class="verdict-icon">#{icon}</span>
+            <div class="verdict-body">
+              <h3>#{ERB::Util.html_escape(title)}</h3>
+              <p>#{ERB::Util.html_escape(description)}</p>
+            </div>
+          </div>
+        HTML
+      end
+
       def render_node(node, depth)
         node_id = "node_#{SecureRandom.hex(6)}"
         warnings = detect_warnings(node)
@@ -371,7 +454,30 @@ module RailsDbInspector
           details << [ "Cost", "#{node["Startup Cost"]}..#{node["Total Cost"]}", "Startup cost (before first row) to total cost (all rows). Arbitrary units — compare relative to other nodes." ]
         end
 
+        # Cardinality metrics — estimated rows and row width
+        if node["Plan Rows"]
+          details << [ "Estimated Rows (Cardinality)", number_with_delimiter(node["Plan Rows"]), "The planner's estimate of how many rows this node will produce. This is the estimated cardinality — a key factor in plan selection." ]
+        end
+
+        if node["Plan Width"]
+          details << [ "Estimated Row Width", "#{node["Plan Width"]} bytes", "Average width of each output row in bytes. Combined with cardinality (row count), this determines memory and I/O cost estimates." ]
+        end
+
         if @analyze
+          if node["Actual Rows"]
+            details << [ "Actual Rows", number_with_delimiter(node["Actual Rows"]), "The real number of rows returned by this node. Compare with Estimated Rows to judge planner accuracy." ]
+          end
+
+          if node["Actual Rows"] && node["Plan Rows"] && node["Plan Rows"] > 0
+            ratio = (node["Actual Rows"].to_f / node["Plan Rows"]).round(2)
+            accuracy = if ratio == 1.0 then "exact match"
+            elsif ratio > 0.5 && ratio < 2.0 then "good (within 2x)"
+            elsif ratio > 0.1 && ratio < 10 then "off (#{ratio}x)"
+            else "poor (#{ratio}x) — consider ANALYZE on this table"
+            end
+            details << [ "Estimate Accuracy", accuracy, "How close the planner's cardinality estimate was to reality. If poor, run ANALYZE to update table statistics." ]
+          end
+
           if node["Actual Startup Time"] && node["Actual Total Time"]
             details << [ "Actual Time", "#{node["Actual Startup Time"]}..#{node["Actual Total Time"]} ms", "Real time: from start until all rows returned for this node." ]
           end
@@ -520,6 +626,26 @@ module RailsDbInspector
         node["Plans"] && node["Plans"].any?
       end
 
+      def cardinality_accuracy(plan_node, result = nil)
+        result ||= { worst_ratio: 1.0, worst_table: nil }
+
+        if plan_node["Actual Rows"] && plan_node["Plan Rows"] && plan_node["Plan Rows"] > 0
+          ratio = plan_node["Actual Rows"].to_f / plan_node["Plan Rows"]
+          ratio = 1.0 / ratio if ratio > 0 && ratio < 1.0  # normalize so ratio >= 1
+          ratio = ratio.round(1)
+          if ratio > result[:worst_ratio]
+            result[:worst_ratio] = ratio
+            result[:worst_table] = plan_node["Relation Name"]
+          end
+        end
+
+        if plan_node["Plans"]
+          plan_node["Plans"].each { |child| cardinality_accuracy(child, result) }
+        end
+
+        result[:worst_ratio] > 1.0 ? result : nil
+      end
+
       def find_hotspots(plan_node, hotspots = [])
         return hotspots unless @analyze
 

data/app/views/layouts/rails_db_inspector/application.html.erb

@@ -35,6 +35,7 @@
             <nav class="flex items-center space-x-3 ml-6">
               <%= link_to "Queries", queries_path, class: "text-sm font-medium #{'text-blue-600' if controller_name == 'queries'} #{'text-gray-500 hover:text-gray-700' unless controller_name == 'queries'} transition-colors" %>
               <%= link_to "Schema", schema_index_path, class: "text-sm font-medium #{'text-blue-600' if controller_name == 'schema'} #{'text-gray-500 hover:text-gray-700' unless controller_name == 'schema'} transition-colors" %>
+              <%= link_to "Console", console_index_path, class: "text-sm font-medium #{'text-blue-600' if controller_name == 'console'} #{'text-gray-500 hover:text-gray-700' unless controller_name == 'console'} transition-colors" %>
             </nav>
           </div>
           <div class="flex items-center space-x-4">