mysql_genius 0.1.0

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "mysql_genius"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/config/routes.rb

@@ -0,0 +1,24 @@
+MysqlGenius::Engine.routes.draw do
+  root to: "queries#index"
+
+  get  "columns",      to: "queries#columns"
+  post "execute",      to: "queries#execute"
+  post "explain",      to: "queries#explain"
+  post "suggest",      to: "queries#suggest"
+  post "optimize",     to: "queries#optimize"
+  get  "slow_queries",      to: "queries#slow_queries"
+  get  "duplicate_indexes", to: "queries#duplicate_indexes"
+  get  "table_sizes",      to: "queries#table_sizes"
+  get  "query_stats",      to: "queries#query_stats"
+  get  "unused_indexes",   to: "queries#unused_indexes"
+  get  "server_overview",  to: "queries#server_overview"
+
+  # AI features
+  post "describe_query",   to: "queries#describe_query"
+  post "schema_review",    to: "queries#schema_review"
+  post "rewrite_query",    to: "queries#rewrite_query"
+  post "index_advisor",    to: "queries#index_advisor"
+  post "anomaly_detection", to: "queries#anomaly_detection"
+  post "root_cause",       to: "queries#root_cause"
+  post "migration_risk",   to: "queries#migration_risk"
+end

data/lib/mysql_genius/configuration.rb

@@ -0,0 +1,96 @@
+module MysqlGenius
+  class Configuration
+    # Tables to feature in the visual builder dropdown (array of strings).
+    # When empty, all non-blocked tables are shown.
+    attr_accessor :featured_tables
+
+    # Tables that must never be queried (auth, sessions, internal Rails tables).
+    attr_accessor :blocked_tables
+
+    # Column name patterns to mask with [REDACTED] in query results.
+    # Matched case-insensitively via String#include?.
+    attr_accessor :masked_column_patterns
+
+    # Default columns to check in the visual builder, keyed by table name.
+    # Example: { "users" => %w[id name email created_at] }
+    attr_accessor :default_columns
+
+    # Maximum rows a single query can return.
+    attr_accessor :max_row_limit
+
+    # Default row limit when none is specified.
+    attr_accessor :default_row_limit
+
+    # Query timeout in milliseconds.
+    attr_accessor :query_timeout_ms
+
+    # Proc that receives the controller instance and returns true if the user
+    # is authorized. Example:
+    #   config.authenticate = ->(controller) { controller.current_user&.admin? }
+    attr_accessor :authenticate
+
+    # AI configuration — set to nil to disable AI features entirely.
+    # Must respond to :call(messages:, response_format:, temperature:)
+    # and return a Hash with "choices" in OpenAI-compatible format,
+    # OR set ai_endpoint + ai_api_key for a direct OpenAI-compatible HTTP API.
+    attr_accessor :ai_client
+    attr_accessor :ai_endpoint
+    attr_accessor :ai_api_key
+
+    # AI model name to pass in the request body (e.g. "gpt-4o", "gpt-3.5-turbo").
+    # Optional — if nil, the API default or deployment model is used.
+    attr_accessor :ai_model
+
+    # AI auth style: :bearer (OpenAI, Ollama Cloud) or :api_key (Azure OpenAI).
+    # Defaults to :api_key for backwards compatibility.
+    attr_accessor :ai_auth_style
+
+    # Custom system prompt prepended to AI suggestions. Use this to describe
+    # your domain, table relationships, and naming conventions.
+    attr_accessor :ai_system_context
+
+    # Slow query threshold in milliseconds. Queries slower than this are logged.
+    attr_accessor :slow_query_threshold_ms
+
+    # Redis URL for slow query storage. Set to nil to disable slow query monitoring.
+    attr_accessor :redis_url
+
+    # Logger instance for audit logging. Defaults to a file logger.
+    # Set to nil to disable audit logging.
+    attr_accessor :audit_logger
+
+    # Base controller class for the engine to inherit from.
+    # Set to "ApplicationController" to get current_user and other app helpers.
+    # Defaults to "ActionController::Base".
+    attr_accessor :base_controller
+
+    def initialize
+      @featured_tables = []
+      @blocked_tables = %w[
+        sessions
+        ar_internal_metadata
+        schema_migrations
+      ]
+      @masked_column_patterns = %w[password secret digest token]
+      @default_columns = {}
+      @max_row_limit = 1000
+      @default_row_limit = 25
+      @query_timeout_ms = 30_000
+      @authenticate = ->(controller) { true }
+      @ai_client = nil
+      @ai_endpoint = nil
+      @ai_api_key = nil
+      @ai_model = nil
+      @ai_auth_style = :api_key
+      @ai_system_context = nil
+      @slow_query_threshold_ms = 250
+      @redis_url = nil
+      @audit_logger = nil
+      @base_controller = "ActionController::Base"
+    end
+
+    def ai_enabled?
+      !ai_client.nil? || (!ai_endpoint.nil? && !ai_endpoint.empty? && !ai_api_key.nil? && !ai_api_key.empty?)
+    end
+  end
+end

data/lib/mysql_genius/engine.rb

@@ -0,0 +1,12 @@
+module MysqlGenius
+  class Engine < ::Rails::Engine
+    isolate_namespace MysqlGenius
+
+    config.after_initialize do
+      if MysqlGenius.configuration.redis_url.present?
+        require "mysql_genius/slow_query_monitor"
+        MysqlGenius::SlowQueryMonitor.subscribe!
+      end
+    end
+  end
+end

data/lib/mysql_genius/slow_query_monitor.rb

