sql_genius 0.9.0

data/lib/sql_genius/core/query_explainer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    # Runs EXPLAIN against a SELECT query via a Core::Connection. Optionally
+    # skips SQL validation (used for explaining captured slow queries from
+    # mysql's own logs where the exact text may include references to
+    # otherwise-blocked tables).
+    #
+    # Rejects obviously-truncated SQL — captured slow queries from the
+    # slow query log are capped at ~2000 characters, so if the last
+    # character doesn't look like a valid terminator we refuse to try.
+    # This avoids confusing EXPLAIN errors from partial statements.
+    #
+    # Reuses Core::QueryRunner::Rejected for validation failures so
+    # callers can rescue one error type for both runners.
+    class QueryExplainer
+      class Truncated < Core::Error; end
+
+      def initialize(connection, config)
+        @connection = connection
+        @config = config
+      end
+
+      def explain(sql, skip_validation: false)
+        unless skip_validation
+          error = SqlValidator.validate(
+            sql,
+            blocked_tables: @config.blocked_tables,
+            connection: @connection,
+          )
+          raise QueryRunner::Rejected, error if error
+        end
+
+        clean_sql = normalize_placeholders(SqlValidator.normalize_identifier_quotes(sql, @connection).gsub(/;\s*\z/, ""))
+
+        unless looks_complete?(clean_sql)
+          raise Truncated, "This query appears to be truncated and cannot be explained."
+        end
+
+        @connection.exec_query("EXPLAIN #{clean_sql}")
+      end
+
+      private
+
+      # Captured digest text from pg_stat_statements has literals replaced with
+      # $1, $2, ... bind placeholders, and MySQL's performance_schema digest
+      # uses ?. Running EXPLAIN directly on that text fails ("there is no
+      # parameter $1" on PG, similar on MySQL). Substituting NULL lets the
+      # planner produce a plan — selectivity won't match the real query but
+      # the shape (join order, indexes used, scan types) is still useful.
+      #
+      # On PostgreSQL we only substitute $N — those don't appear in
+      # hand-written SQL and the substitution is unambiguous. On MySQL we
+      # only substitute ? outside of single-quoted strings to avoid mangling
+      # user-typed literals like `WHERE name = '?'`.
+      def normalize_placeholders(sql)
+        if @connection.server_version.postgresql?
+          sql.gsub(/\$\d+/, "NULL")
+        else
+          replace_unquoted_question_marks(sql)
+        end
+      end
+
+      # Walks the SQL once, tracking whether we're inside a single-quoted
+      # string (with '' as the escape). Replaces ? with NULL only when
+      # outside a string literal.
+      def replace_unquoted_question_marks(sql)
+        out = +""
+        in_string = false
+        i = 0
+        while i < sql.length
+          ch = sql[i]
+          # Doubled single quote inside a string literal is an escaped quote;
+          # consume both chars without toggling in_string.
+          if in_string && ch == "'" && sql[i + 1] == "'"
+            out << "''"
+            i += 2
+            next
+          end
+          if ch == "'"
+            in_string = !in_string
+            out << ch
+          elsif !in_string && ch == "?"
+            out << "NULL"
+          else
+            out << ch
+          end
+          i += 1
+        end
+        out
+      end
+
+      # Heuristic: SQL ends with a value-like token (identifier, number, closing
+      # paren/bracket, or closing quote). A trailing SQL keyword such as WHERE,
+      # AND, OR, ON, JOIN, SET, HAVING, or a comma/operator means the statement
+      # was cut before its next token.
+      TRAILING_KEYWORD_PATTERN = /\b(WHERE|AND|OR|ON|JOIN|INNER|OUTER|LEFT|RIGHT|CROSS|HAVING|SET|BETWEEN|LIKE|IN|NOT|IS|FROM|SELECT|GROUP|ORDER|LIMIT|OFFSET|UNION|EXCEPT|INTERSECT)\s*$/i
+
+      def looks_complete?(sql)
+        # Strip Rails-style query annotation comments (/*action=...*/) before
+        # inspecting the trailing token. Otherwise the `/` at the end of `*/`
+        # would trip the trailing-operator check and false-flag the statement
+        # as truncated.
+        bare = sql.gsub(%r{/\*.*?\*/}m, " ").strip
+        return false if bare.match?(TRAILING_KEYWORD_PATTERN)
+        return false if bare.match?(%r{[,=<>!(+\-*/]\s*$})
+
+        bare.match?(/[\w'"`)\]]\s*$/)
+      end
+    end
+  end
+end

data/lib/sql_genius/core/query_runner/config.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    # Forward declaration so Config can be namespaced under QueryRunner.
+    # The full QueryRunner class is defined in query_runner.rb.
+    class QueryRunner
+      Config = Struct.new(
+        :blocked_tables,
+        :masked_column_patterns,
+        :query_timeout_ms,
+        keyword_init: true,
+      ) do
+        def initialize(*)
+          super
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/query_runner.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "set"
+
+module SqlGenius
+  module Core
+    # Runs SELECT queries against a Core::Connection with SQL validation,
+    # row-limit application, dialect-appropriate timeout hints, and column
+    # masking. Returns a Core::ExecutionResult on success or raises a
+    # specific error class on failure.
+    #
+    # Timeout strategy by vendor:
+    #   MySQL      — wraps SELECT with /*+ MAX_EXECUTION_TIME(ms) */ hint
+    #   MariaDB    — prefixes SQL with SET STATEMENT max_statement_time=s FOR
+    #   PostgreSQL — issues SET statement_timeout = ms before the query and
+    #                resets it to 0 in an ensure block (the server enforces
+    #                the cancel-on-timeout behaviour)
+    #
+    # Does NOT handle audit logging — the caller is responsible for
+    # recording successful queries and errors using whatever logger it owns.
+    class QueryRunner
+      class Rejected < Core::Error; end
+      class Timeout < Core::Error; end
+
+      TIMEOUT_PATTERNS = [
+        "max_statement_time",
+        "max_execution_time",
+        "Query execution was interrupted",
+        "canceling statement due to statement timeout",
+      ].freeze
+
+      def initialize(connection, config)
+        @connection = connection
+        @config = config
+      end
+
+      def run(sql, row_limit:)
+        validation_error = SqlValidator.validate(
+          sql,
+          blocked_tables: @config.blocked_tables,
+          connection: @connection,
+        )
+        raise Rejected, validation_error if validation_error
+
+        normalized = SqlValidator.normalize_identifier_quotes(sql, @connection)
+        limited = SqlValidator.apply_row_limit(normalized, row_limit)
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = with_timeout do
+          @connection.exec_query(apply_timeout_hint(limited))
+        end
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+
+        masked_rows = mask_rows(result)
+
+        ExecutionResult.new(
+          columns: result.columns,
+          rows: masked_rows,
+          execution_time_ms: duration_ms,
+          truncated: masked_rows.length >= row_limit,
+        )
+      end
+
+      private
+
+      def apply_timeout_hint(sql)
+        case vendor
+        when :mariadb
+          timeout_seconds = @config.query_timeout_ms / 1000
+          "SET STATEMENT max_statement_time=#{timeout_seconds} FOR #{sql}"
+        when :postgresql
+          # PostgreSQL timeout is set out-of-band in with_timeout; the
+          # query itself is sent unchanged.
+          sql
+        else
+          sql.sub(/\bSELECT\b/i, "SELECT /*+ MAX_EXECUTION_TIME(#{@config.query_timeout_ms}) */")
+        end
+      end
+
+      def with_timeout
+        if vendor == :postgresql
+          @connection.exec_query("SET statement_timeout = #{@config.query_timeout_ms}")
+          begin
+            yield
+          ensure
+            begin
+              @connection.exec_query("SET statement_timeout = 0")
+            rescue StandardError
+              # If the session is already torn down we can't restore — that's fine.
+            end
+          end
+        else
+          yield
+        end
+      rescue StandardError => e
+        raise Timeout, e.message if timeout_error?(e)
+
+        raise
+      end
+
+      def vendor
+        @connection.server_version.vendor
+      end
+
+      def mask_rows(result)
+        mask_indices = result.columns.each_with_index.select do |name, _i|
+          SqlValidator.masked_column?(name, @config.masked_column_patterns)
+        end.map { |(_name, i)| i }.to_set
+
+        return result.rows if mask_indices.empty?
+
+        result.rows.map do |row|
+          row.each_with_index.map { |value, i| mask_indices.include?(i) ? "[REDACTED]" : value }
+        end
+      end
+
+      def timeout_error?(exception)
+        msg = exception.message
+        TIMEOUT_PATTERNS.any? { |pattern| msg.include?(pattern) }
+      end
+    end
+  end
+end

data/lib/sql_genius/core/result.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    # Immutable value object representing the result of a query.
+    # Adapters translate their native result types into this shape.
+    class Result
+      include Enumerable
+
+      attr_reader :columns, :rows
+
+      def initialize(columns:, rows:)
+        @columns = columns.freeze
+        @rows = rows.freeze
+        freeze
+      end
+
+      def each(&block)
+        return @rows.each unless block
+
+        @rows.each(&block)
+      end
+
+      def to_a
+        @rows.dup
+      end
+
+      def count
+        @rows.length
+      end
+
+      def empty?
+        @rows.empty?
+      end
+
+      # Returns rows as an array of hashes keyed by column name. Mirrors
+      # ActiveRecord::Result#to_a's hashification behavior.
+      def to_hashes
+        @rows.map { |row| @columns.zip(row).to_h }
+      end
+    end
+  end
+end

data/lib/sql_genius/core/server_info.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    # Identifies the database vendor and version. Adapters construct one
+    # from the server's VERSION() output.
+    #
+    # Three vendors are recognised: :mysql, :mariadb, :postgresql.
+    # #dialect collapses these into the SQL family used by query builders
+    # — :mysql (covering both MySQL and MariaDB) or :postgresql.
+    class ServerInfo
+      attr_reader :vendor, :version
+
+      class << self
+        def parse(version_string)
+          str = version_string.to_s
+          vendor = if str.match?(/postgresql/i)
+            :postgresql
+          elsif str.downcase.include?("mariadb")
+            :mariadb
+          else
+            :mysql
+          end
+          new(vendor: vendor, version: str)
+        end
+      end
+
+      # vendor must be :mysql, :mariadb, or :postgresql
+      def initialize(vendor:, version:)
+        @vendor = vendor
+        @version = version
+        freeze
+      end
+
+      def mariadb?
+        @vendor == :mariadb
+      end
+
+      def mysql?
+        @vendor == :mysql
+      end
+
+      def postgresql?
+        @vendor == :postgresql
+      end
+
+      # SQL family used to pick a query builder. MySQL and MariaDB share
+      # one dialect; PostgreSQL is its own.
+      def dialect
+        postgresql? ? :postgresql : :mysql
+      end
+    end
+  end
+end

data/lib/sql_genius/core/sql_validator.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module SqlValidator
+      FORBIDDEN_KEYWORDS = ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "CREATE", "TRUNCATE", "GRANT", "REVOKE"].freeze
+
+      MYSQL_SYSTEM_SCHEMAS = ["information_schema", "mysql", "performance_schema", "sys"].freeze
+      POSTGRESQL_SYSTEM_SCHEMAS = ["information_schema", "pg_catalog", "pg_toast", "pg_temp"].freeze
+
+      extend self
+
+      def validate(sql, blocked_tables:, connection:)
+        return "Please enter a query." if sql.nil? || sql.strip.empty?
+
+        normalized = sql.gsub(/--.*$/, "").gsub(%r{/\*.*?\*/}m, "").strip
+
+        unless normalized.match?(/\ASELECT\b/i) || normalized.match?(/\AWITH\b/i)
+          return "Only SELECT queries are allowed."
+        end
+
+        system_schemas = system_schemas_for(connection)
+        if normalized.match?(/\b(#{system_schemas.join("|")})\b/i)
+          return "Access to system schemas is not allowed."
+        end
+
+        FORBIDDEN_KEYWORDS.each do |keyword|
+          return "#{keyword} statements are not allowed." if normalized.match?(/\b#{keyword}\b/i)
+        end
+
+        tables_in_query = extract_table_references(normalized, connection)
+        blocked = tables_in_query & blocked_tables
+        if blocked.any?
+          return "Access denied for table(s): #{blocked.join(", ")}."
+        end
+
+        nil
+      end
+
+      def extract_table_references(sql, connection)
+        tables = []
+        sql.scan(/\bFROM\s+((?:["`]?\w+["`]?(?:\s*,\s*["`]?\w+["`]?)*)+)/i) do |m|
+          m[0].scan(/["`]?(\w+)["`]?/) { |t| tables << t[0] }
+        end
+        sql.scan(/\bJOIN\s+["`]?(\w+)["`]?/i) { |m| tables << m[0] }
+        sql.scan(/\b(?:INTO|UPDATE)\s+["`]?(\w+)["`]?/i) { |m| tables << m[0] }
+        tables.uniq.map(&:downcase) & connection.tables
+      end
+
+      def apply_row_limit(sql, limit)
+        if sql.match?(/\bLIMIT\s+\d+\s*,\s*\d+/i)
+          sql.gsub(/\bLIMIT\s+(\d+)\s*,\s*(\d+)/i) do
+            "LIMIT #{::Regexp.last_match(1).to_i}, #{[::Regexp.last_match(2).to_i, limit].min}"
+          end
+        elsif sql.match?(/\bLIMIT\s+\d+/i)
+          sql.gsub(/\bLIMIT\s+(\d+)/i) { "LIMIT #{[::Regexp.last_match(1).to_i, limit].min}" }
+        else
+          "#{sql.gsub(/;\s*\z/, "")} LIMIT #{limit}"
+        end
+      end
+
+      def normalize_identifier_quotes(sql, connection)
+        quote = connection.quote_table_name("sql_genius_identifier_probe")[0]
+        return sql if quote == "`" || !sql.include?("`")
+
+        rewrite_backtick_identifiers(sql, connection)
+      end
+
+      def masked_column?(column_name, patterns)
+        patterns.any? { |pattern| column_name.downcase.include?(pattern) }
+      end
+
+      def system_schemas_for(connection)
+        return MYSQL_SYSTEM_SCHEMAS unless connection.respond_to?(:server_version)
+
+        connection.server_version.postgresql? ? POSTGRESQL_SYSTEM_SCHEMAS : MYSQL_SYSTEM_SCHEMAS
+      rescue StandardError
+        MYSQL_SYSTEM_SCHEMAS
+      end
+
+      def rewrite_backtick_identifiers(sql, connection)
+        output = +""
+        i = 0
+
+        while i < sql.length
+          char = sql[i]
+
+          if char == "'"
+            literal, i = read_single_quoted_literal(sql, i)
+            output << literal
+          elsif char == "`"
+            identifier, i = read_backtick_identifier(sql, i)
+            output << connection.quote_table_name(identifier)
+          else
+            output << char
+            i += 1
+          end
+        end
+
+        output
+      end
+
+      def read_single_quoted_literal(sql, index)
+        output = +"'"
+        i = index + 1
+
+        while i < sql.length
+          output << sql[i]
+          if sql[i] == "'"
+            if sql[i + 1] == "'"
+              output << sql[i + 1]
+              i += 2
+              next
+            end
+
+            i += 1
+            break
+          end
+          i += 1
+        end
+
+        [output, i]
+      end
+
+      def read_backtick_identifier(sql, index)
+        output = +""
+        i = index + 1
+
+        while i < sql.length
+          if sql[i] == "`"
+            if sql[i + 1] == "`"
+              output << "`"
+              i += 2
+              next
+            end
+
+            i += 1
+            break
+          end
+
+          output << sql[i]
+          i += 1
+        end
+
+        [output, i]
+      end
+    end
+  end
+end

data/lib/sql_genius/core/views/sql_genius/queries/_shared_results.html.erb

@@ -0,0 +1,59 @@
+<!-- Explain Results -->
+<div id="explain-results" class="mg-mt mg-hidden">
+  <div class="mg-card">
+    <div class="mg-card-header">
+      <span><strong>&#128270; EXPLAIN Output</strong></span>
+      <div>
+        <% if @ai_enabled %>
+          <button id="explain-optimize" class="mg-btn mg-btn-outline mg-btn-sm">&#9889; AI Optimization</button>
+          <button id="explain-index-advisor" class="mg-btn mg-btn-outline mg-btn-sm">&#9889; Index Advisor</button>
+        <% end %>
+        <button id="explain-close" class="mg-btn mg-btn-outline-secondary mg-btn-sm">&#10005; Close</button>
+      </div>
+    </div>
+    <div class="mg-card-body">
+      <div class="mg-table-wrap">
+        <table class="mg-table">
+          <thead id="explain-thead"></thead>
+          <tbody id="explain-tbody"></tbody>
+        </table>
+      </div>
+      <div id="optimize-results" class="mg-hidden mg-mt">
+        <div id="optimize-content" class="mg-alert mg-alert-info"></div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<!-- Results Area -->
+<div id="query-results" class="mg-mt mg-hidden">
+  <div style="display:flex;justify-content:space-between;align-items:center;">
+    <div id="results-stats" class="mg-mb mg-hidden">
+      <span id="results-row-count" class="mg-badge mg-badge-info"></span>
+      <span id="results-time" class="mg-badge mg-badge-secondary"></span>
+      <span id="results-truncated" class="mg-badge mg-badge-warning mg-hidden">Results truncated</span>
+    </div>
+    <button id="results-close" class="mg-btn mg-btn-outline-secondary mg-btn-sm" style="margin-bottom:12px;">&#10005; Dismiss</button>
+  </div>
+  <div id="results-alert" class="mg-hidden"></div>
+  <div id="results-table-wrapper" class="mg-table-wrap mg-hidden">
+    <table class="mg-table">
+      <thead id="results-thead"></thead>
+      <tbody id="results-tbody"></tbody>
+    </table>
+  </div>
+  <div id="results-empty" class="mg-text-center mg-text-muted mg-hidden">No rows returned.</div>
+</div>
+
+<!-- AI Query Analysis Results -->
+<div id="ai-query-result" class="mg-mt mg-hidden">
+  <div class="mg-card">
+    <div class="mg-card-header">
+      <span id="ai-query-title"><strong>&#9889; AI Analysis</strong></span>
+      <button id="ai-query-close" class="mg-btn mg-btn-outline-secondary mg-btn-sm">&#10005;</button>
+    </div>
+    <div class="mg-card-body">
+      <div id="ai-query-content" style="font-size:13px;"></div>
+    </div>
+  </div>
+</div>

data/lib/sql_genius/core/views/sql_genius/queries/_tab_ai_tools.html.erb

@@ -0,0 +1,43 @@
+<!-- AI Tools Tab -->
+<div class="mg-tab-content" id="tab-aitools">
+  <!-- Schema Review -->
+  <div class="mg-card mg-mb">
+    <div class="mg-card-header"><strong>&#9889; Schema Review</strong></div>
+    <div class="mg-card-body">
+      <div class="mg-text-muted mg-mb" style="font-size:12px;">Analyze your schema for anti-patterns: inappropriate column types, missing indexes, naming inconsistencies, and more.</div>
+      <div class="mg-row" style="align-items:flex-end;">
+        <div class="mg-col-4 mg-field">
+          <label for="schema-table">Table (leave blank for all)</label>
+          <select id="schema-table">
+            <option value="">All tables (top 20)</option>
+            <% @all_tables.each do |table| %>
+              <option value="<%= table %>"><%= table %></option>
+            <% end %>
+          </select>
+        </div>
+        <div class="mg-field">
+          <button id="schema-review-btn" class="mg-btn mg-btn-primary mg-btn-sm">&#9889; Analyze Schema</button>
+        </div>
+      </div>
+      <div id="schema-result" class="mg-mt mg-hidden">
+        <div id="schema-result-content" style="font-size:13px;"></div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Migration Risk Assessment -->
+  <div class="mg-card">
+    <div class="mg-card-header"><strong>&#9889; Migration Risk Assessment</strong></div>
+    <div class="mg-card-body">
+      <div class="mg-text-muted mg-mb" style="font-size:12px;">Paste a Rails migration or DDL and get a risk assessment: lock duration, impact on active queries, deployment strategy.</div>
+      <div class="mg-field">
+        <textarea id="migration-input" rows="8" placeholder="class AddIndexToUsers < ActiveRecord::Migration[7.0]&#10;  def change&#10;    add_index :users, :email, unique: true&#10;  end&#10;end"></textarea>
+      </div>
+      <button id="migration-assess-btn" class="mg-btn mg-btn-primary mg-btn-sm">&#9889; Assess Risk</button>
+      <div id="migration-result" class="mg-mt mg-hidden">
+        <div id="migration-risk-badge" style="margin-bottom:8px;"></div>
+        <div id="migration-result-content" style="font-size:13px;"></div>
+      </div>
+    </div>
+  </div>
+</div>