mxrb 0.1.0

data/lib/mxrb/oql/sql_server_plan_analyzer.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+
+module Mxrb
+  module Oql
+    # Parses SQL Server SHOWPLAN XML without executing or rewriting the query.
+    # Missing-index entries are optimizer hypotheses, not DDL instructions.
+    class SqlServerPlanAnalyzer # rubocop:disable Metrics/ClassLength
+      LARGE_ROWS = 1_000
+      HIGH_NESTED_ROWS = 10_000
+      MISESTIMATE_RATIO = 10.0
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def analyze(xml)
+        document = REXML::Document.new(xml.to_s)
+        root = document.root
+        raise ArgumentError, 'invalid SQL Server SHOWPLAN XML' unless root&.name == 'ShowPlanXML'
+
+        findings = [*operator_findings(root), *missing_index_findings(root)].freeze
+        statement = elements(root, 'StmtSimple').first
+        runtime = elements(root, 'QueryTimeStats').first
+        PlanReport.new(
+          :sql_server, !runtime.nil?, nil, attribute_number(runtime, 'ElapsedTime'),
+          attribute_number(statement, 'StatementSubTreeCost'), findings, xml.to_s.freeze
+        )
+      rescue REXML::ParseException => e
+        raise ArgumentError, "invalid SQL Server SHOWPLAN XML: #{e.message}"
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      private
+
+      def operator_findings(root)
+        elements(root, 'RelOp').flat_map do |operator|
+          [
+            scan_finding(operator), nested_loop_finding(operator),
+            spill_finding(operator), misestimate_finding(operator)
+          ].compact
+        end
+      end
+
+      def scan_finding(operator)
+        physical = operator.attributes['PhysicalOp'].to_s
+        return unless ['Table Scan', 'Clustered Index Scan'].include?(physical)
+        return unless estimated_rows(operator) >= LARGE_ROWS
+
+        object = operator_object(operator)
+        PlanFinding.new(
+          :sql_server_scan, :warning, physical, object[:relation],
+          "#{physical} processes a large estimated row set.",
+          'Review predicate selectivity and the actual plan; a scan can still be optimal.',
+          operator_metrics(operator).freeze, object[:indexes].freeze
+        )
+      end
+
+      def nested_loop_finding(operator)
+        return unless operator.attributes['PhysicalOp'] == 'Nested Loops'
+        return unless estimated_rows(operator) >= HIGH_NESTED_ROWS
+
+        operator_finding(
+          :sql_server_high_volume_nested_loop, operator,
+          'A nested-loops join processes a high estimated row volume.',
+          'Review indexes on inner join keys and compare hash or merge alternatives in the actual plan.'
+        )
+      end
+
+      def spill_finding(operator)
+        spill = descendants(operator).find do |element|
+          %w[SpillToTempDb SortSpillDetails HashSpillDetails].include?(element.name)
+        end
+        return unless spill
+
+        operator_finding(
+          :sql_server_tempdb_spill, operator,
+          'The actual plan reports a spill to tempdb.',
+          'Reduce intermediate rows and review memory grants, cardinality estimates, sorts, and hashes.'
+        )
+      end
+
+      def misestimate_finding(operator)
+        estimated = estimated_rows(operator)
+        actual = actual_rows(operator)
+        return if estimated.zero? || actual.zero?
+        return unless [estimated, actual].max >= 100 && ratio(estimated, actual) >= MISESTIMATE_RATIO
+
+        operator_finding(
+          :sql_server_cardinality_misestimation, operator,
+          'Estimated and actual operator rows differ by at least 10x.',
+          'Update statistics and inspect parameter sensitivity, predicates, and correlated columns.'
+        )
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def missing_index_findings(root)
+        elements(root, 'MissingIndexGroup').map do |group|
+          index = elements(group, 'MissingIndex').first
+          columns = elements(group, 'Column').map do |column|
+            { name: clean_identifier(column.attributes['Name']),
+              usage: column.parent.attributes['Usage'] }.freeze
+          end
+          relation = qualified_object(index)
+          impact = attribute_number(group, 'Impact')
+          PlanFinding.new(
+            :sql_server_missing_index, :hint, 'MissingIndex', relation,
+            "SQL Server estimates a missing-index impact of #{impact}%.",
+            'Treat this as a hypothesis: compare with existing indexes, write cost, and representative workload.',
+            { impact_percent: impact }.freeze, columns.freeze
+          )
+        end
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      def operator_finding(rule, operator, message, suggestion)
+        object = operator_object(operator)
+        PlanFinding.new(
+          rule, :warning, operator.attributes['PhysicalOp'], object[:relation], message, suggestion,
+          operator_metrics(operator).freeze, object[:indexes].freeze
+        )
+      end
+
+      def operator_object(operator)
+        object = descendants(operator).find { _1.name == 'Object' }
+        return { relation: nil, indexes: [] } unless object
+
+        index = clean_identifier(object.attributes['Index'])
+        {
+          relation: qualified_object(object),
+          indexes: index ? [{ name: index, definition: nil }.freeze] : []
+        }
+      end
+
+      def qualified_object(element)
+        return unless element
+
+        %w[Database Schema Table].filter_map do |name|
+          clean_identifier(element.attributes[name])
+        end.join('.')
+      end
+
+      def clean_identifier(value)
+        text = value.to_s
+        return if text.empty?
+
+        text.delete_prefix('[').delete_suffix(']')
+      end
+
+      def operator_metrics(operator)
+        {
+          estimated_rows: estimated_rows(operator), actual_rows: actual_rows(operator),
+          estimated_cost: attribute_number(operator, 'EstimatedTotalSubtreeCost'),
+          actual_executions: runtime_counters(operator).sum do |counter|
+            attribute_number(counter, 'ActualExecutions')
+          end
+        }
+      end
+
+      def estimated_rows(operator)
+        attribute_number(operator, 'EstimateRows')
+      end
+
+      def actual_rows(operator)
+        runtime_counters(operator).sum { attribute_number(_1, 'ActualRows') }
+      end
+
+      def runtime_counters(operator)
+        descendants(operator).take_while { _1.name != 'RelOp' }
+                             .select { _1.name == 'RunTimeCountersPerThread' }
+      end
+
+      def descendants(element)
+        result = []
+        element.each_recursive { result << _1 }
+        result
+      end
+
+      def elements(element, name)
+        descendants(element).select { _1.name == name }
+      end
+
+      def attribute_number(element, name)
+        element ? element.attributes[name].to_f : 0.0
+      end
+
+      def ratio(left, right)
+        [left, right].max / [left, right].min
+      end
+    end # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/mxrb/oql/sql_server_workload_analyzer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Oql
+    SqlServerWorkloadQuery = Data.define(
+      :query_id, :query, :calls, :total_time_ms, :mean_time_ms, :rows,
+      :logical_reads, :physical_reads, :temp_writes, :io_time_ms, :cache_hit_ratio
+    )
+
+    # Normalizes read-only SQL Server DMV snapshots into the shared workload report.
+    class SqlServerWorkloadAnalyzer
+      def analyze(query_rows:, table_rows:, index_rows:)
+        queries = query_rows.map { query_entry(_1) }.freeze
+        findings = [
+          *queries.filter_map { query_finding(_1) },
+          *table_rows.filter_map { table_finding(_1) },
+          *index_rows.filter_map { index_finding(_1) }
+        ].freeze
+        WorkloadReport.new(:sql_server, queries, table_rows.freeze, index_rows.freeze, findings)
+      end
+
+      private
+
+      def query_entry(row) # rubocop:disable Metrics/AbcSize
+        calls = row['execution_count'].to_i
+        total = row['total_elapsed_time'].to_f / 1_000.0
+        SqlServerWorkloadQuery.new(
+          row['query_hash'], row['query_text'], calls, total,
+          calls.zero? ? 0.0 : total / calls, row['total_rows'].to_i,
+          row['total_logical_reads'].to_i, row['total_physical_reads'].to_i,
+          0, 0.0, cache_ratio(row)
+        )
+      end
+
+      def cache_ratio(row)
+        logical = row['total_logical_reads'].to_i
+        physical = row['total_physical_reads'].to_i
+        return 1.0 if logical.zero?
+
+        (1.0 - physical.to_f / logical).clamp(0.0, 1.0).round(4)
+      end
+
+      def query_finding(query)
+        return unless query.total_time_ms >= 1_000 || query.mean_time_ms >= 100
+
+        WorkloadFinding.new(
+          :sql_server_expensive_query, :warning, query.query_id,
+          'The DMV snapshot reports substantial elapsed time for this query fingerprint.',
+          'Inspect Query Store history and the actual plan for regressions and parameter sensitivity.',
+          query.to_h.freeze
+        )
+      end
+
+      def table_finding(row)
+        scans = row['user_scans'].to_i
+        seeks = row['user_seeks'].to_i
+        return unless scans > seeks && scans >= 100
+
+        WorkloadFinding.new(
+          :sql_server_scan_pressure, :warning, row['relation'],
+          'Index usage DMVs report more scans than seeks.',
+          'Correlate the table with expensive fingerprints before changing indexes.',
+          { user_scans: scans, user_seeks: seeks }.freeze
+        )
+      end
+
+      def index_finding(row)
+        return unless row['user_seeks'].to_i.zero? && row['user_scans'].to_i.zero?
+        return unless row['index_bytes'].to_i >= 1_048_576
+
+        WorkloadFinding.new(
+          :sql_server_unused_large_index, :warning, row['index_name'],
+          'A large index has no seeks or scans in the current DMV window.',
+          'Confirm restart time and representative workload before considering removal.',
+          { index_bytes: row['index_bytes'].to_i }.freeze
+        )
+      end
+    end
+  end
+end