@@ -0,0 +1,38 @@
+require "json"
+
+module MysqlGenius
+  class SlowQueryMonitor
+    def self.redis_key
+      "mysql_genius:slow_queries"
+    end
+
+    def self.subscribe!
+      ActiveSupport::Notifications.subscribe("sql.active_record") do |_name, start, finish, _id, payload|
+        duration_ms = ((finish - start) * 1000).round(1)
+        sql = payload[:sql].to_s
+        threshold = MysqlGenius.configuration.slow_query_threshold_ms
+
+        next unless duration_ms >= threshold
+        next unless sql.match?(/\ASELECT\b/i)
+        next if sql.include?("SCHEMA")
+        next if sql.include?("EXPLAIN")
+        next if payload[:name] == "SCHEMA"
+
+        begin
+          redis = Redis.new(url: MysqlGenius.configuration.redis_url)
+          entry = {
+            sql: sql.truncate(10_000),
+            duration_ms: duration_ms,
+            timestamp: Time.current.iso8601,
+            name: payload[:name]
+          }.to_json
+
+          redis.lpush(redis_key, entry)
+          redis.ltrim(redis_key, 0, 199)
+        rescue => e
+          Rails.logger.debug("[mysql_genius] Slow query logger error: #{e.message}") if defined?(Rails)
+        end
+      end
+    end
+  end
+end

data/lib/mysql_genius/sql_validator.rb

@@ -0,0 +1,55 @@
+module MysqlGenius
+  module SqlValidator
+    FORBIDDEN_KEYWORDS = %w[INSERT UPDATE DELETE DROP ALTER CREATE TRUNCATE GRANT REVOKE].freeze
+
+    module_function
+
+    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

data/lib/mysql_genius/version.rb

@@ -0,0 +1,3 @@
+module MysqlGenius
+  VERSION = "0.1.0"
+end

data/lib/mysql_genius.rb

@@ -0,0 +1,23 @@
+require "mysql_genius/version"
+require "mysql_genius/configuration"
+require "mysql_genius/sql_validator"
+
+module MysqlGenius
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require "mysql_genius/engine" if defined?(Rails)

data/mysql_genius.gemspec

@@ -0,0 +1,34 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "mysql_genius/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "mysql_genius"
+  spec.version       = MysqlGenius::VERSION
+  spec.authors       = ["Antarr Byrd"]
+  spec.email         = ["antarr.t.byrd@uth.tmc.edu"]
+
+  spec.summary       = "A MySQL performance dashboard and query explorer for Rails — like PgHero, but for MySQL."
+  spec.description   = "MysqlGenius gives Rails apps a mountable admin dashboard for MySQL databases. " \
+                        "Includes a safe SQL query explorer with visual builder, EXPLAIN analysis, " \
+                        "slow query monitoring, audit logging, and optional AI-powered query suggestions and optimization."
+  spec.homepage      = "https://github.com/antarr/mysql_genius"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "railties", ">= 5.2"
+  spec.add_dependency "activerecord", ">= 5.2"
+
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: mysql_genius
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Antarr Byrd
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+description: MysqlGenius gives Rails apps a mountable admin dashboard for MySQL databases.
+  Includes a safe SQL query explorer with visual builder, EXPLAIN analysis, slow query
+  monitoring, audit logging, and optional AI-powered query suggestions and optimization.
+email:
+- antarr.t.byrd@uth.tmc.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/concerns/mysql_genius/ai_features.rb
+- app/controllers/concerns/mysql_genius/database_analysis.rb
+- app/controllers/concerns/mysql_genius/query_execution.rb
+- app/controllers/mysql_genius/base_controller.rb
+- app/controllers/mysql_genius/queries_controller.rb
+- app/services/mysql_genius/ai_client.rb
+- app/services/mysql_genius/ai_optimization_service.rb
+- app/services/mysql_genius/ai_suggestion_service.rb
+- app/views/layouts/mysql_genius/application.html.erb
+- app/views/mysql_genius/queries/_shared_results.html.erb
+- app/views/mysql_genius/queries/_tab_ai_tools.html.erb
+- app/views/mysql_genius/queries/_tab_duplicate_indexes.html.erb
+- app/views/mysql_genius/queries/_tab_query_stats.html.erb
+- app/views/mysql_genius/queries/_tab_server.html.erb
+- app/views/mysql_genius/queries/_tab_slow_queries.html.erb
+- app/views/mysql_genius/queries/_tab_sql_query.html.erb
+- app/views/mysql_genius/queries/_tab_table_sizes.html.erb
+- app/views/mysql_genius/queries/_tab_unused_indexes.html.erb
+- app/views/mysql_genius/queries/_tab_visual_builder.html.erb
+- app/views/mysql_genius/queries/index.html.erb
+- bin/console
+- bin/setup
+- config/routes.rb
+- docs/screenshots/ai_tools.png
+- docs/screenshots/duplicate_indexes.png
+- docs/screenshots/query_stats.png
+- docs/screenshots/server.png
+- docs/screenshots/sql_query.png
+- docs/screenshots/table_sizes.png
+- docs/screenshots/visual_builder.png
+- lib/mysql_genius.rb
+- lib/mysql_genius/configuration.rb
+- lib/mysql_genius/engine.rb
+- lib/mysql_genius/slow_query_monitor.rb
+- lib/mysql_genius/sql_validator.rb
+- lib/mysql_genius/version.rb
+- mysql_genius.gemspec
+homepage: https://github.com/antarr/mysql_genius
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/antarr/mysql_genius
+  source_code_uri: https://github.com/antarr/mysql_genius
+  changelog_uri: https://github.com/antarr/mysql_genius/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: A MySQL performance dashboard and query explorer for Rails — like PgHero,
+  but for MySQL.
+test_files: []