mysql_genius-core 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 70f7ef02105463808683263b268e297b98907545c80b8379a36517b8a2f74a76
+  data.tar.gz: b6c41d695b0cc433dac7e625d08c15a470da36304ccf54eb27be66be0e79118d
+SHA512:
+  metadata.gz: 4c93fad1632ccd9fe8859b40880fad565e43467ae761bb550972a2af750a43636e22779a2e34b93678e16f6c268b1a950693a668b22e21f8822504abe42057e3
+  data.tar.gz: 2c7c33af4765ab2eb520de0f5a95442abfe5b7b8875f4d0ba31cf887c7f227070cb74ab9339faa394c3033ddc87dc959dfc2cf14e16ef5a244cee80dd5c590e9

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.4.0
+
+First published release of `mysql_genius-core`. This gem is the Rails-free foundation library for `mysql_genius` and will be the shared core for the forthcoming `mysql_genius-desktop` standalone app. From 0.4.0 onward, `mysql_genius-core` and `mysql_genius` release in lockstep under matching version numbers.
+
+### Added
+- `MysqlGenius::Core::Connection` — connection contract with `ActiveRecordAdapter` (used by the Rails engine) and `FakeAdapter` (used in specs).
+- `MysqlGenius::Core::SqlValidator` — SELECT-only validation, blocked-table enforcement, row-limit application.
+- `MysqlGenius::Core::Ai::{Client, Suggestion, Optimization}` — AI service layer taking an explicit `Core::Ai::Config` instead of reading global configuration.
+- `MysqlGenius::Core::Result`, `ColumnDefinition`, `IndexDefinition`, `ServerInfo` — value objects returned by adapters and analyses.
+- `MysqlGenius::Core::Analysis::TableSizes` — queries `information_schema.tables` + per-table `COUNT(*)` with size/row/fragmentation metadata.
+- `MysqlGenius::Core::Analysis::DuplicateIndexes` — detects left-prefix covering across indexes per table.
+- `MysqlGenius::Core::Analysis::QueryStats` — reads `performance_schema.events_statements_summary_by_digest` with sort + limit.
+- `MysqlGenius::Core::Analysis::UnusedIndexes` — reads `performance_schema.table_io_waits_summary_by_index_usage` JOINed with `information_schema.tables`.
+- `MysqlGenius::Core::Analysis::ServerOverview` — reads `SHOW GLOBAL STATUS` / `SHOW GLOBAL VARIABLES` / `SELECT VERSION()`, computes derived metrics.
+- `MysqlGenius::Core::ExecutionResult` — immutable value object for `QueryRunner`'s return.
+- `MysqlGenius::Core::QueryRunner` + `QueryRunner::Config` — owns validation, row-limit/timeout-hint application, execution, column masking. Returns `ExecutionResult` or raises `Rejected` / `Timeout`.
+- `MysqlGenius::Core::QueryExplainer` — owns EXPLAIN with optional validation-skipping. Returns `Core::Result` or raises `Rejected` / `Truncated`.
+
+MariaDB vs MySQL is detected at runtime so timeout hints use the correct syntax (`SET STATEMENT max_statement_time` vs `MAX_EXECUTION_TIME` optimizer hint).

