sql_genius 0.9.0

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  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/sql_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)
+          if server_version.postgresql?
+            %("#{name.to_s.gsub('"', '""')}")
+          else
+            "`#{name}`"
+          end
+        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/sql_genius/core/connection.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  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:
+    #   SqlGenius::Core::Connection::FakeAdapter         — used by tests
+    #   SqlGenius::Core::Connection::ActiveRecordAdapter — wraps ActiveRecord::Base.connection
+    #
+    # 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 (dialect-quoted identifier:
+    #                                       backticks for MySQL/MariaDB,
+    #                                       double-quotes for PostgreSQL)
+    #   #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/sql_genius/core/execution_result.rb

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

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

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module QueryBuilders
+      # MySQL / MariaDB query builder. Contains all SQL previously embedded
+      # in the Analysis classes prior to PostgreSQL support being added.
+      module Mysql
+        QUERY_STATS_NOISE_FILTERS = <<~SQL
+          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 @@%'
+        SQL
+
+        extend self
+
+        def table_sizes(connection)
+          <<~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(connection.current_database)}
+              AND table_type = 'BASE TABLE'
+            ORDER BY (data_length + index_length) DESC
+          SQL
+        end
+
+        def query_stats(connection, order_clause:, limit:, include_digest:)
+          digest_col = include_digest ? "DIGEST," : ""
+          <<~SQL
+            SELECT
+              #{digest_col}
+              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 #{QUERY_STATS_NOISE_FILTERS.strip}
+            ORDER BY #{order_clause}
+            LIMIT #{limit}
+          SQL
+        end
+
+        def query_stats_order_clause(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 stats_snapshot(connection, limit:)
+          <<~SQL
+            SELECT
+              DIGEST_TEXT,
+              COUNT_STAR,
+              ROUND(SUM_TIMER_WAIT / 1000000000, 1) AS total_time_ms
+            FROM performance_schema.events_statements_summary_by_digest
+            WHERE SCHEMA_NAME = #{connection.quote(connection.current_database)}
+              AND DIGEST_TEXT IS NOT NULL
+              AND #{QUERY_STATS_NOISE_FILTERS.strip}
+            ORDER BY SUM_TIMER_WAIT DESC
+            LIMIT #{limit}
+          SQL
+        end
+
+        def unused_indexes(connection, min_scans: 0)
+          threshold = [min_scans.to_i, 0].max
+          <<~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,
+              NULL AS size_bytes
+            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(connection.current_database)}
+              AND s.INDEX_NAME IS NOT NULL
+              AND s.INDEX_NAME != 'PRIMARY'
+              AND s.COUNT_READ <= #{threshold}
+            ORDER BY s.COUNT_WRITE DESC
+          SQL
+        end
+
+        # MySQL's table_io_waits counters track since server start with no
+        # cheap way to surface that timestamp at query time, so we return nil
+        # and let the dashboard fall back to "since server restart" wording.
+        def stats_reset_at(_connection)
+          nil
+        end
+
+        def drop_index_sql(table:, index_name:)
+          "ALTER TABLE `#{table}` DROP INDEX `#{index_name}`;"
+        end
+
+        def query_history(connection, digest:)
+          quoted_digest = connection.quote(digest)
+          quoted_db = connection.quote(connection.current_database)
+          <<~SQL
+            SELECT DIGEST_TEXT,
+                   COUNT_STAR AS calls,
+                   ROUND(SUM_TIMER_WAIT / 1000000000.0, 2) AS total_time_ms,
+                   ROUND(AVG_TIMER_WAIT / 1000000000.0, 2) AS avg_time_ms,
+                   ROUND(MAX_TIMER_WAIT / 1000000000.0, 2) AS max_time_ms,
+                   SUM_ROWS_EXAMINED AS rows_examined,
+                   SUM_ROWS_SENT AS rows_sent,
+                   FIRST_SEEN,
+                   LAST_SEEN
+            FROM performance_schema.events_statements_summary_by_digest
+            WHERE DIGEST = #{quoted_digest}
+              AND SCHEMA_NAME = #{quoted_db}
+            LIMIT 1
+          SQL
+        end
+
+        def digest_text_lookup(connection, digest:)
+          quoted_digest = connection.quote(digest)
+          <<~SQL
+            SELECT DIGEST_TEXT
+            FROM performance_schema.events_statements_summary_by_digest
+            WHERE DIGEST = #{quoted_digest}
+            LIMIT 1
+          SQL
+        end
+
+        def digest_column_available?(connection)
+          result = connection.exec_query(
+            "SELECT COLUMN_NAME FROM information_schema.COLUMNS " \
+              "WHERE TABLE_SCHEMA = 'performance_schema' " \
+              "AND TABLE_NAME = 'events_statements_summary_by_digest' " \
+              "AND COLUMN_NAME = 'DIGEST'",
+          )
+          !result.rows.empty?
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/query_builders/postgresql.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    module QueryBuilders
+      # PostgreSQL query builder. Produces SQL that returns the same
+      # column-name contract as the MySQL builder so the Analysis classes
+      # can stay dialect-agnostic after picking a builder.
+      #
+      # Caveats:
+      # - query_stats and stats_snapshot require the pg_stat_statements
+      #   extension. If it's not installed, the query will raise; the
+      #   Analysis layer surfaces that failure to the caller exactly as
+      #   it does on MySQL when performance_schema is disabled.
+      # - "engine" / "table_collation" / "auto_increment" / "fragmented_mb"
+      #   columns are emitted as NULL or 0 — PostgreSQL has no direct
+      #   equivalents. The dashboard renders these gracefully.
+      # - PostgreSQL "schema" and MySQL "database" are not equivalent;
+      #   table_sizes filters to the current search_path's first schema
+      #   (typically "public").
+      module Postgresql
+        QUERY_STATS_NOISE_FILTERS = <<~SQL
+          query NOT ILIKE 'EXPLAIN%'
+          AND query NOT ILIKE 'SHOW %'
+          AND query NOT ILIKE 'SET %'
+          AND query NOT ILIKE '%pg_stat_statements%'
+          AND query NOT ILIKE '%pg_catalog%'
+          AND query NOT ILIKE '%information_schema%'
+        SQL
+
+        extend self
+
+        def table_sizes(_connection)
+          <<~SQL
+            SELECT
+              c.relname AS table_name,
+              NULL AS engine,
+              NULL AS table_collation,
+              NULL AS auto_increment,
+              s.last_autoanalyze AS update_time,
+              ROUND((pg_table_size(c.oid))::numeric / 1024 / 1024, 2) AS data_mb,
+              ROUND((pg_indexes_size(c.oid))::numeric / 1024 / 1024, 2) AS index_mb,
+              ROUND((pg_total_relation_size(c.oid))::numeric / 1024 / 1024, 2) AS total_mb,
+              0.0 AS fragmented_mb
+            FROM pg_class c
+            JOIN pg_namespace n ON n.oid = c.relnamespace
+            LEFT JOIN pg_stat_user_tables s ON s.relid = c.oid
+            WHERE c.relkind = 'r'
+              AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+              AND n.nspname NOT LIKE 'pg_temp_%'
+              AND n.nspname NOT LIKE 'pg_toast_temp_%'
+            ORDER BY pg_total_relation_size(c.oid) DESC
+          SQL
+        end
+
+        def query_stats(connection, order_clause:, limit:, include_digest:)
+          _ = include_digest
+          <<~SQL
+            SELECT
+              queryid::text AS "DIGEST",
+              query AS "DIGEST_TEXT",
+              calls AS calls,
+              ROUND(total_exec_time::numeric, 1) AS total_time_ms,
+              ROUND(mean_exec_time::numeric, 1) AS avg_time_ms,
+              ROUND(max_exec_time::numeric, 1) AS max_time_ms,
+              rows AS rows_examined,
+              rows AS rows_sent,
+              0 AS tmp_disk_tables,
+              0 AS sort_rows,
+              NULL AS "FIRST_SEEN",
+              NULL AS "LAST_SEEN"
+            FROM pg_stat_statements s
+            JOIN pg_database d ON d.oid = s.dbid
+            WHERE d.datname = #{connection.quote(connection.current_database)}
+              AND query IS NOT NULL
+              AND #{QUERY_STATS_NOISE_FILTERS.strip}
+            ORDER BY #{order_clause}
+            LIMIT #{limit}
+          SQL
+        end
+
+        def query_stats_order_clause(sort)
+          case sort
+          when "total_time"    then "total_exec_time DESC"
+          when "avg_time"      then "mean_exec_time DESC"
+          when "calls"         then "calls DESC"
+          when "rows_examined" then "rows DESC"
+          else "total_exec_time DESC"
+          end
+        end
+
+        def stats_snapshot(connection, limit:)
+          <<~SQL
+            SELECT
+              query AS "DIGEST_TEXT",
+              calls AS "COUNT_STAR",
+              ROUND(total_exec_time::numeric, 1) AS total_time_ms
+            FROM pg_stat_statements s
+            JOIN pg_database d ON d.oid = s.dbid
+            WHERE d.datname = #{connection.quote(connection.current_database)}
+              AND query IS NOT NULL
+              AND #{QUERY_STATS_NOISE_FILTERS.strip}
+            ORDER BY total_exec_time DESC
+            LIMIT #{limit}
+          SQL
+        end
+
+        def unused_indexes(_connection, min_scans: 0)
+          threshold = [min_scans.to_i, 0].max
+          <<~SQL
+            SELECT
+              s.schemaname AS table_schema,
+              s.relname AS table_name,
+              s.indexrelname AS index_name,
+              s.idx_scan AS reads,
+              s.idx_tup_read AS writes,
+              c.reltuples::bigint AS table_rows,
+              pg_relation_size(s.indexrelid)::bigint AS size_bytes
+            FROM pg_stat_user_indexes s
+            JOIN pg_index i ON i.indexrelid = s.indexrelid
+            JOIN pg_class c ON c.oid = s.relid
+            WHERE NOT i.indisprimary
+              AND NOT i.indisunique
+              AND s.idx_scan <= #{threshold}
+            ORDER BY pg_relation_size(s.indexrelid) DESC, s.indexrelname ASC
+          SQL
+        end
+
+        # Last time pg_stat_database counters (which back pg_stat_user_indexes,
+        # pg_stat_user_tables, etc.) were reset for the current database.
+        # Surfacing this lets the dashboard distinguish "this index is unused"
+        # from "stats were reset five minutes ago and nothing has run yet".
+        def stats_reset_at(connection)
+          connection.select_value(
+            "SELECT stats_reset FROM pg_stat_database " \
+              "WHERE datname = #{connection.quote(connection.current_database)}",
+          )
+        rescue StandardError
+          nil
+        end
+
+        def drop_index_sql(table:, index_name:)
+          _ = table
+          %(DROP INDEX IF EXISTS "#{index_name.to_s.gsub('"', '""')}";)
+        end
+
+        def query_history(connection, digest:)
+          quoted_digest = connection.quote(digest)
+          quoted_db = connection.quote(connection.current_database)
+          <<~SQL
+            SELECT query AS "DIGEST_TEXT",
+                   calls AS calls,
+                   ROUND(total_exec_time::numeric, 2) AS total_time_ms,
+                   ROUND(mean_exec_time::numeric, 2) AS avg_time_ms,
+                   ROUND(max_exec_time::numeric, 2) AS max_time_ms,
+                   rows AS rows_examined,
+                   rows AS rows_sent,
+                   NULL AS "FIRST_SEEN",
+                   NULL AS "LAST_SEEN"
+            FROM pg_stat_statements s
+            JOIN pg_database d ON d.oid = s.dbid
+            WHERE queryid::text = #{quoted_digest}
+              AND d.datname = #{quoted_db}
+            LIMIT 1
+          SQL
+        end
+
+        def digest_text_lookup(connection, digest:)
+          quoted_digest = connection.quote(digest)
+          <<~SQL
+            SELECT query
+            FROM pg_stat_statements
+            WHERE queryid::text = #{quoted_digest}
+            LIMIT 1
+          SQL
+        end
+
+        def digest_column_available?(_connection)
+          # pg_stat_statements always exposes queryid; treat as a stable digest.
+          true
+        end
+      end
+    end
+  end
+end

data/lib/sql_genius/core/query_builders.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SqlGenius
+  module Core
+    # Factory for dialect-specific SQL query builders used by the analysis
+    # classes. Each builder is a stateless module exposing class methods
+    # that return raw SQL strings; the analysis class is responsible for
+    # executing them and mapping result rows into output hashes.
+    #
+    # Builders intentionally output a stable column-name contract so that
+    # downstream transformation logic doesn't need to know which dialect
+    # produced the rows. See QueryBuilders::Mysql and ::Postgresql.
+    module QueryBuilders
+      extend self
+
+      def for(connection)
+        case connection.server_version.dialect
+        when :postgresql then Postgresql
+        else Mysql
+        end
+      end
+    end
+  end
+end
+
+require "sql_genius/core/query_builders/mysql"
+require "sql_genius/core/query_builders/postgresql"