query_console 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f57530c0dcf15456265758600392d0eeff17ba08cfff9f879d0afa31a1ab7e3
-  data.tar.gz: 12952c2bac1d22594a51e06d7c44e892b8e9955381091c22eb696ce08f7a8668
+  metadata.gz: 8c73054ef91ed2d89682d757f0ec545db4f43273b32df46b9a1f57b8f72d92a2
+  data.tar.gz: 753f12bc25e012af3233b96d0c7326f7df307219aea79740f232d9e7dda41def
 SHA512:
-  metadata.gz: c2c2c54e0c044763180321438121c11b66a5cabd8ebc6a1afe53eea8f58b22675424647b3c5b2bde568aeac62e4de5bfa2dcc2f1f32606f5a1a50eeb3960519f
-  data.tar.gz: 28d136f7b2c95ae7aeb551c07bf38bc8a861ff434885a75cbf805773935d4b3df8df57f2a165f9aca7e5ee23169822e635cd23b884d998626a1a7d654c012b57
+  metadata.gz: 0a0eff39813e9f070ef5df3b2965b0d6c39c4bb34c958efb2511bfec614c40fed59d76406b9b119b78a8f9e9e41914810aab439f2f9ea4555843f785ac787cdf
+  data.tar.gz: d3ef86f6fd078fa1844b38212acf27def791c8031886c9132f6b476b06db344687d37b1c97930cd514f487dd25b048263f04927c9f19c71e1e4c5013253f9840

data/README.md

@@ -4,6 +4,7 @@ A Rails engine that provides a secure, mountable web interface for running read-
 
 ## Features
 
+### Core Features (v0.1.0)
 - 🔒 **Security First**: Read-only queries enforced at multiple levels
 - 🚦 **Environment Gating**: Disabled by default in production
 - 🔑 **Flexible Authorization**: Integrate with your existing auth system
@@ -14,6 +15,13 @@ A Rails engine that provides a secure, mountable web interface for running read-
 - ⚡ **Hotwire-Powered**: Uses Turbo Frames and Stimulus for smooth, SPA-like experience
 - 🎨 **Zero Build Step**: CDN-hosted Hotwire, no asset compilation needed
 
+### New in v0.2.0 🚀
+- 📊 **EXPLAIN Query Plans**: Analyze query execution plans for performance debugging
+- 🗂️ **Schema Explorer**: Browse tables, columns, types with quick actions
+- 💾 **Saved Queries**: Save, organize, import/export your important queries (client-side)
+- 🎨 **Tabbed UI**: Switch between History and Schema views seamlessly
+- 🔍 **Quick Actions**: Generate queries from schema, copy names, insert WHERE clauses
+
 ## Security Features
 
 QueryConsole implements multiple layers of security:
@@ -70,6 +78,17 @@ QueryConsole.configure do |config|
   # Optional: Adjust limits
   # config.max_rows = 1000
   # config.timeout_ms = 5000