data/lib/mysql_genius/core/ai/client.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module MysqlGenius
+  module Core
+    module Ai
+      # HTTP client for OpenAI-compatible chat completion APIs.
+      # Construct with a Core::Ai::Config; call #chat with a messages array.
+      class Client
+        class NotConfigured < Core::Error; end
+        class ApiError < Core::Error; end
+        class TooManyRedirects < Core::Error; end
+
+        MAX_REDIRECTS = 3
+
+        def initialize(config)
+          @config = config
+        end
+
+        def chat(messages:, temperature: 0)
+          if @config.client
+            return @config.client.call(messages: messages, temperature: temperature)
+          end
+
+          raise NotConfigured, "AI is not configured" unless @config.enabled?
+
+          body = {
+            messages: messages,
+            response_format: { type: "json_object" },
+            temperature: temperature,
+          }
+          body[:model] = @config.model if @config.model && !@config.model.empty?
+
+          response = post_with_redirects(URI(@config.endpoint), body.to_json)
+          parsed = JSON.parse(response.body)
+
+          if parsed["error"]
+            raise ApiError, "AI API error: #{parsed["error"]["message"] || parsed["error"]}"
+          end
+
+          content = parsed.dig("choices", 0, "message", "content")
+          raise ApiError, "No content in AI response" if content.nil?
+
+          parse_json_content(content)
+        end
+
+        private
+
+        def parse_json_content(content)
+          JSON.parse(content)
+        rescue JSON::ParserError
+          stripped = content.to_s
+            .gsub(/\A\s*```(?:json)?\s*/i, "")
+            .gsub(/\s*```\s*\z/, "")
+            .strip
+          begin
+            JSON.parse(stripped)
+          rescue JSON::ParserError
+            { "raw" => content.to_s }
+          end
+        end
+
+        def post_with_redirects(uri, body, redirects = 0)
+          raise TooManyRedirects, "Too many redirects" if redirects > MAX_REDIRECTS
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          if http.use_ssl?
+            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+            cert_file = ENV["SSL_CERT_FILE"] || OpenSSL::X509::DEFAULT_CERT_FILE
+            http.ca_file = cert_file if File.exist?(cert_file)
+          end
+          http.open_timeout = 10
+          http.read_timeout = 60
+
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          if @config.auth_style == :bearer
+            request["Authorization"] = "Bearer #{@config.api_key}"
+          else
+            request["api-key"] = @config.api_key
+          end
+          request.body = body
+
+          response = http.request(request)
+
+          if response.is_a?(Net::HTTPRedirection)
+            post_with_redirects(URI(response["location"]), body, redirects + 1)
+          else
+            response
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/ai/config.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Ai
+      # Keyword-init value object holding all the AI settings a Client
+      # needs. Passed explicitly to every AI service constructor — no
+      # module-level globals.
+      #
+      # Fields:
+      #   client         - optional callable; when set, bypasses HTTP.
+      #                    Signature: #call(messages:, temperature:) -> Hash
+      #   endpoint       - HTTPS URL of the chat completions endpoint
+      #   api_key        - API key (used as Bearer or api-key header)
+      #   model          - model name passed in the request body
+      #   auth_style     - :bearer or :api_key
+      #   system_context - optional domain context string that services
+      #                    append to their system prompts
+      Config = Struct.new(
+        :client,
+        :endpoint,
+        :api_key,
+        :model,
+        :auth_style,
+        :system_context,
+        keyword_init: true,
+      ) do
+        def initialize(*)
+          super
+          freeze
+        end
+
+        def enabled?
+          return true if client
+          return false if endpoint.nil? || endpoint.to_s.empty?
+          return false if api_key.nil? || api_key.to_s.empty?
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/ai/optimization.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Ai
+      # Analyses a SQL query + its EXPLAIN output and asks the AI client
+      # for optimization suggestions.
+      #
+      # Construct with:
+      #   connection - a Core::Connection implementation
+      #   client     - a Core::Ai::Client
+      #   config     - the Core::Ai::Config
+      #
+      # Call:
+      #   .call(sql, explain_rows, allowed_tables)
+      #     explain_rows - Array of arrays OR a pre-formatted String
+      #     -> Hash with "suggestions" key
+      class Optimization
+        def initialize(connection, client, config)
+          @connection = connection
+          @client = client
+          @config = config
+        end
+
+        def call(sql, explain_rows, allowed_tables)
+          schema = build_schema_description(allowed_tables)
+          messages = [
+            { role: "system", content: system_prompt(schema) },
+            { role: "user", content: user_prompt(sql, explain_rows) },
+          ]
+
+          @client.chat(messages: messages)
+        end
+
+        private
+
+        def system_prompt(schema_description)
+          <<~PROMPT
+            You are a MySQL query optimization expert. Given a SQL query and its EXPLAIN output, analyze the query execution plan and provide actionable optimization suggestions.
+
+            Available schema:
+            #{schema_description}
+
+            Respond with JSON:
+            {
+              "suggestions": "Markdown-formatted analysis and suggestions. Include: 1) Summary of current execution plan (scan types, rows examined). 2) Specific recommendations such as indexes to add (provide exact CREATE INDEX statements), query rewrites, or structural changes. 3) Expected impact of each suggestion."
+            }
+          PROMPT
+        end
+
+        def user_prompt(sql, explain_rows)
+          <<~PROMPT
+            SQL Query:
+            #{sql}
+
+            EXPLAIN Output:
+            #{format_explain(explain_rows)}
+          PROMPT
+        end
+
+        def format_explain(explain_rows)
+          return explain_rows if explain_rows.is_a?(String)
+
+          explain_rows.map { |row| row.join(" | ") }.join("\n")
+        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})" }
+            indexes = @connection.indexes_for(table).map { |idx| "#{idx.name}: [#{idx.columns.join(", ")}]#{" UNIQUE" if idx.unique}" }
+            desc = "#{table}: #{columns.join(", ")}"
+            desc += "\n  Indexes: #{indexes.join("; ")}" if indexes.any?
+            desc
+          end.compact.join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  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 = <<~PROMPT
+            You are a SQL query assistant for a MySQL database.
+          PROMPT
+
+          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.
+            - Use backticks for table and column names.
+            - 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/mysql_genius/core/analysis/duplicate_indexes.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "set"
+
+module MysqlGenius
+  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
+        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,
+                }
+              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/mysql_genius/core/analysis/query_stats.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Analysis
+      # Queries performance_schema.events_statements_summary_by_digest for
+      # the top statements by a given sort dimension, excluding noise
+      # (internal schema queries, EXPLAIN, SHOW, SET STATEMENT, etc.).
+      # Returns an array of per-digest hashes with call counts, timing
+      # percentiles, row examine/sent ratios, and temp-table metadata.
+      #
+      # If performance_schema is not enabled, the underlying exec_query
+      # call 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
+        end
+
+        def call(sort: "total_time", limit: MAX_LIMIT)
+          order_clause = order_clause_for(sort)
+          effective_limit = limit.to_i.clamp(1, MAX_LIMIT)
+
+          result = @connection.exec_query(build_sql(order_clause, effective_limit))
+          result.to_hashes.map { |row| transform(row) }
+        end
+
+        private
+
+        def order_clause_for(sort)
+          case sort
+          when "total_time"    then "SUM_TIMER_WAIT DESC"
+          when "avg_time"      then "AVG_TIMER_WAIT DESC"
+          when "calls"         then "COUNT_STAR DESC"
+          when "rows_examined" then "SUM_ROWS_EXAMINED DESC"
+          else "SUM_TIMER_WAIT DESC"
+          end
+        end
+
+        def build_sql(order_clause, limit)
+          <<~SQL
+            SELECT
+              DIGEST_TEXT,
+              COUNT_STAR AS calls,
+              ROUND(SUM_TIMER_WAIT / 1000000000, 1) AS total_time_ms,
+              ROUND(AVG_TIMER_WAIT / 1000000000, 1) AS avg_time_ms,
+              ROUND(MAX_TIMER_WAIT / 1000000000, 1) AS max_time_ms,
+              SUM_ROWS_EXAMINED AS rows_examined,
+              SUM_ROWS_SENT AS rows_sent,
+              SUM_CREATED_TMP_DISK_TABLES AS tmp_disk_tables,
+              SUM_SORT_ROWS AS sort_rows,
+              FIRST_SEEN,
+              LAST_SEEN
+            FROM performance_schema.events_statements_summary_by_digest
+            WHERE SCHEMA_NAME = #{@connection.quote(@connection.current_database)}
+              AND DIGEST_TEXT IS NOT NULL
+              AND DIGEST_TEXT NOT LIKE 'EXPLAIN%'
+              AND DIGEST_TEXT NOT LIKE '%`information_schema`%'
+              AND DIGEST_TEXT NOT LIKE '%`performance_schema`%'
+              AND DIGEST_TEXT NOT LIKE '%information_schema.%'
+              AND DIGEST_TEXT NOT LIKE '%performance_schema.%'
+              AND DIGEST_TEXT NOT LIKE 'SHOW %'
+              AND DIGEST_TEXT NOT LIKE 'SET STATEMENT %'
+              AND DIGEST_TEXT NOT LIKE 'SELECT VERSION ( )%'
+              AND DIGEST_TEXT NOT LIKE 'SELECT @@%'
+            ORDER BY #{order_clause}
+            LIMIT #{limit}
+          SQL
+        end
+
+        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
+
+          {
+            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
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/analysis/server_overview.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Analysis
+      # Collects a dashboard-worthy snapshot of server state by combining
+      # SHOW GLOBAL STATUS, SHOW GLOBAL VARIABLES, and SELECT VERSION().
+      # Computes derived metrics (uptime formatting, connection usage
+      # percentage, buffer pool hit rate, tmp-disk percentage, QPS).
+      #
+      # Returns a nested hash with four top-level sections: server,
+      # connections, innodb, queries. Errors propagate; the caller
+      # decides how to render failure.
+      class ServerOverview
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def call
+          status = load_status
+          vars = load_variables
+          version = @connection.select_value("SELECT VERSION()")
+
+          uptime_seconds = status["Uptime"].to_i
+          {
+            server: server_block(version, uptime_seconds),
+            connections: connections_block(status, vars),
+            innodb: innodb_block(status, vars),
+            queries: queries_block(status, uptime_seconds),
+          }
+        end
+
+        private
+
+        def load_status
+          result = @connection.exec_query("SHOW GLOBAL STATUS")
+          result.to_hashes.each_with_object({}) do |row, acc|
+            name = (row["Variable_name"] || row["variable_name"]).to_s
+            value = (row["Value"] || row["value"]).to_s
+            acc[name] = value
+          end
+        end
+
+        def load_variables
+          result = @connection.exec_query("SHOW GLOBAL VARIABLES")
+          result.to_hashes.each_with_object({}) do |row, acc|
+            name = (row["Variable_name"] || row["variable_name"]).to_s
+            value = (row["Value"] || row["value"]).to_s
+            acc[name] = value
+          end
+        end
+
+        def server_block(version, uptime_seconds)
+          days = uptime_seconds / 86_400
+          hours = (uptime_seconds % 86_400) / 3600
+          minutes = (uptime_seconds % 3600) / 60
+
+          {
+            version: version,
+            uptime: "#{days}d #{hours}h #{minutes}m",
+            uptime_seconds: uptime_seconds,
+          }
+        end
+
+        def connections_block(status, vars)
+          max_conn = vars["max_connections"].to_i
+          current_conn = status["Threads_connected"].to_i
+          usage_pct = max_conn.positive? ? ((current_conn.to_f / max_conn) * 100).round(1) : 0
+
+          {
+            max: max_conn,
+            current: current_conn,
+            usage_pct: usage_pct,
+            threads_running: status["Threads_running"].to_i,
+            threads_cached: status["Threads_cached"].to_i,
+            threads_created: status["Threads_created"].to_i,
+            aborted_connects: status["Aborted_connects"].to_i,
+            aborted_clients: status["Aborted_clients"].to_i,
+            max_used: status["Max_used_connections"].to_i,
+          }
+        end
+
+        def innodb_block(status, vars)
+          buffer_pool_bytes = vars["innodb_buffer_pool_size"].to_i
+          buffer_pool_mb = (buffer_pool_bytes / 1024.0 / 1024.0).round(1)
+
+          reads = status["Innodb_buffer_pool_read_requests"].to_f
+          disk_reads = status["Innodb_buffer_pool_reads"].to_f
+          hit_rate = reads.positive? ? (((reads - disk_reads) / reads) * 100).round(2) : 0
+
+          {
+            buffer_pool_mb: buffer_pool_mb,
+            buffer_pool_hit_rate: hit_rate,
+            buffer_pool_pages_dirty: status["Innodb_buffer_pool_pages_dirty"].to_i,
+            buffer_pool_pages_free: status["Innodb_buffer_pool_pages_free"].to_i,
+            buffer_pool_pages_total: status["Innodb_buffer_pool_pages_total"].to_i,
+            row_lock_waits: status["Innodb_row_lock_waits"].to_i,
+            row_lock_time_ms: status["Innodb_row_lock_time"].to_f.round(0),
+          }
+        end
+
+        def queries_block(status, uptime_seconds)
+          tmp_tables = status["Created_tmp_tables"].to_i
+          tmp_disk_tables = status["Created_tmp_disk_tables"].to_i
+          tmp_disk_pct = tmp_tables.positive? ? ((tmp_disk_tables.to_f / tmp_tables) * 100).round(1) : 0
+
+          questions = status["Questions"].to_i
+          qps = uptime_seconds.positive? ? (questions.to_f / uptime_seconds).round(1) : 0
+
+          {
+            questions: questions,
+            qps: qps,
+            slow_queries: status["Slow_queries"].to_i,
+            tmp_tables: tmp_tables,
+            tmp_disk_tables: tmp_disk_tables,
+            tmp_disk_pct: tmp_disk_pct,
+            select_full_join: status["Select_full_join"].to_i,
+            sort_merge_passes: status["Sort_merge_passes"].to_i,
+          }
+        end
+      end
+    end
+  end
+end