rails_db_inspector 0.1.0

data/config/routes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+RailsDbInspector::Engine.routes.draw do
+  root to: "queries#index"
+
+  resources :queries, only: %i[index show] do
+    member do
+      get :explain
+    end
+
+    collection do
+      post :clear
+    end
+  end
+
+  get "schema", to: "schema#index", as: :schema_index
+end

data/lib/rails_db_inspector/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RailsDbInspector
+  class Configuration
+    attr_accessor :enabled
+    attr_accessor :max_queries
+    attr_accessor :allow_explain_analyze
+    attr_accessor :show_widget
+
+    def initialize
+      @enabled = true
+      @max_queries = 2_000
+      @allow_explain_analyze = false
+      @show_widget = true
+    end
+  end
+end

data/lib/rails_db_inspector/dev_widget_middleware.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module RailsDbInspector
+  class DevWidgetMiddleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, response = @app.call(env)
+
+      # Only inject into HTML responses in development
+      return [ status, headers, response ] unless injectable?(status, headers, env)
+
+      body = +""
+      response.each { |part| body << part }
+      response.close if response.respond_to?(:close)
+
+      # Find the mount path for the engine
+      mount_path = find_mount_path
+
+      if body.include?("</body>") && mount_path
+        widget_html = render_widget(mount_path)
+        body.sub!("</body>", "#{widget_html}\n</body>")
+        headers["Content-Length"] = body.bytesize.to_s
+      end
+
+      [ status, headers, [ body ] ]
+    end
+
+    private
+
+    def injectable?(status, headers, env)
+      return false unless status == 200
+      return false unless headers["Content-Type"]&.include?("text/html")
+
+      # Don't inject into the engine's own pages
+      mount_path = find_mount_path
+      return false if mount_path && env["PATH_INFO"]&.start_with?(mount_path)
+
+      true
+    end
+
+    def find_mount_path
+      @mount_path ||= begin
+        Rails.application.routes.routes.each do |route|
+          if route.app.respond_to?(:app) && route.app.app == RailsDbInspector::Engine
+            return "/" + route.path.spec.to_s.sub(/\(.*\)/, "").gsub(%r{^/|/$}, "")
+          end
+        end
+        nil
+      end
+    end
+
+    def render_widget(mount_path)
+      queries_url = "#{mount_path}"
+      schema_url = "#{mount_path}/schema"
+
+      <<~HTML
+        <!-- Rails DB Inspector Dev Widget -->
+        <div id="rdi-widget" style="
+          position: fixed;
+          bottom: 16px;
+          right: 16px;
+          z-index: 99999;
+          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        ">
+          <div id="rdi-panel" style="
+            display: none;
+            background: #1f2937;
+            border-radius: 12px;
+            padding: 12px;
+            margin-bottom: 8px;
+            box-shadow: 0 10px 25px rgba(0,0,0,0.3);
+            min-width: 200px;
+          ">
+            <div style="color: #9ca3af; font-size: 10px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 8px; padding: 0 4px;">
+              DB Inspector
+            </div>
+            <a href="#{queries_url}" target="_blank" rel="noopener" style="
+              display: flex;
+              align-items: center;
+              padding: 8px 12px;
+              color: #e5e7eb;
+              text-decoration: none;
+              font-size: 13px;
+              font-weight: 500;
+              border-radius: 8px;
+              margin-bottom: 4px;
+              transition: background 0.15s;
+            " onmouseover="this.style.background='#374151'" onmouseout="this.style.background='transparent'">
+              <span style="margin-right: 8px; font-size: 16px;">🔍</span>
+              Query Monitor
+            </a>
+            <a href="#{schema_url}" target="_blank" rel="noopener" style="
+              display: flex;
+              align-items: center;
+              padding: 8px 12px;
+              color: #e5e7eb;
+              text-decoration: none;
+              font-size: 13px;
+              font-weight: 500;
+              border-radius: 8px;
+              transition: background 0.15s;
+            " onmouseover="this.style.background='#374151'" onmouseout="this.style.background='transparent'">
+              <span style="margin-right: 8px; font-size: 16px;">🗄️</span>
+              Schema Visualization
+            </a>
+          </div>
+          <button onclick="
+            var panel = document.getElementById('rdi-panel');
+            panel.style.display = panel.style.display === 'none' ? 'block' : 'none';
+          " style="
+            width: 48px;
+            height: 48px;
+            border-radius: 50%;
+            background: #2563eb;
+            border: none;
+            color: white;
+            font-size: 20px;
+            cursor: pointer;
+            box-shadow: 0 4px 12px rgba(37, 99, 235, 0.4);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            transition: transform 0.15s, box-shadow 0.15s;
+            margin-left: auto;
+          " onmouseover="this.style.transform='scale(1.1)';this.style.boxShadow='0 6px 16px rgba(37,99,235,0.5)'" onmouseout="this.style.transform='scale(1)';this.style.boxShadow='0 4px 12px rgba(37,99,235,0.4)'">
+            🛢️
+          </button>
+        </div>
+        <script>
+          document.addEventListener('click', function(e) {
+            var widget = document.getElementById('rdi-widget');
+            var panel = document.getElementById('rdi-panel');
+            if (panel && widget && !widget.contains(e.target)) {
+              panel.style.display = 'none';
+            }
+          });
+        </script>
+        <!-- /Rails DB Inspector Dev Widget -->
+      HTML
+    end
+  end
+end

