sql_genius 0.9.0

data/lib/sql_genius/core/ai/schema_review.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Ai
+      # Reviews a schema for anti-patterns. Takes a specific table name
+      # (or nil to review the top 20 queryable tables).
+      class SchemaReview
+        def initialize(client, config, connection)
+          @client = client
+          @config = config
+          @connection = connection
+        end
+
+        def call(table)
+          tables_to_review = table.nil? || table.to_s.empty? ? @connection.tables.first(20) : [table]
+          schema_desc = SchemaContextBuilder.new(@connection).call(tables_to_review, detail: :basic)
+
+          messages = [
+            { role: "system", content: system_prompt },
+            { role: "user",   content: schema_desc },
+          ]
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def system_prompt
+          <<~PROMPT
+            You are a #{DialectHints.name_for(@connection)} schema reviewer. Analyze the following schema and identify anti-patterns and improvement opportunities. Look for:
+            - Inappropriate column types (VARCHAR(255) for short values, TEXT where VARCHAR suffices, INT for booleans)
+            - Missing indexes on foreign key columns or frequently filtered columns
+            - Missing NOT NULL constraints where NULLs are unlikely
+            - ENUM columns that should be lookup tables
+            - Missing created_at/updated_at timestamps
+            - Tables without a PRIMARY KEY
+            - Overly wide indexes or redundant indexes
+            - Column naming inconsistencies
+            #{@config.domain_context}
+            Respond with JSON: {"findings": "markdown-formatted findings organized by severity (Critical, Warning, Suggestion). Include specific ALTER TABLE statements where applicable."}
+          PROMPT
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/ai/suggestion.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Ai
+      # Turns a natural-language prompt + a list of allowed tables into
+      # a SELECT query via the AI client.
+      #
+      # Construct with:
+      #   connection - a Core::Connection implementation
+      #   client     - a Core::Ai::Client (pre-built with the same config)
+      #   config     - the Core::Ai::Config (used for system_context)
+      #
+      # Call:
+      #   .call(user_prompt, allowed_tables)  -> Hash with "sql" and "explanation"
+      class Suggestion
+        def initialize(connection, client, config)
+          @connection = connection
+          @client = client
+          @config = config
+        end
+
+        def call(user_prompt, allowed_tables)
+          schema = build_schema_description(allowed_tables)
+          messages = [
+            { role: "system", content: system_prompt(schema) },
+            { role: "user", content: user_prompt },
+          ]
+
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def system_prompt(schema_description)
+          prompt = +"You are a SQL query assistant for a #{DialectHints.name_for(@connection)} database.\n"
+
+          if @config.system_context && !@config.system_context.empty?
+            prompt += <<~PROMPT
+
+              Domain context:
+              #{@config.system_context}
+            PROMPT
+          end
+
+          prompt += <<~PROMPT
+
+            Rules:
+            - Only generate SELECT statements. Never generate INSERT, UPDATE, DELETE, or any other mutation.
+            - Only reference the tables and columns listed in the schema below. Do not guess or invent column names.
+            - #{DialectHints.identifier_quoting_rule(@connection)}
+            - Include a LIMIT 100 unless the user specifies otherwise.
+
+            Available schema:
+            #{schema_description}
+
+            Respond with JSON: {"sql": "the SQL query", "explanation": "brief explanation of what the query does"}
+          PROMPT
+
+          prompt
+        end
+
+        def build_schema_description(allowed_tables)
+          allowed_tables.map do |table|
+            next unless @connection.tables.include?(table)
+
+            columns = @connection.columns_for(table).map { |c| "#{c.name} (#{c.type})" }
+            "#{table}: #{columns.join(", ")}"
+          end.compact.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/ai/variable_reviewer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Ai
+      # Reviews MySQL configuration variables against best practices for
+      # the observed workload. Gathers SHOW GLOBAL VARIABLES (filtered to
+      # ~20 performance-relevant keys) and SHOW GLOBAL STATUS, then asks
+      # the LLM to identify misconfigurations.
+      class VariableReviewer
+        RELEVANT_VARIABLES = [
+          "innodb_buffer_pool_size",
+          "innodb_log_file_size",
+          "innodb_flush_log_at_trx_commit",
+          "max_connections",
+          "query_cache_type",
+          "sort_buffer_size",
+          "join_buffer_size",
+          "tmp_table_size",
+          "max_heap_table_size",
+          "thread_cache_size",
+          "table_open_cache",
+          "innodb_file_per_table",
+          "innodb_flush_method",
+          "binlog_format",
+          "sync_binlog",
+          "innodb_io_capacity",
+          "innodb_read_io_threads",
+          "innodb_write_io_threads",
+          "long_query_time",
+          "slow_query_log",
+          "performance_schema",
+        ].freeze
+
+        RELEVANT_STATUS_KEYS = [
+          "Innodb_buffer_pool_reads",
+          "Innodb_buffer_pool_read_requests",
+          "Created_tmp_disk_tables",
+          "Created_tmp_tables",
+          "Sort_merge_passes",
+          "Threads_created",
+          "Threads_connected",
+          "Max_used_connections",
+          "Slow_queries",
+          "Questions",
+          "Uptime",
+        ].freeze
+
+        def initialize(client, config, connection)
+          @client = client
+          @config = config
+          @connection = connection
+        end
+
+        def call
+          if @connection.server_version.postgresql?
+            raise Core::UnsupportedDialect.for_postgresql("Variable Config Reviewer")
+          end
+
+          variables = fetch_variables
+          status = fetch_status
+
+          messages = [
+            { role: "system", content: system_prompt },
+            { role: "user",   content: user_prompt(variables, status) },
+          ]
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def fetch_variables
+          result = @connection.exec_query("SHOW GLOBAL VARIABLES")
+          result.rows
+            .select { |row| RELEVANT_VARIABLES.include?(row[0]) }
+            .map { |row| [row[0], row[1]] }
+        end
+
+        def fetch_status
+          result = @connection.exec_query("SHOW GLOBAL STATUS")
+          result.rows
+            .select { |row| RELEVANT_STATUS_KEYS.include?(row[0]) }
+            .map { |row| [row[0], row[1]] }
+        end
+
+        def system_prompt
+          <<~PROMPT
+            You are a MySQL configuration reviewer. Analyze the server variables and status counters below, then identify misconfigurations and improvement opportunities. Consider:
+            - Buffer pool sizing relative to workload (hit rate from status counters)
+            - Temporary table spills to disk (tmp_table_size vs Created_tmp_disk_tables)
+            - Sort buffer and join buffer sizing
+            - Connection pool sizing (max_connections vs Max_used_connections)
+            - Thread cache effectiveness
+            - InnoDB flush and sync settings for durability vs performance trade-offs
+            - Slow query log configuration
+            - Binary log format suitability
+            #{@config.domain_context}
+            Respond with JSON: {"findings": "markdown-formatted analysis organized by severity (Critical, Warning, Suggestion). Include specific SET GLOBAL or my.cnf recommendations with before/after values."}
+          PROMPT
+        end
+
+        def user_prompt(variables, status)
+          lines = ["== Server Variables =="]
+          variables.each { |name, value| lines << "#{name} = #{value}" }
+          lines << ""
+          lines << "== Server Status Counters =="
+          status.each { |name, value| lines << "#{name} = #{value}" }
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/ai/workload_digest.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Ai
+      # Produces a high-level executive summary of the query workload by
+      # pulling the top statements from performance_schema and asking the
+      # LLM to characterize read/write ratio, access patterns, waste
+      # concentration, and highest-leverage optimization opportunities.
+      #
+      # Construct with:
+      #   connection - a Core::Connection implementation
+      #   client     - a Core::Ai::Client
+      #   config     - the Core::Ai::Config
+      #
+      # Call:
+      #   .call() -> Hash with "digest" key containing markdown analysis
+      class WorkloadDigest
+        TOP_N = 30
+
+        def initialize(connection, client, config)
+          @connection = connection
+          @client = client
+          @config = config
+        end
+
+        def call
+          stats = Analysis::QueryStats.new(@connection).call(sort: "total_time", limit: TOP_N)
+          formatted = format_stats(stats)
+
+          messages = [
+            { role: "system", content: system_prompt },
+            { role: "user", content: user_prompt(formatted, stats.length) },
+          ]
+
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def system_prompt
+          prompt = <<~PROMPT
+            You are a #{DialectHints.name_for(@connection)} performance analyst producing an executive workload digest.
+          PROMPT
+
+          if @config.domain_context && !@config.domain_context.empty?
+            prompt += <<~PROMPT
+
+              Domain context:
+              #{@config.domain_context}
+            PROMPT
+          end
+
+          prompt += <<~PROMPT
+
+            Analyze the provided query workload data and produce a concise executive summary covering:
+            1. Read vs write ratio and overall workload characterization
+            2. Access patterns (point lookups, range scans, full table scans, aggregations)
+            3. Waste concentration — which queries examine many rows but return few
+            4. Top 3 highest-leverage changes that would improve overall performance
+
+            Respond with JSON: {"digest": "markdown-formatted workload analysis"}
+          PROMPT
+
+          prompt
+        end
+
+        def user_prompt(formatted_stats, count)
+          <<~PROMPT
+            Top #{count} queries by total execution time:
+
+            #{formatted_stats}
+          PROMPT
+        end
+
+        def format_stats(stats)
+          stats.map.with_index(1) do |s, i|
+            "#{i}. SQL: #{s[:sql]}\n   " \
+              "calls=#{s[:calls]}, avg_time_ms=#{s[:avg_time_ms]}, " \
+              "rows_ratio=#{s[:rows_ratio]}, tmp_disk_tables=#{s[:tmp_disk_tables]}"
+          end.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/analysis/columns.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Service class for the Rails engine's GET /columns action. Takes a
+      # Core::Connection and the relevant configuration; returns a tagged
+      # Result struct that the controller maps to HTTP responses.
+      #
+      # Each status maps 1:1 to an HTTP status code:
+      #   :ok        → 200 with columns: array
+      #   :blocked   → 403 with error_message:
+      #   :not_found → 404 with error_message:
+      #
+      # The adapter reads result.status and dispatches accordingly.
+      class Columns
+        Result = Struct.new(:status, :columns, :error_message, keyword_init: true)
+
+        def initialize(connection, blocked_tables:, masked_column_patterns:, default_columns:)
+          @connection = connection
+          @blocked_tables = blocked_tables
+          @masked_column_patterns = masked_column_patterns
+          @default_columns = default_columns
+        end
+
+        def call(table:)
+          return blocked_result(table)   if @blocked_tables.include?(table)
+          return not_found_result(table) unless @connection.tables.include?(table)
+
+          defaults = @default_columns[table] || []
+          visible = @connection.columns_for(table).reject do |col|
+            SqlValidator.masked_column?(col.name, @masked_column_patterns)
+          end
+          formatted = visible.map do |col|
+            {
+              name: col.name,
+              type: col.type.to_s,
+              default: defaults.empty? || defaults.include?(col.name),
+            }
+          end
+
+          Result.new(status: :ok, columns: formatted)
+        end
+
+        private
+
+        def blocked_result(table)
+          Result.new(
+            status: :blocked,
+            error_message: "Table '#{table}' is not available for querying.",
+          )
+        end
+
+        def not_found_result(table)
+          Result.new(
+            status: :not_found,
+            error_message: "Table '#{table}' does not exist.",
+          )
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/analysis/duplicate_indexes.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "set"
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Detects indexes whose columns are a left-prefix of another index on
+      # the same table (meaning the shorter index is redundant — the longer
+      # one can satisfy the same queries). Preserves unique indexes: a unique
+      # index is never flagged as redundant when only covered by a non-unique
+      # index.
+      #
+      # Takes a Core::Connection plus a list of tables to exclude from the
+      # scan. Returns an array of hashes describing each duplicate pair, with
+      # the (duplicate_index, covered_by_index) pair deduplicated across
+      # symmetrical relationships.
+      class DuplicateIndexes
+        def initialize(connection, blocked_tables:)
+          @connection = connection
+          @blocked_tables = blocked_tables
+          @builder = QueryBuilders.for(connection)
+        end
+
+        def call
+          duplicates = []
+
+          queryable_tables.each do |table|
+            indexes = @connection.indexes_for(table)
+            next if indexes.size < 2
+
+            indexes.each do |idx|
+              indexes.each do |other|
+                next if idx.name == other.name
+                next unless covers?(other, idx)
+
+                duplicates << {
+                  table: table,
+                  duplicate_index: idx.name,
+                  duplicate_columns: idx.columns,
+                  covered_by_index: other.name,
+                  covered_by_columns: other.columns,
+                  unique: idx.unique,
+                  drop_sql: @builder.drop_index_sql(table: table, index_name: idx.name),
+                }
+              end
+            end
+          end
+
+          deduplicate(duplicates)
+        end
+
+        private
+
+        def queryable_tables
+          @connection.tables - @blocked_tables
+        end
+
+        # True if `other` covers `idx` (idx's columns are a left-prefix of
+        # other's columns). Protects unique indexes from being covered by
+        # non-unique ones.
+        def covers?(other, idx)
+          return false if idx.columns.size > other.columns.size
+          return false unless other.columns.first(idx.columns.size) == idx.columns
+          return false if idx.unique && !other.unique
+
+          true
+        end
+
+        def deduplicate(duplicates)
+          seen = Set.new
+          duplicates.reject do |d|
+            key = [d[:table], [d[:duplicate_index], d[:covered_by_index]].sort].flatten.join(":")
+            if seen.include?(key)
+              true
+            else
+              seen.add(key)
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/analysis/query_history.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Fetches a single query's aggregated stats by its digest/queryid for the
+      # query detail page. Returns nil if the digest is not found in the
+      # statement-stats source for the current database.
+      #
+      # On MySQL/MariaDB this reads performance_schema.events_statements_summary_by_digest;
+      # on PostgreSQL it reads pg_stat_statements joined with pg_database.
+      class QueryHistory
+        def initialize(connection)
+          @connection = connection
+          @builder = QueryBuilders.for(connection)
+        end
+
+        def call(digest)
+          digest_str = digest.to_s
+          return if digest_str.empty?
+
+          sql = @builder.query_history(@connection, digest: digest_str)
+          result = @connection.exec_query(sql)
+          row = result.to_hashes.first
+          return unless row
+
+          {
+            sql: row["DIGEST_TEXT"] || row["digest_text"],
+            calls: (row["calls"] || row["CALLS"] || 0).to_i,
+            total_time_ms: (row["total_time_ms"] || 0).to_f,
+            avg_time_ms: (row["avg_time_ms"] || 0).to_f,
+            max_time_ms: (row["max_time_ms"] || 0).to_f,
+            rows_examined: (row["rows_examined"] || row["ROWS_EXAMINED"] || 0).to_i,
+            rows_sent: (row["rows_sent"] || row["ROWS_SENT"] || 0).to_i,
+            first_seen: (row["FIRST_SEEN"] || row["first_seen"]).to_s,
+            last_seen: (row["LAST_SEEN"] || row["last_seen"]).to_s,
+          }
+        end
+
+        def digest_text_for(digest)
+          digest_str = digest.to_s
+          return if digest_str.empty?
+
+          sql = @builder.digest_text_lookup(@connection, digest: digest_str)
+          @connection.select_value(sql)
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/analysis/query_stats.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Top statements by a given sort dimension, sourced from MySQL's
+      # performance_schema.events_statements_summary_by_digest or PostgreSQL's
+      # pg_stat_statements (whichever the connected server provides). Returns
+      # an array of per-digest hashes with call counts, timing percentiles,
+      # row examine/sent ratios, and temp-table metadata.
+      #
+      # If the underlying stats source is not enabled, the SQL exec will
+      # raise — the caller decides how to render that.
+      class QueryStats
+        VALID_SORTS = ["total_time", "avg_time", "calls", "rows_examined"].freeze
+        MAX_LIMIT = 50
+
+        def initialize(connection)
+          @connection = connection
+          @builder = QueryBuilders.for(connection)
+        end
+
+        def call(sort: "total_time", limit: MAX_LIMIT)
+          order_clause = @builder.query_stats_order_clause(sort)
+          effective_limit = limit.to_i.clamp(1, MAX_LIMIT)
+
+          sql = @builder.query_stats(
+            @connection,
+            order_clause: order_clause,
+            limit: effective_limit,
+            include_digest: digest_column_available?,
+          )
+          result = @connection.exec_query(sql)
+          result.to_hashes.map { |row| transform(row) }
+        end
+
+        private
+
+        def transform(row)
+          digest = (row["DIGEST_TEXT"] || row["digest_text"] || "").to_s
+          calls = (row["calls"] || row["CALLS"] || 0).to_i
+          rows_examined = (row["rows_examined"] || row["ROWS_EXAMINED"] || 0).to_i
+          rows_sent = (row["rows_sent"] || row["ROWS_SENT"] || 0).to_i
+
+          {
+            digest: (row["DIGEST"] || row["digest"] || "").to_s,
+            sql: truncate(digest, 500),
+            calls: calls,
+            total_time_ms: (row["total_time_ms"] || 0).to_f,
+            avg_time_ms: (row["avg_time_ms"] || 0).to_f,
+            max_time_ms: (row["max_time_ms"] || 0).to_f,
+            rows_examined: rows_examined,
+            rows_sent: rows_sent,
+            rows_ratio: rows_sent.positive? ? (rows_examined.to_f / rows_sent).round(1) : 0,
+            tmp_disk_tables: (row["tmp_disk_tables"] || row["TMP_DISK_TABLES"] || 0).to_i,
+            sort_rows: (row["sort_rows"] || row["SORT_ROWS"] || 0).to_i,
+            first_seen: row["FIRST_SEEN"] || row["first_seen"],
+            last_seen: row["LAST_SEEN"] || row["last_seen"],
+          }
+        end
+
+        def truncate(string, max)
+          return string if string.length <= max
+
+          "#{string[0, max - 3]}..."
+        end
+
+        def digest_column_available?
+          return @digest_available if defined?(@digest_available)
+
+          @digest_available = @builder.digest_column_available?(@connection)
+        end
+      end
+    end
+  end
+end