sql_genius 0.9.0

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

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Dashboard snapshot of server state. Dispatches to a dialect-specific
+      # implementation that produces a uniform nested hash with four
+      # top-level sections: server, connections, innodb, queries.
+      #
+      # On PostgreSQL the `innodb` section is populated with the closest
+      # equivalents (shared_buffers as buffer pool size, blks_hit/blks_read
+      # ratio as buffer pool hit rate). Lock-related fields fall back to 0
+      # since there is no direct equivalent of InnoDB row lock waits.
+      class ServerOverview
+        def initialize(connection)
+          @connection = connection
+        end
+
+        def call
+          impl_for(@connection).call
+        end
+
+        private
+
+        def impl_for(connection)
+          if connection.server_version.postgresql?
+            Postgresql.new(connection)
+          else
+            Mysql.new(connection)
+          end
+        end
+
+        # MySQL / MariaDB implementation. Combines SHOW GLOBAL STATUS, SHOW
+        # GLOBAL VARIABLES, and SELECT VERSION() into the dashboard hash.
+        class Mysql
+          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
+
+        # PostgreSQL implementation. Reads connection/database stats from
+        # pg_stat_activity and pg_stat_database; reads tunable settings via
+        # pg_settings; populates the `innodb` block with shared_buffers and
+        # the buffer cache hit rate so the existing UI continues to render.
+        class Postgresql
+          def initialize(connection)
+            @connection = connection
+          end
+
+          def call
+            version = @connection.select_value("SELECT version()").to_s
+            uptime_seconds = @connection.select_value(
+              "SELECT EXTRACT(EPOCH FROM (now() - pg_postmaster_start_time()))::bigint",
+            ).to_i
+
+            {
+              server: server_block(version, uptime_seconds),
+              connections: connections_block,
+              innodb: innodb_block,
+              queries: queries_block(uptime_seconds),
+            }
+          end
+
+          private
+
+          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
+            max_conn = setting_int("max_connections")
+            current_conn = @connection.select_value("SELECT count(*) FROM pg_stat_activity").to_i
+            running = @connection.select_value(
+              "SELECT count(*) FROM pg_stat_activity WHERE state = 'active'",
+            ).to_i
+            usage_pct = max_conn.positive? ? ((current_conn.to_f / max_conn) * 100).round(1) : 0
+
+            # PostgreSQL doesn't track aborted-connect counts the way MySQL
+            # does, and pg_stat_database.xact_rollback (rolled-back
+            # transactions) is a different concept — surface it on the
+            # PG-specific path elsewhere if needed, rather than mislabeling
+            # it as "Aborted Clients" here.
+            {
+              max: max_conn,
+              current: current_conn,
+              usage_pct: usage_pct,
+              threads_running: running,
+              threads_cached: 0,
+              threads_created: 0,
+              aborted_connects: 0,
+              aborted_clients: 0,
+              max_used: 0,
+            }
+          end
+
+          def innodb_block
+            buffer_pool_bytes = setting_bytes("shared_buffers")
+            buffer_pool_mb = (buffer_pool_bytes / 1024.0 / 1024.0).round(1)
+
+            db_stats = current_db_stats
+            reads = db_stats[:blks_hit].to_f + db_stats[:blks_read].to_f
+            hit_rate = reads.positive? ? ((db_stats[:blks_hit].to_f / reads) * 100).round(2) : 0
+
+            {
+              buffer_pool_mb: buffer_pool_mb,
+              buffer_pool_hit_rate: hit_rate,
+              buffer_pool_pages_dirty: 0,
+              buffer_pool_pages_free: 0,
+              buffer_pool_pages_total: 0,
+              row_lock_waits: db_stats[:deadlocks],
+              row_lock_time_ms: 0,
+            }
+          end
+
+          def queries_block(uptime_seconds)
+            db_stats = current_db_stats
+            questions = db_stats[:xact_commit].to_i + db_stats[:xact_rollback].to_i
+            qps = uptime_seconds.positive? ? (questions.to_f / uptime_seconds).round(1) : 0
+            # PG's `temp_files` is a single count of files written when sorts/
+            # hashes spilled out of work_mem. Surface it on both sides of the
+            # fraction with a 0% ratio so the dashboard doesn't flag a red
+            # "100% spilled to disk" badge that the metric doesn't actually
+            # mean on PostgreSQL.
+            temp_files = db_stats[:temp_files]
+
+            {
+              questions: questions,
+              qps: qps,
+              slow_queries: 0,
+              tmp_tables: temp_files,
+              tmp_disk_tables: temp_files,
+              tmp_disk_pct: 0,
+              select_full_join: 0,
+              sort_merge_passes: 0,
+            }
+          end
+
+          def current_db_stats
+            @current_db_stats ||= begin
+              result = @connection.exec_query(<<~SQL)
+                SELECT
+                  COALESCE(xact_commit, 0) AS xact_commit,
+                  COALESCE(xact_rollback, 0) AS xact_rollback,
+                  COALESCE(blks_read, 0) AS blks_read,
+                  COALESCE(blks_hit, 0) AS blks_hit,
+                  COALESCE(temp_files, 0) AS temp_files,
+                  COALESCE(deadlocks, 0) AS deadlocks
+                FROM pg_stat_database
+                WHERE datname = #{@connection.quote(@connection.current_database)}
+              SQL
+              row = result.to_hashes.first || {}
+              {
+                xact_commit: row["xact_commit"].to_i,
+                xact_rollback: row["xact_rollback"].to_i,
+                blks_read: row["blks_read"].to_i,
+                blks_hit: row["blks_hit"].to_i,
+                temp_files: row["temp_files"].to_i,
+                deadlocks: row["deadlocks"].to_i,
+              }
+            end
+          end
+
+          def setting_int(name)
+            @connection.select_value(
+              "SELECT setting FROM pg_settings WHERE name = #{@connection.quote(name)}",
+            ).to_i
+          end
+
+          # shared_buffers / work_mem etc. report via current_setting() with
+          # their configured unit suffix (e.g. "128MB"). pg_size_bytes()
+          # resolves that to a raw byte count. Available since PG 9.6.
+          def setting_bytes(name)
+            @connection.select_value(
+              "SELECT pg_size_bytes(current_setting(#{@connection.quote(name)}))",
+            ).to_i
+          rescue StandardError
+            0
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Background sampler that periodically queries performance_schema for the
+      # top 50 digests by SUM_TIMER_WAIT, computes per-interval deltas, and
+      # records snapshots into a StatsHistory ring buffer.
+      #
+      # The +connection_provider+ is a callable (lambda/proc) that returns a
+      # Core::Connection on each invocation. This allows each adapter to supply
+      # its own connection strategy:
+      #
+      #   Rails:   -> { ActiveRecordAdapter.new(ActiveRecord::Base.connection) }
+      #   Desktop: -> { session.checkout { |c| c } }
+      class StatsCollector
+        DEFAULT_INTERVAL = 60
+        STOP_JOIN_TIMEOUT = 5
+        TOP_N = 50
+
+        def initialize(connection_provider:, history:, interval: DEFAULT_INTERVAL)
+          @connection_provider = connection_provider
+          @history = history
+          @interval = interval
+          @mutex = Mutex.new
+          @cv = ConditionVariable.new
+          @stop_signal = false
+          @running = false
+          @thread = nil
+          @previous = {}
+        end
+
+        def start
+          return self if @running
+
+          @stop_signal = false
+          @running = true
+          @thread = Thread.new { run_loop }
+          self
+        end
+
+        def stop
+          @mutex.synchronize do
+            @stop_signal = true
+            @cv.signal
+          end
+          @thread&.join(STOP_JOIN_TIMEOUT)
+          @thread = nil
+        end
+
+        def running?
+          @running
+        end
+
+        private
+
+        def run_loop
+          loop do
+            tick
+            break if wait_or_stop(@interval)
+          end
+        rescue StandardError => e
+          warn("[SqlGenius] StatsCollector stopped: #{e.message}")
+        ensure
+          @running = false
+        end
+
+        def tick
+          connection = @connection_provider.call
+          result = connection.exec_query(build_sql(connection))
+          current = {}
+
+          result.to_hashes.each do |row|
+            digest_text = (row["DIGEST_TEXT"] || row["digest_text"]).to_s
+            next if digest_text.empty?
+
+            calls = (row["COUNT_STAR"] || row["count_star"]).to_i
+            total_time_ms = (row["total_time_ms"] || row["TOTAL_TIME_MS"] || 0).to_f
+
+            current[digest_text] = { calls: calls, total_time_ms: total_time_ms }
+
+            next unless @previous.key?(digest_text)
+
+            record_delta(digest_text, calls, total_time_ms)
+          end
+
+          @previous = current
+        end
+
+        def record_delta(digest_text, calls, total_time_ms)
+          prev = @previous[digest_text]
+          delta_calls = [calls - prev[:calls], 0].max
+          delta_total_ms = [(total_time_ms - prev[:total_time_ms]).round(1), 0.0].max
+
+          @history.record(digest_text, {
+            timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            calls: delta_calls,
+            total_time_ms: delta_total_ms,
+            avg_time_ms: delta_calls.positive? ? (delta_total_ms / delta_calls).round(1) : 0.0,
+          })
+        end
+
+        def build_sql(connection)
+          QueryBuilders.for(connection).stats_snapshot(connection, limit: TOP_N)
+        end
+
+        def wait_or_stop(seconds)
+          @mutex.synchronize do
+            return true if @stop_signal
+
+            @cv.wait(@mutex, seconds)
+            @stop_signal
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Thread-safe in-memory ring buffer that stores per-digest query stats
+      # snapshots. Each digest key maps to an array of snapshots capped at
+      # +max_samples+. Oldest entries are dropped when the cap is reached.
+      class StatsHistory
+        DEFAULT_MAX_SAMPLES = 1440
+
+        def initialize(max_samples: DEFAULT_MAX_SAMPLES)
+          @max_samples = max_samples
+          @mutex = Mutex.new
+          @data = {}
+        end
+
+        def record(digest_text, snapshot)
+          @mutex.synchronize do
+            buf = (@data[digest_text] ||= [])
+            buf << snapshot
+            buf.shift if buf.length > @max_samples
+          end
+        end
+
+        def series_for(digest_text)
+          @mutex.synchronize do
+            (@data[digest_text] || []).dup
+          end
+        end
+
+        def digests
+          @mutex.synchronize { @data.keys.dup }
+        end
+
+        def clear
+          @mutex.synchronize { @data.clear }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Returns size/fragmentation metrics for each user table in the current
+      # database, plus an exact SELECT COUNT(*) for each table. Delegates SQL
+      # generation to the dialect-appropriate QueryBuilder so the same class
+      # works against MySQL/MariaDB (information_schema.tables) and PostgreSQL
+      # (pg_class + pg_total_relation_size).
+      #
+      # Takes a Core::Connection. Returns an array of hashes suitable for
+      # JSON rendering.
+      class TableSizes
+        def initialize(connection)
+          @connection = connection
+          @builder = QueryBuilders.for(connection)
+        end
+
+        def call
+          result = @connection.exec_query(@builder.table_sizes(@connection))
+
+          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/sql_genius/core/analysis/unused_indexes.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module Analysis
+      # Indexes whose scan count is at or below `min_scans` (default 0 — never
+      # scanned since the underlying stats source was last reset). On MySQL this
+      # reads performance_schema.table_io_waits_summary_by_index_usage; on
+      # PostgreSQL it reads pg_stat_user_indexes plus pg_relation_size for the
+      # index byte size.
+      #
+      # Returns a Result with:
+      #   indexes        — Array of per-index hashes (sorted by size DESC on PG,
+      #                    by write count DESC on MySQL); each carries a dialect-
+      #                    appropriate `drop_sql` and a `size_bytes` value (nil
+      #                    on MySQL where individual index sizes aren't cheap).
+      #   stats_reset_at — Time the underlying stats source was last reset
+      #                    (PG only — pg_stat_database.stats_reset; nil on MySQL).
+      #   min_scans      — The scan threshold used for this call, echoed back so
+      #                    callers can display "indexes with ≤ N scans".
+      #
+      # Skips primary key indexes on both dialects, plus unique indexes (which
+      # are usually backing a constraint the application depends on). Raises if
+      # the underlying stats source is unavailable.
+      class UnusedIndexes
+        Result = Struct.new(:indexes, :stats_reset_at, :min_scans, keyword_init: true)
+
+        def initialize(connection, min_scans: 0)
+          @connection = connection
+          @builder = QueryBuilders.for(connection)
+          @min_scans = [min_scans.to_i, 0].max
+        end
+
+        def call
+          rows = @connection.exec_query(@builder.unused_indexes(@connection, min_scans: @min_scans)).to_hashes
+          Result.new(
+            indexes: rows.map { |row| transform(row) },
+            stats_reset_at: @builder.stats_reset_at(@connection),
+            min_scans: @min_scans,
+          )
+        end
+
+        private
+
+        def transform(row)
+          table = row["table_name"] || row["TABLE_NAME"]
+          index_name = row["index_name"] || row["INDEX_NAME"]
+          size_bytes = row["size_bytes"] || row["SIZE_BYTES"]
+          {
+            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,
+            size_bytes: size_bytes&.to_i,
+            drop_sql: @builder.drop_index_sql(table: table, index_name: index_name),
+          }
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/column_definition.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  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/sql_genius/core/connection/active_record_adapter.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "sql_genius/core"
+
+module SqlGenius
+  module Core
+    module Connection
+      # Wraps an ActiveRecord::Base.connection and implements the
+      # Core::Connection contract.
+      class ActiveRecordAdapter
+        def initialize(ar_connection)
+          @ar = ar_connection
+        end
+
+        def exec_query(sql, binds: [])
+          _ = binds
+          ar_result = @ar.exec_query(sql)
+          Core::Result.new(columns: ar_result.columns, rows: ar_result.rows)
+        end
+
+        def select_value(sql)
+          @ar.select_value(sql)
+        end
+
+        def server_version
+          @server_version ||= Core::ServerInfo.parse(@ar.select_value("SELECT VERSION()").to_s)
+        end
+
+        def current_database
+          @ar.current_database
+        end
+
+        def quote(value)
+          @ar.quote(value)
+        end
+
+        def quote_table_name(name)
+          @ar.quote_table_name(name)
+        end
+
+        def tables
+          @ar.tables
+        end
+
+        def columns_for(table)
+          pk = @ar.primary_key(table)
+          @ar.columns(table).map do |c|
+            Core::ColumnDefinition.new(
+              name: c.name,
+              type: c.type,
+              sql_type: c.sql_type,
+              null: c.null,
+              default: c.default,
+              primary_key: c.name == pk,
+            )
+          end
+        end
+
+        def indexes_for(table)
+          @ar.indexes(table).map do |idx|
+            Core::IndexDefinition.new(name: idx.name, columns: idx.columns, unique: idx.unique)
+          end
+        end
+
+        def primary_key(table)
+          @ar.primary_key(table)
+        end
+
+        def close
+          nil
+        end
+      end
+    end
+  end
+end