data/lib/mxrb/oql/workload_analyzer.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Mxrb
+  module Oql
+    WorkloadQuery = Data.define(
+      :query_id, :query, :calls, :total_time_ms, :mean_time_ms, :rows,
+      :shared_hits, :shared_reads, :temp_writes, :io_time_ms, :cache_hit_ratio
+    )
+    WorkloadFinding = Data.define(:rule, :severity, :subject, :message, :suggestion, :metrics)
+    WorkloadReport = Data.define(:engine, :queries, :table_stats, :index_stats, :findings) do
+      def clean? = findings.none? { _1.severity == :warning }
+      def warnings? = !clean?
+    end
+
+    # Interprets cumulative PostgreSQL statistics without pretending that one
+    # threshold is universally optimal. Findings retain the measured values so
+    # callers can rank them against their own latency and throughput budgets.
+    class WorkloadAnalyzer # rubocop:disable Metrics/ClassLength
+      TOTAL_TIME_MS = 1_000.0
+      MEAN_TIME_MS = 100.0
+      MIN_BUFFER_BLOCKS = 100
+      MIN_CACHE_HIT_RATIO = 0.90
+      HIGH_ROWS_PER_CALL = 10_000
+      LARGE_UNUSED_INDEX_BYTES = 1_048_576
+      HEAVY_SEQ_ROWS = 100_000
+
+      DEFAULT_THRESHOLDS = {
+        total_time_ms: TOTAL_TIME_MS, mean_time_ms: MEAN_TIME_MS,
+        min_buffer_blocks: MIN_BUFFER_BLOCKS, min_cache_hit_ratio: MIN_CACHE_HIT_RATIO,
+        high_rows_per_call: HIGH_ROWS_PER_CALL,
+        large_unused_index_bytes: LARGE_UNUSED_INDEX_BYTES, heavy_seq_rows: HEAVY_SEQ_ROWS
+      }.freeze
+
+      def initialize(**thresholds)
+        unknown = thresholds.keys - DEFAULT_THRESHOLDS.keys
+        raise ArgumentError, "unknown workload thresholds: #{unknown.join(', ')}" unless unknown.empty?
+
+        @thresholds = DEFAULT_THRESHOLDS.merge(thresholds).freeze
+      end
+
+      def analyze(query_rows:, table_rows:, index_rows:)
+        queries = query_rows.map { query_entry(_1) }.freeze
+        findings = [
+          *queries.flat_map { query_findings(_1) },
+          *table_rows.filter_map { table_finding(_1) },
+          *index_rows.filter_map { index_finding(_1) }
+        ].freeze
+        WorkloadReport.new(:postgresql, queries, table_rows.freeze, index_rows.freeze, findings)
+      end
+
+      private
+
+      def query_entry(row) # rubocop:disable Metrics/AbcSize
+        hits = integer(row['shared_blks_hit'])
+        reads = integer(row['shared_blks_read'])
+        total_blocks = hits + reads
+        ratio = total_blocks.zero? ? 1.0 : hits.to_f / total_blocks
+        WorkloadQuery.new(
+          row['queryid'], row['query'], integer(row['calls']), float(row['total_exec_time']),
+          float(row['mean_exec_time']), integer(row['rows']), hits, reads,
+          integer(row['temp_blks_written']), float(row['blk_read_time']) + float(row['blk_write_time']),
+          ratio.round(4)
+        )
+      end
+
+      def query_findings(entry)
+        [
+          cumulative_time(entry), slow_mean(entry), low_cache_hit(entry),
+          temporary_writes(entry), high_rows(entry)
+        ].compact
+      end
+
+      def cumulative_time(entry)
+        return unless entry.total_time_ms >= threshold(:total_time_ms)
+
+        query_finding(
+          :high_cumulative_time, entry,
+          'This query fingerprint consumes substantial cumulative execution time.',
+          'Prioritize it by total time, then inspect its real plan with db explain --analyze.'
+        )
+      end
+
+      def slow_mean(entry)
+        return unless entry.mean_time_ms >= threshold(:mean_time_ms)
+
+        query_finding(
+          :high_mean_time, entry, 'Mean execution time exceeds 100 ms.',
+          'Inspect plan stability, cardinality estimates, locks, I/O, and returned row volume.'
+        )
+      end
+
+      def low_cache_hit(entry)
+        blocks = entry.shared_hits + entry.shared_reads
+        return unless blocks >= threshold(:min_buffer_blocks) &&
+                      entry.cache_hit_ratio < threshold(:min_cache_hit_ratio)
+
+        query_finding(
+          :low_cache_hit, entry, 'A significant share of shared blocks came from storage.',
+          'Check working-set size, access locality, indexes, and whether the query reads excess rows.'
+        )
+      end
+
+      def temporary_writes(entry)
+        return unless entry.temp_writes.positive?
+
+        query_finding(
+          :temporary_block_writes, entry, 'The query wrote temporary blocks.',
+          'Inspect sorts and hashes, reduce intermediate rows, and review work_mem per workload.'
+        )
+      end
+
+      def high_rows(entry)
+        return if entry.calls.zero? || entry.rows / entry.calls < threshold(:high_rows_per_call)
+
+        query_finding(
+          :high_rows_per_call, entry, 'The query returns or processes many rows per call.',
+          'Project only required columns and rows; consider pagination or a narrower aggregation.'
+        )
+      end
+
+      def query_finding(rule, entry, message, suggestion)
+        WorkloadFinding.new(
+          rule, :warning, entry.query_id, message, suggestion,
+          {
+            calls: entry.calls, total_time_ms: entry.total_time_ms,
+            mean_time_ms: entry.mean_time_ms, rows: entry.rows,
+            cache_hit_ratio: entry.cache_hit_ratio, temp_writes: entry.temp_writes,
+            io_time_ms: entry.io_time_ms
+          }.freeze
+        )
+      end
+
+      def table_finding(row) # rubocop:disable Metrics/MethodLength
+        seq_rows = integer(row['seq_tup_read'])
+        seq_scans = integer(row['seq_scan'])
+        index_scans = integer(row['idx_scan'])
+        return unless seq_rows >= threshold(:heavy_seq_rows) && seq_scans > index_scans
+
+        WorkloadFinding.new(
+          :table_sequential_pressure, :warning, qualified(row, 'relname'),
+          'Cumulative table statistics show more sequential than index scans.',
+          'Inspect the highest-cost query fingerprints before adding or changing indexes.',
+          { seq_scan: seq_scans, seq_tup_read: seq_rows, idx_scan: index_scans,
+            live_rows: integer(row['n_live_tup']) }.freeze
+        )
+      end
+
+      def index_finding(row)
+        return if truthy?(row['indisunique']) || truthy?(row['indisprimary'])
+
+        size = integer(row['index_bytes'])
+        return unless integer(row['idx_scan']).zero? && size >= threshold(:large_unused_index_bytes)
+
+        WorkloadFinding.new(
+          :unused_large_index, :warning, qualified(row, 'indexrelname'),
+          'A non-unique index occupies at least 1 MiB but has no scans in the current statistics window.',
+          'Confirm the statistics reset time and production workload before considering removal.',
+          { idx_scan: 0, index_bytes: size, idx_tup_read: integer(row['idx_tup_read']) }.freeze
+        )
+      end
+
+      def qualified(row, name_key)
+        [row['schemaname'], row[name_key]].compact.join('.')
+      end
+
+      def truthy?(value)
+        %w[t true 1].include?(value.to_s.downcase)
+      end
+
+      def integer(value) = value.to_i
+      def float(value) = value.to_f
+      def threshold(name) = @thresholds.fetch(name)
+    end # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/mxrb/oql/workload_baseline.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Mxrb
+  module Oql
+    WorkloadDelta = Data.define(:query_id, :metric, :before, :after, :change_percent)
+    WorkloadComparison = Data.define(:deltas) do
+      def regressions = deltas.select { _1.change_percent.positive? }
+      def improvements = deltas.select { _1.change_percent.negative? }
+    end
+
+    # Serializable workload snapshot and deterministic regression comparison.
+    module WorkloadBaseline
+      module_function
+
+      METRICS = %w[total_time_ms mean_time_ms io_time_ms temp_writes rows].freeze
+
+      def dump(report)
+        JSON.pretty_generate(
+          version: 1, engine: report.engine, captured_at: Time.now.utc.iso8601,
+          queries: report.queries.to_h { [_1.query_id.to_s, _1.to_h] }
+        ) << "\n"
+      end
+
+      def load(source)
+        payload = source.is_a?(Hash) ? source : JSON.parse(File.read(source))
+        raise ArgumentError, 'unsupported workload baseline version' unless payload['version'] == 1
+
+        payload
+      rescue JSON::ParserError, Errno::ENOENT => e
+        raise ArgumentError, "cannot read workload baseline: #{e.message}"
+      end
+
+      def compare(report, baseline)
+        previous = load(baseline).fetch('queries')
+        deltas = report.queries.flat_map { query_deltas(_1, previous[_1.query_id.to_s]) }
+        WorkloadComparison.new(deltas.freeze)
+      end
+
+      def query_deltas(query, before)
+        return [] unless before
+
+        METRICS.filter_map do |metric|
+          delta(query.query_id, metric, Float(before.fetch(metric)), Float(query.to_h.fetch(metric.to_sym)))
+        end
+      end
+      private_class_method :query_deltas
+
+      def delta(query_id, metric, before, after)
+        return if before.zero? && after.zero?
+
+        percent = before.zero? ? 100.0 : ((after - before) * 100.0 / before).round(2)
+        WorkloadDelta.new(query_id, metric.to_sym, before, after, percent)
+      end
+      private_class_method :delta
+    end
+  end
+end