+  
+  # v0.2.0+ Features
+  # EXPLAIN feature (default: enabled)
+  # config.enable_explain = true
+  # config.enable_explain_analyze = false  # Disabled by default for safety
+  
+  # Schema Explorer (default: enabled)
+  # config.schema_explorer = true
+  # config.schema_cache_seconds = 60
+  # config.schema_table_denylist = ["schema_migrations", "ar_internal_metadata"]
+  # config.schema_allowlist = []  # Optional: whitelist specific tables
 end
 ```
 

data/app/controllers/query_console/application_controller.rb

@@ -15,7 +15,8 @@ module QueryConsole
       config = QueryConsole.configuration
       
       unless config.enabled_environments.map(&:to_s).include?(Rails.env.to_s)
-        raise ActionController::RoutingError, "Not Found"
+        render plain: "Not Found", status: :not_found
+        return false
       end
     end
 
@@ -25,13 +26,15 @@ module QueryConsole
       # Default deny if no authorize hook is configured
       if config.authorize.nil?
         Rails.logger.warn("[QueryConsole] Access denied: No authorization hook configured")
-        raise ActionController::RoutingError, "Not Found"
+        render plain: "Not Found", status: :not_found
+        return false
       end
 
       # Call the authorization hook
       unless config.authorize.call(self)
         Rails.logger.warn("[QueryConsole] Access denied by authorization hook")
-        raise ActionController::RoutingError, "Not Found"
+        render plain: "Not Found", status: :not_found
+        return false
       end
     end
   end

data/app/controllers/query_console/explain_controller.rb

@@ -0,0 +1,47 @@
+module QueryConsole
+  class ExplainController < ApplicationController
+    skip_forgery_protection only: [:create] # Allow Turbo Frame POST requests
+
+    def create
+      sql = params[:sql]
+
+      if sql.blank?
+        @result = ExplainRunner::ExplainResult.new(error: "Query cannot be empty")
+        respond_to do |format|
+          format.turbo_stream do
+            render turbo_stream: turbo_stream.replace(
+              "explain-results",
+              partial: "explain/results",
+              locals: { result: @result }
+            )
+          end
+          format.html { render "explain/_results", layout: false, locals: { result: @result } }
+        end
+        return
+      end
+
+      # Execute the EXPLAIN
+      runner = ExplainRunner.new(sql)
+      @result = runner.execute
+
+      # Log the EXPLAIN execution
+      AuditLogger.log_query(
+        sql: "EXPLAIN: #{sql}",
+        result: @result,
+        controller: self
+      )
+
+      # Respond with Turbo Stream or HTML
+      respond_to do |format|
+        format.turbo_stream do
+          render turbo_stream: turbo_stream.replace(
+            "explain-results",
+            partial: "query_console/explain/results",
+            locals: { result: @result }
+          )
+        end
+        format.html { render "query_console/explain/_results", layout: false, locals: { result: @result } }
+      end
+    end
+  end
+end

data/app/controllers/query_console/queries_controller.rb

@@ -1,5 +1,7 @@
 module QueryConsole
   class QueriesController < ApplicationController
+    skip_forgery_protection only: [:run] # Allow Turbo Frame POST requests
+    
     def new
       # Render the main query editor page
     end

data/app/controllers/query_console/schema_controller.rb

@@ -0,0 +1,32 @@
+module QueryConsole
+  class SchemaController < ApplicationController
+    def tables
+      unless QueryConsole.configuration.schema_explorer
+        render json: { error: "Schema explorer is disabled" }, status: :forbidden
+        return
+      end
+
+      introspector = SchemaIntrospector.new
+      @tables = introspector.tables
+
+      render json: @tables
+    end
+
+    def show
+      unless QueryConsole.configuration.schema_explorer
+        render json: { error: "Schema explorer is disabled" }, status: :forbidden
+        return
+      end
+
+      introspector = SchemaIntrospector.new
+      @table = introspector.table_details(params[:name])
+
+      if @table.nil?
+        render json: { error: "Table not found or access denied" }, status: :not_found
+        return
+      end
+
+      render json: @table
+    end
+  end
+end

data/app/services/query_console/audit_logger.rb

@@ -15,16 +15,20 @@ module QueryConsole
         actor: resolved_actor,
         sql: sql.to_s.strip,
         duration_ms: result.execution_time_ms,
-        rows: result.row_count_shown,
         status: result.success? ? "ok" : "error"
       }
 
+      # Add row count if available (for QueryResult)
+      if result.respond_to?(:row_count_shown)
+        log_data[:rows] = result.row_count_shown
+      end
+
       if result.failure?
         log_data[:error] = result.error
         log_data[:error_class] = determine_error_class(result.error)
       end
 
-      if result.truncated?
+      if result.respond_to?(:truncated) && result.truncated
         log_data[:truncated] = true
         log_data[:max_rows] = config.max_rows
       end

data/app/services/query_console/explain_runner.rb

@@ -0,0 +1,137 @@
+require 'timeout'
+
+module QueryConsole
+  class ExplainRunner
+    class ExplainResult
+      attr_reader :plan_text, :execution_time_ms, :error
+
+      def initialize(plan_text: nil, execution_time_ms: 0, error: nil)
+        @plan_text = plan_text
+        @execution_time_ms = execution_time_ms
+        @error = error
+      end
+
+      def success?
+        @error.nil?
+      end
+
+      def failure?
+        !success?
+      end
+    end
+
+    def initialize(sql, config = QueryConsole.configuration)
+      @sql = sql
+      @config = config
+    end
+
+    def execute
+      return ExplainResult.new(error: "EXPLAIN feature is disabled") unless @config.enable_explain
+
+      start_time = Time.now
+
+      # Step 1: Validate SQL (same as regular runner)
+      validator = SqlValidator.new(@sql, @config)
+      validation_result = validator.validate
+
+      if validation_result.invalid?
+        return ExplainResult.new(error: validation_result.error)
+      end
+
+      sanitized_sql = validation_result.sanitized_sql
+
+      # Step 2: Build EXPLAIN query based on adapter
+      explain_sql = build_explain_query(sanitized_sql)
+
+      # Step 3: Execute with timeout
+      begin
+        result = execute_with_timeout(explain_sql)
+        execution_time = ((Time.now - start_time) * 1000).round(2)
+
+        # Format the result as plain text
+        plan_text = format_explain_output(result)
+
+        ExplainResult.new(
+          plan_text: plan_text,
+          execution_time_ms: execution_time
+        )
+      rescue Timeout::Error
+        ExplainResult.new(
+          error: "EXPLAIN timeout: exceeded #{@config.timeout_ms}ms limit"
+        )
+      rescue StandardError => e
+        ExplainResult.new(
+          error: "EXPLAIN error: #{e.message}"
+        )
+      end
+    end
+
+    private
+
+    attr_reader :sql, :config
+
+    def build_explain_query(sql)
+      adapter_name = ActiveRecord::Base.connection.adapter_name
+
+      case adapter_name
+      when "PostgreSQL"
+        if @config.enable_explain_analyze
+          "EXPLAIN (ANALYZE, FORMAT TEXT) #{sql}"
+        else
+          "EXPLAIN (FORMAT TEXT) #{sql}"
+        end
+      when "Mysql2", "Trilogy"
+        if @config.enable_explain_analyze
+          "EXPLAIN ANALYZE #{sql}"
+        else
+          "EXPLAIN #{sql}"
+        end
+      when "SQLite"
+        # SQLite doesn't support ANALYZE in EXPLAIN
+        "EXPLAIN QUERY PLAN #{sql}"
+      else
+        # Fallback for other adapters
+        "EXPLAIN #{sql}"
+      end
+    end
+
+    def execute_with_timeout(sql)
+      timeout_seconds = @config.timeout_ms / 1000.0
+      
+      Timeout.timeout(timeout_seconds) do
+        ActiveRecord::Base.connection.exec_query(sql)
+      end
+    end
+
+    def format_explain_output(result)
+      # For SQLite, the result has columns like: id, parent, notused, detail
+      # For Postgres, it's usually a single "QUERY PLAN" column
+      # For MySQL, it varies by version
+
+      adapter_name = ActiveRecord::Base.connection.adapter_name
+
+      case adapter_name
+      when "SQLite"
+        # SQLite EXPLAIN QUERY PLAN format
+        lines = result.rows.map do |row|
+          # row is [id, parent, notused, detail]
+          detail = row[3] || row.last
+          detail.to_s
+        end
+        lines.join("\n")
+      when "PostgreSQL"
+        # Postgres returns single column with plan text
+        result.rows.map { |row| row[0].to_s }.join("\n")
+      when "Mysql2", "Trilogy"
+        # MySQL returns multiple columns, format as table
+        header = result.columns.join(" | ")
+        separator = "-" * header.length
+        rows = result.rows.map { |row| row.map(&:to_s).join(" | ") }
+        ([header, separator] + rows).join("\n")
+      else
+        # Generic fallback
+        result.rows.map { |row| row.join(" | ") }.join("\n")
+      end
+    end
+  end
+end

data/app/services/query_console/schema_introspector.rb

@@ -0,0 +1,244 @@
+module QueryConsole
+  class SchemaIntrospector
+    def initialize(config = QueryConsole.configuration)
+      @config = config
+    end
+
+    def tables
+      return [] unless @config.schema_explorer
+
+      Rails.cache.fetch(cache_key_tables, expires_in: @config.schema_cache_seconds) do
+        fetch_tables
+      end
+    end
+
+    def table_details(table_name)
+      return nil unless @config.schema_explorer
+      return nil if table_denied?(table_name)
+
+      Rails.cache.fetch(cache_key_table(table_name), expires_in: @config.schema_cache_seconds) do
+        fetch_table_details(table_name)
+      end
+    end
+
+    private
+
+    attr_reader :config
+
+    def fetch_tables
+      adapter_name = ActiveRecord::Base.connection.adapter_name
+      
+      raw_tables = case adapter_name
+      when "PostgreSQL"
+        fetch_postgresql_tables
+      when "Mysql2", "Trilogy"
+        fetch_mysql_tables
+      when "SQLite"
+        fetch_sqlite_tables
+      else
+        # Fallback for other adapters
+        ActiveRecord::Base.connection.tables.map { |name| { name: name, kind: "table" } }
+      end
+
+      # Apply filtering
+      filter_tables(raw_tables)
+    end
+
+    def fetch_postgresql_tables
+      sql = <<~SQL
+        SELECT 
+          table_name as name,
+          table_type as kind
+        FROM information_schema.tables
+        WHERE table_schema = 'public'
+        ORDER BY table_name
+      SQL
+
+      result = ActiveRecord::Base.connection.exec_query(sql)
+      result.rows.map do |row|
+        {
+          name: row[0],
+          kind: row[1].downcase.include?("view") ? "view" : "table"
+        }
+      end
+    end
+
+    def fetch_mysql_tables
+      sql = <<~SQL
+        SELECT 
+          table_name as name,
+          table_type as kind
+        FROM information_schema.tables
+        WHERE table_schema = DATABASE()
+        ORDER BY table_name
+      SQL
+
+      result = ActiveRecord::Base.connection.exec_query(sql)
+      result.rows.map do |row|
+        {
+          name: row[0],
+          kind: row[1].downcase.include?("view") ? "view" : "table"
+        }
+      end
+    end
+
+    def fetch_sqlite_tables
+      sql = <<~SQL
+        SELECT name, type
+        FROM sqlite_master
+        WHERE type IN ('table', 'view')
+        AND name NOT LIKE 'sqlite_%'
+        ORDER BY name
+      SQL
+
+      result = ActiveRecord::Base.connection.exec_query(sql)
+      result.rows.map do |row|
+        {
+          name: row[0],
+          kind: row[1]
+        }
+      end
+    end
+
+    def fetch_table_details(table_name)
+      adapter_name = ActiveRecord::Base.connection.adapter_name
+      
+      columns = case adapter_name
+      when "PostgreSQL"
+        fetch_postgresql_columns(table_name)
+      when "Mysql2", "Trilogy"
+        fetch_mysql_columns(table_name)
+      when "SQLite"
+        fetch_sqlite_columns(table_name)
+      else
+        # Fallback using ActiveRecord
+        fetch_activerecord_columns(table_name)
+      end
+
+      {
+        name: table_name,
+        columns: columns
+      }
+    end
+
+    def fetch_postgresql_columns(table_name)
+      sql = <<~SQL
+        SELECT 
+          column_name,
+          data_type,
+          is_nullable,
+          column_default
+        FROM information_schema.columns
+        WHERE table_schema = 'public'
+        AND table_name = '#{sanitize_table_name(table_name)}'
+        ORDER BY ordinal_position
+      SQL
+
+      result = ActiveRecord::Base.connection.exec_query(sql)
+      result.rows.map do |row|
+        {
+          name: row[0],
+          db_type: row[1],
+          nullable: row[2] == "YES",
+          default: row[3]
+        }
+      end
+    end
+
+    def fetch_mysql_columns(table_name)
+      sql = <<~SQL
+        SELECT 
+          column_name,
+          data_type,
+          is_nullable,
+          column_default
+        FROM information_schema.columns
+        WHERE table_schema = DATABASE()
+        AND table_name = '#{sanitize_table_name(table_name)}'
+        ORDER BY ordinal_position
+      SQL
+
+      result = ActiveRecord::Base.connection.exec_query(sql)
+      result.rows.map do |row|
+        {
+          name: row[0],
+          db_type: row[1],
+          nullable: row[2] == "YES",
+          default: row[3]
+        }
+      end
+    end
+
+    def fetch_sqlite_columns(table_name)
+      sql = "PRAGMA table_info(#{sanitize_table_name(table_name)})"
+      result = ActiveRecord::Base.connection.exec_query(sql)
+      
+      result.rows.map do |row|
+        # SQLite PRAGMA returns: cid, name, type, notnull, dflt_value, pk
+        {
+          name: row[1],
+          db_type: row[2],
+          nullable: row[3] == 0,
+          default: row[4]
+        }
+      end
+    end
+
+    def fetch_activerecord_columns(table_name)
+      columns = ActiveRecord::Base.connection.columns(table_name)
+      columns.map do |col|
+        {
+          name: col.name,
+          db_type: col.sql_type,
+          nullable: col.null,
+          default: col.default
+        }
+      end
+    rescue StandardError
+      []
+    end
+
+    def filter_tables(tables)
+      tables.select do |table|
+        # Check denylist
+        next false if @config.schema_table_denylist.include?(table[:name])
+        
+        # Check allowlist (if present)
+        if @config.schema_allowlist.any?
+          next @config.schema_allowlist.include?(table[:name])
+        end
+        
+        true
+      end
+    end
+
+    def table_denied?(table_name)
+      # Check denylist
+      return true if @config.schema_table_denylist.include?(table_name)
+      
+      # Check allowlist (if present)
+      if @config.schema_allowlist.any?
+        return !@config.schema_allowlist.include?(table_name)
+      end
+      
+      false
+    end
+
+    def sanitize_table_name(name)
+      # Basic SQL injection protection - only allow alphanumeric, underscore
+      name.to_s.gsub(/[^a-zA-Z0-9_]/, '')
+    end
+
+    def cache_key_tables
+      "query_console/schema/tables/#{adapter_identifier}"
+    end
+
+    def cache_key_table(table_name)
+      "query_console/schema/table/#{adapter_identifier}/#{table_name}"
+    end
+
+    def adapter_identifier
+      ActiveRecord::Base.connection.adapter_name.downcase
+    end
+  end
+end

data/app/views/query_console/explain/_results.html.erb

@@ -0,0 +1,89 @@
+<style>
+  .explain-container {
+    margin-top: 20px;
+  }
+
+  .explain-header {
+    background: #f8f9fa;
+    padding: 12px 16px;
+    border-radius: 4px 4px 0 0;
+    border: 1px solid #dee2e6;
+    border-bottom: none;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+
+  .explain-header h4 {
+    margin: 0;
+    font-size: 14px;
+    font-weight: 600;
+    color: #495057;
+  }
+
+  .explain-metadata {
+    font-size: 12px;
+    color: #6c757d;
+  }
+
+  .explain-content {
+    background: #fff;
+    border: 1px solid #dee2e6;
+    border-radius: 0 0 4px 4px;
+    padding: 16px;
+    max-height: 400px;
+    overflow: auto;
+  }
+
+  .explain-plan {
+    font-family: 'Courier New', Courier, monospace;
+    font-size: 13px;
+    line-height: 1.6;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+    background: #f8f9fa;
+    padding: 12px;
+    border-radius: 4px;
+    color: #212529;
+  }
+
+  .explain-error {
+    background: #f8d7da;
+    color: #721c24;
+    padding: 12px 16px;
+    border-radius: 4px;
+    border: 1px solid #f5c6cb;
+  }
+
+  .explain-error-icon {
+    font-weight: bold;
+    margin-right: 8px;
+  }
+</style>
+
+<%= turbo_frame_tag "explain-results" do %>
+  <div class="explain-container">
+    <% if result.failure? %>
+      <div class="explain-error">
+        <span class="explain-error-icon">⚠</span>
+        <strong>EXPLAIN Error:</strong> <%= result.error %>
+      </div>
+    <% else %>
+      <div class="explain-header">
+        <h4>Query Execution Plan</h4>
+        <div class="explain-metadata">
+          Execution time: <strong><%= result.execution_time_ms %>ms</strong>
+        </div>
+      </div>
+      <div class="explain-content">
+        <% if result.plan_text.present? %>
+          <div class="explain-plan"><%= result.plan_text %></div>
+        <% else %>
+          <div style="color: #6c757d; text-align: center; padding: 20px;">
+            No execution plan available.
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+<% end %>

data/app/views/query_console/queries/_results.html.erb

@@ -2,6 +2,9 @@
   <style>
     .results-container {
       margin-top: 20px;
+      width: 100%;
+      min-width: 0;
+      overflow: hidden;
     }
 
     .error-message {
@@ -66,7 +69,8 @@
     }
 
     .results-table {
-      width: 100%;
+      width: max-content;
+      min-width: 100%;
       border-collapse: collapse;
       font-size: 14px;
       background: white;