data/lib/rails_db_inspector/engine.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "dev_widget_middleware"
+
+module RailsDbInspector
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsDbInspector
+
+    initializer "rails_db_inspector.subscribe_sql" do
+      next unless RailsDbInspector.configuration.enabled
+      RailsDbInspector::SqlSubscriber.install!
+    end
+
+    initializer "rails_db_inspector.dev_widget" do |app|
+      next unless RailsDbInspector.configuration.enabled
+      next unless RailsDbInspector.configuration.show_widget
+      next unless Rails.env.development?
+
+      app.middleware.use RailsDbInspector::DevWidgetMiddleware
+    end
+  end
+end

data/lib/rails_db_inspector/explain/my_sql.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsDbInspector
+  class Explain
+    class MySql
+      def initialize(connection)
+        @connection = connection
+      end
+
+      def explain(sql, analyze: false)
+        # Strip any existing EXPLAIN prefix to prevent doubling
+        clean_sql = sql.sub(/\A\s*EXPLAIN\s*(ANALYZE)?\s*/i, "")
+
+        statement =
+          if analyze
+            RailsDbInspector::Explain.select_only!(clean_sql)
+            "EXPLAIN ANALYZE #{clean_sql}"
+          else
+            "EXPLAIN #{clean_sql}"
+          end
+
+        result = @connection.exec_query(statement)
+
+        { adapter: "mysql", analyze: analyze, columns: result.columns, rows: result.rows }
+      end
+    end
+  end
+end

data/lib/rails_db_inspector/explain/postgres.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RailsDbInspector
+  class Explain
+    class Postgres
+      def initialize(connection)
+        @connection = connection
+      end
+
+      def explain(sql, analyze: false)
+        # Strip any existing EXPLAIN prefix to prevent doubling
+        clean_sql = sql.sub(/\A\s*EXPLAIN\s*(\([^)]*\))?\s*/i, "")
+
+        statement =
+          if analyze
+            RailsDbInspector::Explain.select_only!(clean_sql)
+            "EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT JSON) #{clean_sql}"
+          else
+            "EXPLAIN (FORMAT JSON) #{clean_sql}"
+          end
+
+        result = @connection.exec_query(statement)
+        raw = result.rows.dig(0, 0)
+        plan = raw.is_a?(String) ? JSON.parse(raw) : raw
+
+        { adapter: "postgres", analyze: analyze, plan: plan }
+      end
+    end
+  end
+end

data/lib/rails_db_inspector/explain.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsDbInspector
+  class Explain
+    class UnsupportedAdapter < StandardError; end
+    class DangerousQuery < StandardError; end
+
+    def self.for_connection(connection)
+      adapter = connection.adapter_name.to_s.downcase
+
+      case adapter
+      when /postgres/
+        RailsDbInspector::Explain::Postgres.new(connection)
+      when /mysql/
+        RailsDbInspector::Explain::MySql.new(connection)
+      else
+        raise UnsupportedAdapter, "Unsupported adapter: #{connection.adapter_name}"
+      end
+    end
+
+    def self.select_only!(sql)
+      return if sql.strip.match?(/\ASELECT\b/i)
+
+      raise DangerousQuery, "Only SELECT is allowed for EXPLAIN ANALYZE by default"
+    end
+  end
+end

data/lib/rails_db_inspector/query_store.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "securerandom"
+require "thread"
+
+module RailsDbInspector
+  class QueryStore
+    include Singleton
+
+    Query = Struct.new(
+      :id,
+      :sql,
+      :name,
+      :binds,
+      :duration_ms,
+      :connection_id,
+      :timestamp,
+      keyword_init: true
+    )
+
+    def initialize
+      @mutex = Mutex.new
+      @queries = []
+      @by_id = {}
+    end
+
+    def add(sql:, name:, binds:, duration_ms:, connection_id:, timestamp:)
+      q = Query.new(
+        id: SecureRandom.hex(8),
+        sql: sql,
+        name: name,
+        binds: normalize_binds(binds),
+        duration_ms: duration_ms.to_f,
+        connection_id: connection_id,
+        timestamp: timestamp
+      )
+
+      @mutex.synchronize do
+        @queries << q
+        @by_id[q.id] = q
+        trim!
+      end
+
+      q
+    end
+
+    def all
+      @mutex.synchronize { @queries.dup }
+    end
+
+    def find(id)
+      @mutex.synchronize { @by_id[id] }
+    end
+
+    def clear!
+      @mutex.synchronize do
+        @queries.clear
+        @by_id.clear
+      end
+    end
+
+    private
+
+    def trim!
+      max = RailsDbInspector.configuration.max_queries.to_i
+      return if max <= 0
+      return if @queries.length <= max
+
+      drop_count = @queries.length - max
+      dropped = @queries.shift(drop_count)
+      dropped.each { |q| @by_id.delete(q.id) }
+    end
+
+    def normalize_binds(binds)
+      return [] unless binds.is_a?(Array)
+
+      binds.map do |b|
+        if b.respond_to?(:name) && b.respond_to?(:value_before_type_cast)
+          { name: b.name, value: b.value_before_type_cast, type: b.type&.type }
+        elsif b.is_a?(Array) && b.length == 2
+          { name: b[0].to_s, value: b[1], type: nil }
+        else
+          { name: nil, value: b.to_s, type: nil }
+        end
+      end
+    end
+  end
+end

data/lib/rails_db_inspector/schema_inspector.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module RailsDbInspector
+  class SchemaInspector
+    attr_reader :connection
+
+    def initialize(connection = ActiveRecord::Base.connection)
+      @connection = connection
+    end
+
+    IGNORED_TABLES = %w[schema_migrations ar_internal_metadata].freeze
+
+    # Returns a hash of table_name => { columns:, indexes:, foreign_keys: }
+    def introspect
+      tables = connection.tables.sort - IGNORED_TABLES
+      schema = {}
+
+      tables.each do |table|
+        columns = introspect_columns(table)
+        indexes = introspect_indexes(table)
+        schema[table] = {
+          columns: columns,
+          indexes: indexes,
+          foreign_keys: introspect_foreign_keys(table),
+          primary_key: introspect_primary_key(table),
+          row_count: safe_row_count(table),
+          associations: introspect_associations(table),
+          missing_indexes: detect_missing_indexes(columns, indexes),
+          polymorphic_columns: detect_polymorphic_columns(columns)
+        }
+      end
+
+      schema
+    end
+
+    # Returns relationships between tables for visualization
+    def relationships
+      rels = []
+
+      (connection.tables.sort - IGNORED_TABLES).each do |table|
+        # Foreign key-based relationships
+        if connection.respond_to?(:foreign_keys)
+          connection.foreign_keys(table).each do |fk|
+            rels << {
+              from_table: table,
+              from_column: fk.column,
+              to_table: fk.to_table,
+              to_column: fk.primary_key || "id",
+              type: :foreign_key
+            }
+          end
+        end
+
+        # Convention-based relationships (belongs_to via _id columns)
+        connection.columns(table).each do |col|
+          next unless col.name.end_with?("_id")
+
+          referenced_table = col.name.sub(/_id\z/, "").pluralize
+          next unless connection.tables.include?(referenced_table)
+
+          # Skip if already covered by a foreign key
+          already_covered = rels.any? do |r|
+            r[:from_table] == table && r[:from_column] == col.name
+          end
+          next if already_covered
+
+          rels << {
+            from_table: table,
+            from_column: col.name,
+            to_table: referenced_table,
+            to_column: "id",
+            type: :convention
+          }
+        end
+      end
+
+      rels
+    end
+
+    private
+
+    def introspect_columns(table)
+      connection.columns(table).map do |col|
+        {
+          name: col.name,
+          type: col.sql_type,
+          nullable: col.null,
+          default: col.default
+        }
+      end
+    end
+
+    def introspect_indexes(table)
+      connection.indexes(table).map do |idx|
+        {
+          name: idx.name,
+          columns: idx.columns,
+          unique: idx.unique
+        }
+      end
+    end
+
+    def introspect_foreign_keys(table)
+      return [] unless connection.respond_to?(:foreign_keys)
+
+      connection.foreign_keys(table).map do |fk|
+        {
+          column: fk.column,
+          to_table: fk.to_table,
+          primary_key: fk.primary_key || "id",
+          name: fk.name
+        }
+      end
+    end
+
+    def introspect_primary_key(table)
+      connection.primary_key(table)
+    end
+
+    def safe_row_count(table)
+      quoted = connection.quote_table_name(table)
+      result = connection.select_value("SELECT COUNT(*) FROM #{quoted}")
+      result.to_i
+    rescue StandardError
+      nil
+    end
+
+    def introspect_associations(table)
+      model = find_model_for_table(table)
+      return [] unless model
+
+      model.reflect_on_all_associations.map do |assoc|
+        target_table = begin
+          assoc.klass.table_name
+        rescue StandardError
+          nil
+        end
+
+        {
+          name: assoc.name.to_s,
+          macro: assoc.macro.to_s,
+          target_table: target_table,
+          foreign_key: assoc.foreign_key.to_s,
+          through: assoc.options[:through]&.to_s
+        }
+      end
+    rescue StandardError
+      []
+    end
+
+    # Detect _id columns that lack a corresponding index
+    def detect_missing_indexes(columns, indexes)
+      indexed_columns = indexes.flat_map { |idx| idx[:columns] }.to_set
+
+      columns
+        .select { |col| col[:name].end_with?("_id") }
+        .reject { |col| indexed_columns.include?(col[:name]) }
+        .map { |col| col[:name] }
+    end
+
+    # Detect polymorphic column pairs (*_type + *_id)
+    def detect_polymorphic_columns(columns)
+      col_names = columns.map { |c| c[:name] }.to_set
+      polymorphics = []
+
+      columns.each do |col|
+        next unless col[:name].end_with?("_type")
+
+        base = col[:name].sub(/_type\z/, "")
+        id_col = "#{base}_id"
+        next unless col_names.include?(id_col)
+
+        polymorphics << {
+          name: base,
+          type_column: col[:name],
+          id_column: id_col
+        }
+      end
+
+      polymorphics
+    end
+
+    def find_model_for_table(table)
+      # Force-load all models so descendants are populated
+      eager_load_models!
+
+      ActiveRecord::Base.descendants.detect do |klass|
+        klass.table_name == table && !klass.abstract_class?
+      rescue StandardError
+        false
+      end
+    rescue StandardError
+      nil
+    end
+
+    def eager_load_models!
+      return if @models_loaded
+      @models_loaded = true
+
+      # Use Zeitwerk autoloader to load all models
+      model_paths = Rails.application.config.paths["app/models"].to_a
+      model_paths.each do |dir|
+        Dir.glob("#{dir}/**/*.rb").sort.each do |file|
+          begin
+            require file
+          rescue StandardError, LoadError
+            # Skip models that fail to load
+          end
+        end
+      end
+
+      # Fallback: eager load the whole app if no descendants found
+      if ActiveRecord::Base.descendants.reject { |k| k.abstract_class? rescue true }.empty?
+        begin
+          Rails.application.eager_load!
+        rescue StandardError
+          # ignore
+        end
+      end
+    end
+  end
+end

data/lib/rails_db_inspector/sql_subscriber.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RailsDbInspector
+  class SqlSubscriber
+    IGNORED_NAMES = [
+      "SCHEMA",
+      "TRANSACTION",
+      "ActiveRecord::SchemaMigration Load",
+      "ActiveRecord::InternalMetadata Load"
+    ].freeze
+
+    def self.install!
+      return if @installed
+
+      @installed = true
+      RailsDbInspector::QueryStore.instance
+
+      ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        payload = event.payload
+
+        name = payload[:name].to_s
+        sql  = payload[:sql].to_s
+
+        next if sql.strip.empty?
+        next if IGNORED_NAMES.include?(name)
+        next if sql =~ /\A(?:BEGIN|COMMIT|ROLLBACK)\b/i
+        next if sql =~ /\A\s*EXPLAIN\b/i
+        next if payload[:cached]
+
+        RailsDbInspector::QueryStore.instance.add(
+          sql: sql,
+          name: name,
+          binds: payload[:binds],
+          duration_ms: event.duration,
+          connection_id: payload[:connection_id],
+          timestamp: (event.time.is_a?(Time) ? event.time : Time.at(event.time.to_f))
+        )
+      end
+    end
+  end
+end

data/lib/rails_db_inspector/version.rb

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

data/lib/rails_db_inspector.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "rails_db_inspector/version"
+require_relative "rails_db_inspector/engine"
+require_relative "rails_db_inspector/configuration"
+require_relative "rails_db_inspector/query_store"
+require_relative "rails_db_inspector/sql_subscriber"
+require_relative "rails_db_inspector/explain"
+require_relative "rails_db_inspector/explain/postgres"
+require_relative "rails_db_inspector/explain/my_sql"
+require_relative "rails_db_inspector/schema_inspector"
+
+module RailsDbInspector
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/tasks/rails_db_inspector_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :rails_db_inspector do
+#   # Task goes here
+# end