mysql_genius-core 0.4.0

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Analysis
+      # Queries information_schema.tables for data/index/fragmentation metrics
+      # per BASE TABLE in the current database, plus an exact SELECT COUNT(*)
+      # for each table. Returns an array of hashes suitable for JSON rendering.
+      #
+      # Takes a Core::Connection. No configuration required — the current
+      # database is read from connection.current_database.
+      class TableSizes
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def call
+          db_name = @connection.current_database
+
+          result = @connection.exec_query(<<~SQL)
+            SELECT
+              table_name,
+              engine,
+              table_collation,
+              auto_increment,
+              update_time,
+              ROUND(data_length / 1024 / 1024, 2) AS data_mb,
+              ROUND(index_length / 1024 / 1024, 2) AS index_mb,
+              ROUND((data_length + index_length) / 1024 / 1024, 2) AS total_mb,
+              ROUND(data_free / 1024 / 1024, 2) AS fragmented_mb
+            FROM information_schema.tables
+            WHERE table_schema = #{@connection.quote(db_name)}
+              AND table_type = 'BASE TABLE'
+            ORDER BY (data_length + index_length) DESC
+          SQL
+
+          result.to_hashes.map do |row|
+            table_name = row["table_name"] || row["TABLE_NAME"]
+            row_count = begin
+              @connection.select_value("SELECT COUNT(*) FROM #{@connection.quote_table_name(table_name)}")
+            rescue StandardError
+              nil
+            end
+
+            total_mb = (row["total_mb"] || 0).to_f
+            fragmented_mb = (row["fragmented_mb"] || 0).to_f
+
+            {
+              table: table_name,
+              rows: row_count,
+              engine: row["engine"] || row["ENGINE"],
+              collation: row["table_collation"] || row["TABLE_COLLATION"],
+              auto_increment: row["auto_increment"] || row["AUTO_INCREMENT"],
+              updated_at: row["update_time"] || row["UPDATE_TIME"],
+              data_mb: (row["data_mb"] || 0).to_f,
+              index_mb: (row["index_mb"] || 0).to_f,
+              total_mb: total_mb,
+              fragmented_mb: fragmented_mb,
+              needs_optimize: total_mb.positive? && fragmented_mb > (total_mb * 0.1),
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Analysis
+      # Queries performance_schema.table_io_waits_summary_by_index_usage
+      # joined with information_schema.tables to find indexes with zero
+      # reads but non-zero row counts in their parent table. Returns hashes
+      # with a ready-to-run DROP INDEX statement per result.
+      #
+      # Skips the PRIMARY index (should never be dropped) and anonymous
+      # rows (where INDEX_NAME IS NULL). Raises if performance_schema is
+      # unavailable.
+      class UnusedIndexes
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def call
+          db_name = @connection.current_database
+
+          result = @connection.exec_query(<<~SQL)
+            SELECT
+              s.OBJECT_SCHEMA AS table_schema,
+              s.OBJECT_NAME AS table_name,
+              s.INDEX_NAME AS index_name,
+              s.COUNT_READ AS `reads`,
+              s.COUNT_WRITE AS `writes`,
+              t.TABLE_ROWS AS table_rows
+            FROM performance_schema.table_io_waits_summary_by_index_usage s
+            JOIN information_schema.tables t
+              ON t.TABLE_SCHEMA = s.OBJECT_SCHEMA AND t.TABLE_NAME = s.OBJECT_NAME
+            WHERE s.OBJECT_SCHEMA = #{@connection.quote(db_name)}
+              AND s.INDEX_NAME IS NOT NULL
+              AND s.INDEX_NAME != 'PRIMARY'
+              AND s.COUNT_READ = 0
+              AND t.TABLE_ROWS > 0
+            ORDER BY s.COUNT_WRITE DESC
+          SQL
+
+          result.to_hashes.map do |row|
+            table = row["table_name"] || row["TABLE_NAME"]
+            index_name = row["index_name"] || row["INDEX_NAME"]
+            {
+              table: table,
+              index_name: index_name,
+              reads: (row["reads"] || row["READS"] || 0).to_i,
+              writes: (row["writes"] || row["WRITES"] || 0).to_i,
+              table_rows: (row["table_rows"] || row["TABLE_ROWS"] || 0).to_i,
+              drop_sql: "ALTER TABLE `#{table}` DROP INDEX `#{index_name}`;",
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/column_definition.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    # Column metadata as returned by Core::Connection#columns_for. Mirrors
+    # the subset of ActiveRecord::ConnectionAdapters::Column that the
+    # analyses and AI services rely on.
+    class ColumnDefinition
+      attr_reader :name, :type, :sql_type, :null, :default, :primary_key
+
+      def initialize(name:, type:, sql_type:, null:, default:, primary_key:)
+        @name = name
+        @type = type
+        @sql_type = sql_type
+        @null = null
+        @default = default
+        @primary_key = primary_key
+        freeze
+      end
+
+      def null?
+        @null
+      end
+
+      def primary_key?
+        @primary_key
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/connection/fake_adapter.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module Connection
+      # In-memory fake connection used by core specs. Supports stubbing
+      # queries by regex and returning canned Core::Result values, plus
+      # stubbing metadata methods. See spec/mysql_genius/core/connection/
+      # fake_adapter_spec.rb for the full surface.
+      class FakeAdapter
+        class NoStubError < StandardError; end
+
+        def initialize
+          @stubs = []
+          @tables = []
+          @columns_for = {}
+          @indexes_for = {}
+          @primary_keys = {}
+          @server_version = "8.0.35"
+          @current_database = "test_db"
+        end
+
+        # ----- stub registration -----
+
+        def stub_query(pattern, columns: [], rows: [], raises: nil)
+          @stubs << { pattern: pattern, columns: columns, rows: rows, raises: raises }
+        end
+
+        def stub_server_version(version)
+          @server_version = version
+        end
+
+        def stub_current_database(name)
+          @current_database = name
+        end
+
+        def stub_tables(list)
+          @tables = list
+        end
+
+        def stub_columns_for(table, columns)
+          @columns_for[table] = columns
+        end
+
+        def stub_indexes_for(table, indexes)
+          @indexes_for[table] = indexes
+        end
+
+        def stub_primary_key(table, name)
+          @primary_keys[table] = name
+        end
+
+        # ----- contract -----
+
+        def exec_query(sql, binds: [])
+          _ = binds
+          stub = @stubs.find { |s| s[:pattern] =~ sql }
+          raise NoStubError, "No stub matched SQL: #{sql}" unless stub
+          raise stub[:raises] if stub[:raises]
+
+          Result.new(columns: stub[:columns], rows: stub[:rows])
+        end
+
+        def select_value(sql)
+          result = exec_query(sql)
+          return if result.empty?
+
+          result.rows.first&.first
+        end
+
+        def server_version
+          ServerInfo.parse(@server_version)
+        end
+
+        attr_reader :current_database
+
+        def quote(value)
+          case value
+          when nil then "NULL"
+          when Integer, Float then value.to_s
+          when String then "'#{value.gsub("'", "''")}'"
+          else "'#{value.to_s.gsub("'", "''")}'"
+          end
+        end
+
+        def quote_table_name(name)
+          "`#{name}`"
+        end
+
+        attr_reader :tables
+
+        def columns_for(table)
+          @columns_for.fetch(table, [])
+        end
+
+        def indexes_for(table)
+          @indexes_for.fetch(table, [])
+        end
+
+        def primary_key(table)
+          @primary_keys[table]
+        end
+
+        def close
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/connection.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    # Connection abstraction. This module is a namespace for concrete
+    # adapters plus documentation of the contract every adapter must
+    # satisfy. It is NOT meant to be included as a mixin; Ruby has no
+    # interface enforcement. Tests exercise the contract via duck-typing
+    # against the real adapters and the FakeAdapter test helper.
+    #
+    # Implementing adapters:
+    #   MysqlGenius::Core::Connection::FakeAdapter        — in this gem, for tests
+    #   MysqlGenius::Core::Connection::ActiveRecordAdapter — in mysql_genius (Rails adapter)
+    #   MysqlGenius::Core::Connection::TrilogyAdapter      — in mysql_genius-desktop (Phase 2)
+    #
+    # Contract (every adapter must implement):
+    #
+    #   #exec_query(sql)                -> Core::Result
+    #   #select_value(sql)              -> Object (first column of first row, or nil)
+    #   #server_version                 -> Core::ServerInfo
+    #   #current_database               -> String
+    #   #quote(value)                   -> String (SQL-escaped value)
+    #   #quote_table_name(name)         -> String (backtick-quoted identifier)
+    #   #tables                         -> Array<String>
+    #   #columns_for(table)             -> Array<Core::ColumnDefinition>
+    #   #indexes_for(table)             -> Array<Core::IndexDefinition>
+    #   #primary_key(table)             -> String or nil
+    #   #close                          -> nil
+    #
+    # Adapters may implement additional methods for efficiency, but any
+    # core code that depends on the connection must only call methods
+    # defined in this contract.
+    module Connection
+    end
+  end
+end

data/lib/mysql_genius/core/execution_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    # Immutable frozen value object returned from Core::QueryRunner#run.
+    # Contains the executed columns and (possibly masked) rows plus runtime
+    # metrics: row count, wall-clock execution time in milliseconds, and a
+    # truncated flag indicating whether the row count reached the applied
+    # LIMIT.
+    #
+    # This is distinct from Core::Result (which models a plain query result
+    # shape) because QueryRunner returns runtime metadata that plain results
+    # don't carry.
+    class ExecutionResult
+      attr_reader :columns, :rows, :row_count, :execution_time_ms, :truncated
+
+      def initialize(columns:, rows:, execution_time_ms:, truncated:)
+        @columns = columns.freeze
+        @rows = rows.freeze
+        @row_count = rows.length
+        @execution_time_ms = execution_time_ms
+        @truncated = truncated
+        freeze
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/index_definition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    # Index metadata as returned by Core::Connection#indexes_for. Mirrors
+    # the subset of ActiveRecord::ConnectionAdapters::IndexDefinition that
+    # the analyses rely on.
+    class IndexDefinition
+      attr_reader :name, :columns, :unique
+
+      def initialize(name:, columns:, unique:)
+        @name = name
+        @columns = columns.freeze
+        @unique = unique
+        freeze
+      end
+
+      def unique?
+        @unique
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/query_explainer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  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 = sql.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
+
+      # 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)
+        return false if sql.match?(TRAILING_KEYWORD_PATTERN)
+        return false if sql.match?(%r{[,=<>!(+\-*/]\s*$})
+
+        sql.match?(/[\w'"`)\]]\s*$/)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  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/mysql_genius/core/query_runner.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "set"
+
+module MysqlGenius
+  module Core
+    # Runs SELECT queries against a Core::Connection with SQL validation,
+    # row-limit application, timeout hints (MySQL or MariaDB flavor), and
+    # column masking. Returns a Core::ExecutionResult on success or raises
+    # a specific error class on failure.
+    #
+    # Does NOT handle audit logging — the caller (Rails concern or future
+    # desktop sidecar) 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",
+      ].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
+
+        limited = SqlValidator.apply_row_limit(sql, row_limit)
+        timed = apply_timeout_hint(limited)
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = begin
+          @connection.exec_query(timed)
+        rescue StandardError => e
+          raise Timeout, e.message if timeout_error?(e)
+
+          raise
+        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)
+        if mariadb?
+          timeout_seconds = @config.query_timeout_ms / 1000
+          "SET STATEMENT max_statement_time=#{timeout_seconds} FOR #{sql}"
+        else
+          sql.sub(/\bSELECT\b/i, "SELECT /*+ MAX_EXECUTION_TIME(#{@config.query_timeout_ms}) */")
+        end
+      end
+
+      def mariadb?
+        @connection.server_version.mariadb?
+      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/mysql_genius/core/result.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  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/mysql_genius/core/server_info.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    # Identifies the database vendor and version. Adapters construct one
+    # from the server's VERSION() output.
+    class ServerInfo
+      attr_reader :vendor, :version
+
+      class << self
+        def parse(version_string)
+          vendor = version_string.to_s.downcase.include?("mariadb") ? :mariadb : :mysql
+          new(vendor: vendor, version: version_string)
+        end
+      end
+
+      # vendor must be :mysql or :mariadb
+      def initialize(vendor:, version:)
+        @vendor = vendor
+        @version = version
+        freeze
+      end
+
+      def mariadb?
+        @vendor == :mariadb
+      end
+
+      def mysql?
+        @vendor == :mysql
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/sql_validator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    module SqlValidator
+      FORBIDDEN_KEYWORDS = ["INSERT", "UPDATE", "DELETE", "DROP", "ALTER", "CREATE", "TRUNCATE", "GRANT", "REVOKE"].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
+
+        return "Access to system schemas is not allowed." if normalized.match?(/\b(information_schema|mysql|performance_schema|sys)\b/i)
+
+        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) { |m| m[0].scan(/`?(\w+)`?/) { |t| tables << t[0] } }
+        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 masked_column?(column_name, patterns)
+        patterns.any? { |pattern| column_name.downcase.include?(pattern) }
+      end
+    end
+  end
+end

data/lib/mysql_genius/core/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MysqlGenius
+  module Core
+    VERSION = "0.4.0"
+  end
+end