mysql_genius 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 95e37df968649185800af1d3500a85a29fcb7b161f4b6fec56e0cb85f1989ddf
+  data.tar.gz: 024d6408ba0792c82692d47fa76daf74ffc9f81ed3340ea0f4bff2dd60494469
+SHA512:
+  metadata.gz: a7935d42e665520dd8f3f3bd8e30c67b196760994522c9eb0ae63e3bc1a1606c0f98b4327392f4e0bc006470315b3a4467f5df583906359def790f9d0d4a7767
+  data.tar.gz: 33c9db66a13de66c1f68f9092834a8bc606dbf584d2cce2c647481155cf3321bcd4addcb6447ee622b2699ea80014ff687084dd03c841816a084a4279032d5e2

data/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["2.7", "3.0", "3.1", "3.2", "3.3"]
+        rails: ["5.2", "6.0", "6.1", "7.0", "7.1", "7.2"]
+        exclude:
+          # Rails 7.0+ requires Ruby 2.7+, but 7.2 requires 3.1+
+          - ruby: "2.7"
+            rails: "7.2"
+          - ruby: "3.0"
+            rails: "7.2"
+          # Rails 5.2 doesn't support Ruby 3.1+
+          - ruby: "3.1"
+            rails: "5.2"
+          - ruby: "3.2"
+            rails: "5.2"
+          - ruby: "3.3"
+            rails: "5.2"
+          # Rails 6.0 doesn't support Ruby 3.2+
+          - ruby: "3.2"
+            rails: "6.0"
+          - ruby: "3.3"
+            rails: "6.0"
+
+    env:
+      RAILS_VERSION: ${{ matrix.rails }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Run specs
+        run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- Visual query builder with column selection, filters, and ordering
+- Safe SQL execution (read-only, blocked tables, masked columns, row limits, timeouts)
+- EXPLAIN analysis
+- AI-powered query suggestions (optional)
+- AI-powered query optimization from EXPLAIN output (optional)
+- Slow query monitoring via Redis
+- Audit logging
+- MariaDB support

data/Gemfile

@@ -0,0 +1,15 @@
+source "https://rubygems.org"
+
+gemspec
+
+if ENV["RAILS_VERSION"]
+  rails_version = ENV["RAILS_VERSION"]
+  gem "railties", "~> #{rails_version}.0"
+  gem "activerecord", "~> #{rails_version}.0"
+  gem "actionpack", "~> #{rails_version}.0"
+end
+
+group :development, :test do
+  gem "rake"
+  gem "rspec", "~> 3.0"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Antarr Byrd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,295 @@
+# MySQLGenius
+
+A MySQL performance dashboard and query explorer for Rails, inspired by [PgHero](https://github.com/ankane/pghero). If you've used PgHero for PostgreSQL and wished something similar existed for MySQL -- this is it, with AI-powered query suggestions and optimization on top.
+
+## Screenshots
+
+### Visual Builder
+Build queries visually -- select tables, pick columns, add type-aware filters, and sort results without writing SQL.
+
+![Visual Builder](docs/screenshots/visual_builder.png)
+
+### SQL Query with AI Assistant
+Write raw SQL or describe what you want in plain English and let the AI generate the query for you.
+
+![SQL Query](docs/screenshots/sql_query.png)
+
+### Duplicate Index Detection
+Find redundant indexes whose columns are a left-prefix of another index, with ready-to-run `DROP INDEX` statements.
+
+![Duplicate Indexes](docs/screenshots/duplicate_indexes.png)
+
+### Table Sizes
+View row counts, data size, index size, fragmentation, and a visual size chart for every table.
+
+![Table Sizes](docs/screenshots/table_sizes.png)
+
+### Query Stats
+Top queries from `performance_schema` sorted by total time, with call counts, avg/max time, and rows examined.
+
+![Query Stats](docs/screenshots/query_stats.png)
+
+### Server Dashboard
+At-a-glance server health: version, connections, InnoDB buffer pool, and query activity with AI-powered diagnostics.
+
+![Server](docs/screenshots/server.png)
+
+### AI Tools
+Schema review that finds anti-patterns -- missing primary keys, nullable foreign keys, inappropriate column types, and more.
+
+![AI Tools](docs/screenshots/ai_tools.png)
+
+## Features
+
+- **Visual Query Builder** -- point-and-click query construction with column selection, type-aware filters, and ordering
+- **Safe SQL Execution** -- read-only enforcement, blocked tables, masked sensitive columns, row limits, query timeouts
+- **EXPLAIN Analysis** -- run EXPLAIN on any query and view the execution plan
+- **AI Query Suggestions** -- describe what you want in plain English, get SQL back (optional, any OpenAI-compatible API)
+- **AI Query Optimization** -- get actionable optimization suggestions from EXPLAIN output (optional)
+- **Slow Query Monitoring** -- captures slow SELECT queries via ActiveSupport notifications and Redis
+- **Duplicate Index Detection** -- finds redundant indexes whose columns are a left-prefix of another index
+- **Table Size Dashboard** -- view row counts, data size, index size, and fragmentation for all tables
+- **Audit Logging** -- logs all query executions, rejections, and errors
+- **MariaDB Support** -- automatically detects MariaDB and uses appropriate timeout syntax
+- **Self-contained UI** -- no external CSS/JS dependencies, works with any Rails layout
+- **Zero jQuery** -- pure vanilla JavaScript frontend
+
+## Requirements
+
+- Rails 5.2+
+- Ruby 2.6+
+- MySQL or MariaDB
+- Redis (optional, for slow query monitoring)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "mysql_genius"
+```
+
+Or from GitHub:
+
+```ruby
+gem "mysql_genius", github: "antarr/mysql_genius"
+```
+
+Then run:
+
+```
+bundle install
+```
+
+## Setup
+
+### 1. Mount the engine
+
+In `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount MysqlGenius::Engine, at: "/mysql_genius"
+end
+```
+
+To restrict access at the route level:
+
+```ruby
+# Using a session constraint
+constraints ->(req) { req.session[:admin] } do
+  mount MysqlGenius::Engine, at: "/mysql_genius"
+end
+
+# Or using Devise
+authenticate :user, ->(u) { u.admin? } do
+  mount MysqlGenius::Engine, at: "/mysql_genius"
+end
+```
+
+### 2. Configure
+
+Create `config/initializers/mysql_genius.rb`:
+
+```ruby
+MysqlGenius.configure do |config|
+  # --- Authentication ---
+  # Lambda that receives the controller instance. Return true to allow access.
+  # Default: allows everyone. Use route constraints for most cases.
+  config.authenticate = ->(controller) { true }
+
+  # To use current_user or other app helpers, inherit from ApplicationController:
+  # config.base_controller = "ApplicationController"
+  # config.authenticate = ->(controller) { controller.current_user&.admin? }
+
+  # --- Tables ---
+  # Tables featured at the top of the visual builder dropdown (optional)
+  config.featured_tables = %w[users posts comments]
+
+  # Tables blocked from querying (defaults: sessions, schema_migrations, ar_internal_metadata)
+  config.blocked_tables += %w[oauth_tokens api_keys]
+
+  # Column patterns to redact with [REDACTED] in results (case-insensitive substring match)
+  config.masked_column_patterns = %w[password secret digest token ssn]
+
+  # Default columns checked in the visual builder per table (optional).
+  # When empty for a table, all columns are checked by default.
+  config.default_columns = {
+    "users" => %w[id name email created_at],
+    "posts" => %w[id title user_id published_at]
+  }
+
+  # --- Query Safety ---
+  config.max_row_limit = 1000       # Hard cap on rows returned
+  config.default_row_limit = 25     # Default when no limit specified
+  config.query_timeout_ms = 30_000  # 30 second timeout (uses MariaDB or MySQL hints)
+
+  # --- Slow Query Monitoring ---
+  # Requires Redis. Set to nil to disable.
+  config.redis_url = ENV["REDIS_URL"].presence || "redis://127.0.0.1:6379/0"
+  config.slow_query_threshold_ms = 250
+
+  # --- Audit Logging ---
+  # Set to nil to disable. Logs query executions, rejections, and errors.
+  config.audit_logger = Logger.new(Rails.root.join("log", "mysql_genius.log"))
+end
+```
+
+### 3. AI Features (optional)
+
+MySQLGenius supports AI-powered query suggestions and optimization via any OpenAI-compatible API, including OpenAI, Azure OpenAI, Ollama Cloud, and local Ollama instances.
+
+```ruby
+MysqlGenius.configure do |config|
+  # --- Option A: OpenAI ---
+  config.ai_endpoint = "https://api.openai.com/v1/chat/completions"
+  config.ai_api_key = ENV["OPENAI_API_KEY"]
+  config.ai_model = "gpt-4o"
+  config.ai_auth_style = :bearer
+
+  # --- Option B: Azure OpenAI ---
+  config.ai_endpoint = ENV["AZURE_OPENAI_ENDPOINT"]  # Your deployment URL
+  config.ai_api_key = ENV["AZURE_OPENAI_API_KEY"]
+  config.ai_auth_style = :api_key                     # Default, uses api-key header
+
+  # --- Option C: Ollama Cloud ---
+  config.ai_endpoint = "https://api.ollama.com/v1/chat/completions"
+  config.ai_api_key = ENV["OLLAMA_API_KEY"]
+  config.ai_model = "gemma3:27b"
+  config.ai_auth_style = :bearer
+
+  # --- Option D: Local Ollama ---
+  config.ai_endpoint = "http://localhost:11434/v1/chat/completions"
+  config.ai_api_key = "ollama"  # Any non-empty string
+  config.ai_model = "llama3"
+  config.ai_auth_style = :bearer
+
+  # --- Option E: Custom client ---
+  # Any callable that accepts messages: and temperature: kwargs
+  # and returns an OpenAI-compatible response hash.
+  config.ai_client = ->(messages:, temperature:) {
+    MyAiService.chat(messages, temperature: temperature)
+  }
+
+  # --- Domain Context ---
+  # Helps the AI understand your schema and generate better queries.
+  config.ai_system_context = <<~CONTEXT
+    This is an e-commerce database.
+    - `users` stores customer accounts. Primary key is `id`.
+    - `orders` tracks purchases. Linked to users via `user_id`.
+    - `products` contains the product catalog.
+    - Soft-deleted records have `deleted_at IS NOT NULL`.
+  CONTEXT
+end
+```
+
+| Option | `ai_auth_style` | `ai_model` | Notes |
+|--------|-----------------|------------|-------|
+| OpenAI | `:bearer` | Required (e.g. `gpt-4o`) | |
+| Azure OpenAI | `:api_key` (default) | Optional (uses deployment default) | |
+| Ollama Cloud | `:bearer` | Required (e.g. `gemma3:27b`) | Follows redirects automatically |
+| Local Ollama | `:bearer` | Required | No API key validation |
+| Custom client | N/A | N/A | You handle everything |
+
+When AI is not configured, the AI Assistant panel and optimization buttons are hidden automatically.
+
+## Usage
+
+Visit `/mysql_genius` in your browser. The dashboard has five tabs:
+
+### Visual Builder
+Select a table, pick columns, add type-aware filters (dates get date pickers, booleans get dropdowns), add sort orders, and run queries -- no SQL knowledge required. The generated SQL is shown and synced with the SQL tab.
+
+### SQL Query
+Write raw SQL directly. The optional AI Assistant lets you describe what you want in plain English and generates a query. AI-generated queries are synced back to the Visual Builder for further refinement.
+
+### Slow Queries
+View slow SELECT queries captured from your application in real time. Each slow query can be:
+- **Explained** -- run EXPLAIN to see the execution plan (bypasses blocked table restrictions)
+- **Used** -- copy to the SQL tab for editing and re-running
+- **Optimized** -- get AI-powered optimization suggestions with specific index and rewrite recommendations
+
+### Duplicate Indexes
+Scans all tables for redundant indexes -- indexes whose columns are a left-prefix of another index on the same table. Shows the `ALTER TABLE ... DROP INDEX` statement for each duplicate, ready to copy and run.
+
+### Table Sizes
+Displays every table sorted by total size, with columns for estimated row count, data size, index size, total size, and fragmented space. Includes a visual size bar for quick comparison.
+
+## Configuration Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `authenticate` | Proc | `->(_) { true }` | Authorization check |
+| `base_controller` | String | `"ActionController::Base"` | Parent controller class |
+| `featured_tables` | Array | `[]` | Tables shown in Featured group |
+| `blocked_tables` | Array | `[sessions, ...]` | Tables that cannot be queried |
+| `masked_column_patterns` | Array | `[password, secret, ...]` | Column patterns to redact |
+| `default_columns` | Hash | `{}` | Default checked columns per table |
+| `max_row_limit` | Integer | `1000` | Maximum rows returned |
+| `default_row_limit` | Integer | `25` | Default row limit |
+| `query_timeout_ms` | Integer | `30000` | Query timeout in ms |
+| `redis_url` | String | `nil` | Redis URL for slow query monitoring |
+| `slow_query_threshold_ms` | Integer | `250` | Slow query threshold |
+| `audit_logger` | Logger | `nil` | Logger for query audit trail |
+| `ai_endpoint` | String | `nil` | AI API endpoint URL |
+| `ai_api_key` | String | `nil` | AI API key |
+| `ai_model` | String | `nil` | AI model name |
+| `ai_auth_style` | Symbol | `:api_key` | `:bearer` or `:api_key` |
+| `ai_client` | Proc | `nil` | Custom AI client callable |
+| `ai_system_context` | String | `nil` | Domain context for AI prompts |
+
+## Compatibility
+
+Tested against:
+
+| Rails | Ruby |
+|-------|------|
+| 5.2   | 2.6, 2.7, 3.0 |
+| 6.0   | 2.6, 2.7, 3.0, 3.1 |
+| 6.1   | 2.6, 2.7, 3.0, 3.1, 3.2, 3.3 |
+| 7.0   | 2.7, 3.0, 3.1, 3.2, 3.3 |
+| 7.1   | 2.7, 3.0, 3.1, 3.2, 3.3 |
+| 7.2   | 3.1, 3.2, 3.3 |
+
+## Development
+
+```
+git clone https://github.com/antarr/mysql_genius.git
+cd mysql_genius
+bin/setup
+bundle exec rspec
+```
+
+To test against a specific Rails version:
+
+```
+RAILS_VERSION=6.1 bundle update && bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/antarr/mysql_genius.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec