pg_canary 0.1.0

data/lib/pg_canary/rules/definitions/unindexed_order_by_with_limit.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): ORDER BY x LIMIT n without an index led by x forces a
+    # full sort before the limit can apply. Size-dependent, so disabled by
+    # default and gated by config.table_size_hints.
+    class UnindexedOrderByWithLimit < Base
+      include IndexPredicates
+
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        true
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          next unless scope.limited?
+
+          sort_by = scope.sort_items.first
+          next unless sort_by
+
+          column_ref = unwrap_node(sort_by.node)
+          next unless column_ref.is_a?(PgQuery::ColumnRef)
+
+          table, column = scope.resolve(column_ref)
+          next unless table && column
+          next unless applicable_table?(query, table)
+          next if index_leading_with?(query, table, column)
+
+          detections << detection(
+            query,
+            table: table,
+            columns: column,
+            message: "ORDER BY #{column} LIMIT sorts every row before the limit can apply " \
+                     "(no index on #{table} leads with #{column}).",
+            suggestion: <<~SUGGESTION.chomp
+              Consider indexing the sort key:
+                CREATE INDEX index_#{table}_on_#{column} ON #{table} (#{column});
+            SUGGESTION
+          )
+        end
+        detections
+      end
+    end
+  end
+end

data/lib/pg_canary/rules/definitions/unindexed_where.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): equality/range predicates on columns with no index
+    # whose leading column could serve them. Depends on production table
+    # size — a 30-row lookup table is fine without indexes — hence disabled
+    # by default and gated by config.table_size_hints.
+    class UnindexedWhere < Base
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        true
+      end
+
+      def check(query)
+        query.each_scope.with_object([]) do |scope, detections|
+          next unless scope.where_clause
+
+          predicate_columns(query, scope).each do |table, columns|
+            next unless applicable_table?(query, table)
+            next if served_by_index?(query, table, columns)
+
+            detections << build(query, table, columns)
+          end
+        end
+      end
+
+      private
+
+      # => { table => [column, ...] } for plain-column predicates in WHERE.
+      def predicate_columns(_query, scope)
+        result = Hash.new { |h, k| h[k] = [] }
+        walk_within_scope(scope.where_clause) do |node|
+          next unless node.is_a?(PgQuery::A_Expr) && indexable_predicate?(node)
+
+          [node.lexpr, node.rexpr].each do |side|
+            column_ref = unwrap_node(side)
+            next unless column_ref.is_a?(PgQuery::ColumnRef)
+            next unless constant_side?(node, side)
+
+            table, column = scope.resolve(column_ref)
+            result[table] << column if table && column
+          end
+        end
+        result.transform_values(&:uniq)
+      end
+
+      def indexable_predicate?(a_expr)
+        comparison_expr?(a_expr) ||
+          %i[AEXPR_IN AEXPR_BETWEEN AEXPR_LIKE AEXPR_ILIKE].include?(a_expr.kind)
+      end
+
+      # Only count `column <op> constant-ish` predicates; column-to-column
+      # comparisons (join conditions in WHERE) are not our business here.
+      def constant_side?(a_expr, column_side)
+        other = a_expr.lexpr.equal?(column_side) ? a_expr.rexpr : a_expr.lexpr
+        node = strip_type_casts(other)
+        case node
+        when PgQuery::A_Const, PgQuery::ParamRef
+          true
+        when PgQuery::List
+          node.items.all? { |i| strip_type_casts(i).is_a?(PgQuery::A_Const) || strip_type_casts(i).is_a?(PgQuery::ParamRef) }
+        else
+          false
+        end
+      end
+
+      # Leftmost-prefix rule: an index helps when its leading column is one
+      # of the predicate columns.
+      def served_by_index?(query, table, columns)
+        query.indexes(table).any? do |index|
+          index.leading_column && columns.include?(index.leading_column)
+        end
+      end
+
+      def build(query, table, columns)
+        column_list = columns.join(", ")
+        detection(
+          query,
+          table: table,
+          columns: columns,
+          message: "No index leads with any of the WHERE predicate columns (#{table}.#{column_list}). " \
+                   "Depending on production row counts, this becomes a full scan.",
+          suggestion: <<~SUGGESTION.chomp
+            Consider adding an index (equality columns first):
+              CREATE INDEX index_#{table}_on_#{columns.join("_and_")} ON #{table} (#{column_list});
+          SUGGESTION
+        )
+      end
+    end
+  end
+end

data/lib/pg_canary/rules/definitions/union_instead_of_union_all.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): UNION without ALL deduplicates the combined result by
+    # sorting/hashing all rows. When the branches cannot overlap (or
+    # duplicates are acceptable), UNION ALL skips that work. Whether
+    # deduplication is intended is the author's call, hence opt-in.
+    class UnionInsteadOfUnionAll < Base
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def check(query)
+        union = query.scopes.find { |scope| scope.stmt.op == :SETOP_UNION && !scope.stmt.all }
+        return [] unless union
+
+        [detection(
+          query,
+          message: "UNION (without ALL) sorts/hashes the entire combined result to remove duplicates.",
+          suggestion: "If the branches cannot produce overlapping rows — or duplicates are acceptable — use UNION ALL."
+        )]
+      end
+    end
+  end
+end

data/lib/pg_canary/rules/detection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    MAX_SQL_LENGTH = 500
+
+    # What a rule's #check returns: one anti-pattern finding — which rule
+    # fired, on which query, which table/columns are involved, why it is a
+    # problem, and how to fix it.
+    Detection = Struct.new(
+      :rule_name, :severity, :sql, :table, :columns,
+      :message, :suggestion, :location, :fingerprint,
+      keyword_init: true
+    ) do
+      def truncated_sql
+        squashed = sql.to_s.strip.gsub(/\s+/, " ")
+        squashed.length > MAX_SQL_LENGTH ? "#{squashed[0, MAX_SQL_LENGTH]}…" : squashed
+      end
+    end
+  end
+end

data/lib/pg_canary/rules/index_predicates.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Predicates over index metadata, for rules that stay silent when a
+    # suitable index exists. Include only in rules that need them.
+    module IndexPredicates
+      TRGM_ACCESS_METHODS = %w[gin gist].freeze
+
+      private
+
+      def trgm_index?(query, table, column)
+        query.indexes(table).any? do |index|
+          TRGM_ACCESS_METHODS.include?(index.using) &&
+            index.columns.include?(column) &&
+            index.opclasses[column].to_s.include?("trgm")
+        end
+      end
+
+      def gin_index_on?(query, table, column)
+        query.indexes(table).any? { |index| index.using == "gin" && index.columns.include?(column) }
+      end
+
+      # Any expression index whose expression mentions the column.
+      # Deliberately loose (column-level word match, not expression
+      # equality) to avoid false positives.
+      def expression_index_referencing?(query, table, column)
+        query.indexes(table).any? do |index|
+          index.expressions&.match?(/\b#{Regexp.escape(column)}\b/)
+        end
+      end
+
+      # Whether any index's leading column is +column+ (leftmost-prefix rule).
+      def index_leading_with?(query, table, column)
+        query.indexes(table).any? { |index| index.leading_column == column }
+      end
+    end
+  end
+end

data/lib/pg_canary/rules/query_context.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # What a rule's #check receives: everything about one executed query —
+    # the parsed AST (as Scopes), bind parameter values, the configuration,
+    # and access to schema metadata via the connection the query ran on.
+    class QueryContext
+      include PgQuerySupport
+
+      # One SELECT scope (top-level statement, CTE, subquery, ...) with its
+      # own FROM-clause alias resolution.
+      class Scope
+        include PgQuerySupport
+
+        attr_reader :stmt, :aliases
+
+        def initialize(stmt)
+          @stmt = stmt
+          @aliases = {}
+          collect_aliases(stmt.from_clause)
+        end
+
+        def where_clause
+          stmt.where_clause
+        end
+
+        # => [PgQuery::SortBy]
+        def sort_items
+          stmt.sort_clause.map { |n| unwrap_node(n) }.grep(PgQuery::SortBy)
+        end
+
+        def limited?
+          !stmt.limit_count.nil?
+        end
+
+        # Real table names referenced directly in this scope's FROM clause.
+        def tables
+          @aliases.values.compact.uniq
+        end
+
+        # Resolves a ColumnRef to [table, column]. Returns nil when the ref
+        # cannot be attributed to a real table unambiguously (unknown alias,
+        # subquery output, multiple candidate tables for an unqualified ref).
+        def resolve(column_ref)
+          fields = column_ref_fields(column_ref)
+          return nil if fields.nil? || fields.empty?
+
+          column = fields.last
+          if fields.length >= 2
+            table = @aliases[fields[-2]]
+            table ? [table, column] : nil
+          else
+            tables.length == 1 ? [tables.first, column] : nil
+          end
+        end
+
+        private
+
+        def collect_aliases(from_clause)
+          from_clause.each { |node| collect_from_node(unwrap_node(node)) }
+        end
+
+        def collect_from_node(node)
+          case node
+          when PgQuery::RangeVar
+            name = node.alias&.aliasname
+            name = node.relname if name.nil? || name.empty?
+            @aliases[name] = node.relname
+          when PgQuery::JoinExpr
+            collect_from_node(unwrap_node(node.larg))
+            collect_from_node(unwrap_node(node.rarg))
+          when PgQuery::RangeSubselect
+            name = node.alias&.aliasname
+            @aliases[name] = nil if name && !name.empty?
+          end
+        end
+      end
+
+      attr_reader :sql, :connection, :parse_result, :config
+
+      def initialize(sql:, connection:, parse_result:, config:, binds: [], type_casted_binds: nil)
+        @sql = sql
+        @connection = connection
+        @parse_result = parse_result
+        @config = config
+        @binds = binds || []
+        @type_casted_binds = type_casted_binds
+      end
+
+      # Cannot fail: a QueryContext is only built for SQL that already parsed.
+      def fingerprint
+        @fingerprint ||= PgQuery.fingerprint(sql)
+      end
+
+      # All SELECT scopes in the statement, including CTEs, subqueries in
+      # FROM/WHERE and UNION branches.
+      def scopes
+        @scopes ||= begin
+          stmts = []
+          parse_result.tree.stmts.each do |raw|
+            walk_ast(raw.stmt) { |msg| stmts << msg if msg.is_a?(PgQuery::SelectStmt) }
+          end
+          stmts.map { |s| Scope.new(s) }
+        end
+      end
+
+      def each_scope(&)
+        scopes.each(&)
+      end
+
+      # All real table names touched anywhere in the query.
+      def tables
+        @tables ||= scopes.flat_map(&:tables).uniq
+      end
+
+      # Value for a ParamRef ($n, 1-based). nil when unknown.
+      def bind_value(number)
+        index = number - 1
+        return nil if index.negative?
+
+        casted = @type_casted_binds
+        return casted[index] if casted.is_a?(Array) && index < casted.length
+
+        bind = @binds[index]
+        return nil if bind.nil?
+
+        bind.respond_to?(:value_for_database) ? bind.value_for_database : bind
+      end
+
+      # --- schema metadata for the query's connection ---
+
+      def indexes(table)
+        SchemaIntrospection.indexes(connection, table)
+      end
+
+      def column_type(table, column)
+        SchemaIntrospection.column_type(connection, table, column)
+      end
+
+      # => { column_name => sql_type }
+      def column_types(table)
+        SchemaIntrospection.column_types(connection, table)
+      end
+    end
+  end
+end

data/lib/pg_canary/schema_introspection.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module PgCanary
+  # Index and column metadata for the rules, read through ActiveRecord's
+  # schema cache — caching, invalidation and thread safety ride on Rails.
+  # The catalog queries ActiveRecord issues are named "SCHEMA", which the
+  # Subscriber already ignores, so they are never analyzed themselves.
+  module SchemaIntrospection
+    IndexInfo = Struct.new(
+      :name,        # index name
+      :using,       # access method: "btree", "gin", "gist", ...
+      :columns,     # [String] — empty for expression indexes
+      :opclasses,   # { column => opclass } for non-default opclasses
+      :expressions, # SQL string of the indexed expressions, or nil
+      keyword_init: true
+    ) do
+      def leading_column
+        columns.first
+      end
+    end
+
+    module_function
+
+    # => [IndexInfo] — includes the primary key, which ActiveRecord's
+    # #indexes omits.
+    def indexes(connection, table)
+      cache = connection.schema_cache
+      return [] unless cache.data_source_exists?(table)
+
+      list = cache.indexes(table).map { |definition| index_info(definition) }
+      primary_key = Array(cache.primary_keys(table))
+      if primary_key.any?
+        list << IndexInfo.new(name: "#{table}_pkey", using: "btree",
+                              columns: primary_key, opclasses: {}, expressions: nil)
+      end
+      list
+    rescue StandardError => e
+      PgCanary.internal_error(e)
+      []
+    end
+
+    def column_type(connection, table, column)
+      column_types(connection, table)[column]
+    end
+
+    # => { column_name => sql_type } e.g. { "id" => "bigint", "tags" => "text[]" }
+    def column_types(connection, table)
+      cache = connection.schema_cache
+      return {} unless cache.data_source_exists?(table)
+
+      cache.columns(table).to_h do |column|
+        type = column.sql_type
+        type = "#{type}[]" if column.respond_to?(:array?) && column.array?
+        [column.name, type]
+      end
+    rescue StandardError => e
+      PgCanary.internal_error(e)
+      {}
+    end
+
+    # ActiveRecord returns plain-column indexes with an Array of column
+    # names, and expression indexes with the expressions as one SQL String.
+    def index_info(definition)
+      expressions = definition.columns.is_a?(String) ? definition.columns : nil
+      columns = expressions ? [] : Array(definition.columns)
+      opclasses = definition.opclasses
+      opclasses = columns.to_h { |c| [c, opclasses.to_s] } unless opclasses.is_a?(Hash)
+      IndexInfo.new(name: definition.name, using: definition.using.to_s,
+                    columns: columns, opclasses: opclasses, expressions: expressions)
+    end
+  end
+end

data/lib/pg_canary/subscriber.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PgCanary
+  # Subscribes to sql.active_record, filters events down to likely SELECT
+  # statements, and hands them to the Detector. Stateless per event, so
+  # everything lives at class level.
+  class Subscriber
+    # Event names that never carry application SELECTs. "SCHEMA" also covers
+    # the catalog queries ActiveRecord's schema cache runs on our behalf.
+    IGNORED_NAMES = %w[SCHEMA TRANSACTION].freeze
+    # Cheap pre-filter before paying for a real parse.
+    SELECT_PREFIX = %r{\A\s*(?:/\*.*?\*/\s*)*(?:SELECT|WITH)\b}im
+
+    class << self
+      def subscribe!
+        @subscribe ||= ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+          next unless analysis_target?(payload)
+
+          detections = detector.call(payload)
+          Middleware.collect(detections) if detections.any?
+        rescue StandardError => e
+          PgCanary.internal_error(e)
+        end
+      end
+
+      private
+
+      def analysis_target?(payload)
+        return false if payload[:cached]
+        return false if payload[:name] && IGNORED_NAMES.include?(payload[:name])
+        return false unless payload[:sql]&.match?(SELECT_PREFIX)
+
+        !!payload[:connection]&.adapter_name&.match?(/postg/i)
+      end
+
+      def detector
+        @detector ||= Detector.new(PgCanary.config)
+      end
+    end
+  end
+end

data/lib/pg_canary/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PgCanary
+  VERSION = "0.1.0"
+end

data/lib/pg_canary.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "pg_query"
+
+require_relative "pg_canary/version"
+require_relative "pg_canary/configuration"
+require_relative "pg_canary/pg_query_support"
+require_relative "pg_canary/schema_introspection"
+require_relative "pg_canary/rules/detection"
+require_relative "pg_canary/rules/query_context"
+require_relative "pg_canary/rules/base"
+require_relative "pg_canary/rules/index_predicates"
+Dir[File.join(__dir__, "pg_canary", "rules", "definitions", "*.rb")].each { |file| require file }
+require_relative "pg_canary/detector"
+require_relative "pg_canary/subscriber"
+require_relative "pg_canary/middleware"
+
+module PgCanary
+  class Error < StandardError; end
+
+  @config = Configuration.new
+
+  class << self
+    attr_reader :config
+
+    def configure
+      yield config
+    end
+
+    # Reports an internal pg_canary failure without ever breaking the host app.
+    def internal_error(error)
+      warn_once("[PgCanary] internal error (detection skipped): #{error.class}: #{error.message}")
+    end
+
+    private
+
+    def logger
+      config.logger || default_logger
+    end
+
+    def default_logger
+      @default_logger ||= begin
+        require "logger"
+        ::Logger.new($stderr)
+      end
+    end
+
+    def warn_once(message)
+      @warned ||= {}
+      return if @warned[message]
+
+      @warned[message] = true
+      logger.warn(message)
+    end
+  end
+
+  if defined?(Rails::Railtie)
+    # Middleware insertion and automatic enabling in development/test.
+    class Railtie < Rails::Railtie
+      initializer "pg_canary.app_root", before: :load_config_initializers do
+        PgCanary.config.app_root ||= Rails.root.to_s
+      end
+
+      initializer "pg_canary.middleware" do |app|
+        app.middleware.use PgCanary::Middleware
+      end
+
+      config.after_initialize do
+        config = PgCanary.config
+        config.enabled = Rails.env.development? || Rails.env.test? if config.enabled.nil?
+        config.logger ||= Rails.logger
+        Subscriber.subscribe! if config.enabled
+      end
+    end
+  end
+end