pg_canary 0.1.0

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Searching a jsonb column in WHERE:
+    # - containment/existence operators (@>, <@, ?, ?|, ?&) need a GIN index
+    #   on the column
+    # - key extraction (->> etc.) compared against a value needs a matching
+    #   expression index
+    class JsonbSearchWithoutGin < Base
+      include IndexPredicates
+
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      CONTAINMENT_OPS = %w[@> <@ ? ?| ?&].freeze
+      EXTRACTION_OPS = %w[-> ->> #> #>>].freeze
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          next unless scope.where_clause
+
+          walk_within_scope(scope.where_clause) do |node|
+            next unless node.is_a?(PgQuery::A_Expr) && node.kind == :AEXPR_OP
+
+            operator = operator_name(node)
+            if CONTAINMENT_OPS.include?(operator)
+              detections << inspect_containment(query, scope, node, operator)
+            elsif EXTRACTION_OPS.include?(operator)
+              detections << inspect_extraction(query, scope, node, operator)
+            end
+          end
+        end
+        detections.compact
+      end
+
+      private
+
+      def inspect_containment(query, scope, expr, operator)
+        table, column = jsonb_column(query, scope, [expr.lexpr, expr.rexpr])
+        return nil unless table
+        return nil if gin_index_on?(query, table, column)
+
+        detection(
+          query,
+          table: table,
+          columns: column,
+          message: "#{operator} search on jsonb column #{table}.#{column} has no GIN index " \
+                   "and will scan every row in production.",
+          suggestion: <<~SUGGESTION.chomp
+            Consider a GIN index (jsonb_path_ops is smaller/faster if you only use @>):
+              CREATE INDEX index_#{table}_on_#{column} ON #{table} USING gin (#{column});
+          SUGGESTION
+        )
+      end
+
+      def inspect_extraction(query, scope, expr, operator)
+        table, column = jsonb_column(query, scope, [expr.lexpr])
+        return nil unless table
+        return nil if expression_index_referencing?(query, table, column)
+
+        key = extraction_key(expr)
+        expr_sql = "#{column} #{operator} #{key ? "'#{key}'" : "..."}"
+        detection(
+          query,
+          table: table,
+          columns: column,
+          message: "Filtering on #{table}.#{expr_sql} has no matching expression index, " \
+                   "so no index can serve this predicate.",
+          suggestion: <<~SUGGESTION.chomp
+            Consider an expression index on the extracted key:
+              CREATE INDEX index_#{table}_on_#{column}_key ON #{table} ((#{expr_sql.sub("...", "'key'")}));
+          SUGGESTION
+        )
+      end
+
+      # First side that is a jsonb-typed, resolvable column.
+      def jsonb_column(query, scope, sides)
+        sides.each do |side|
+          column_ref = strip_type_casts(side)
+          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 unless query.column_type(table, column) == "jsonb"
+
+          return [table, column]
+        end
+        nil
+      end
+
+      def extraction_key(expr)
+        const = strip_type_casts(expr.rexpr)
+        return nil unless const.is_a?(PgQuery::A_Const)
+
+        value = constant_value(const)
+        value.is_a?(String) ? value : nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # LIKE / ILIKE with a leading wildcard ('%foo', '%foo%') cannot use a
+    # btree index regardless of table size. Only a pg_trgm GIN/GiST index
+    # helps, so we stay silent when one exists on the column.
+    # Bind parameters ($1) are resolved from the event's binds.
+    class LeadingWildcardLike < Base
+      include IndexPredicates
+
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      LIKE_KINDS = %i[AEXPR_LIKE AEXPR_ILIKE].freeze
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          next unless scope.where_clause
+
+          walk_within_scope(scope.where_clause) do |node|
+            detections << inspect_expr(query, scope, node) if like_expr?(node)
+          end
+        end
+        detections.compact
+      end
+
+      private
+
+      def like_expr?(node)
+        node.is_a?(PgQuery::A_Expr) && LIKE_KINDS.include?(node.kind)
+      end
+
+      def inspect_expr(query, scope, expr)
+        column_ref = strip_type_casts(expr.lexpr)
+        return nil unless column_ref.is_a?(PgQuery::ColumnRef)
+
+        pattern = pattern_value(query, expr.rexpr)
+        return nil unless pattern&.start_with?("%", "_")
+
+        table, column = scope.resolve(column_ref)
+        return nil unless table && column
+        return nil unless applicable_table?(query, table)
+        return nil if trgm_index?(query, table, column)
+
+        operator = expr.kind == :AEXPR_ILIKE ? "ILIKE" : "LIKE"
+        detection(
+          query,
+          table: table,
+          columns: column,
+          message: "Leading-wildcard #{operator} (#{pattern.inspect}) on #{table}.#{column} cannot use " \
+                   "a btree index and will scan every row in production.",
+          suggestion: <<~SUGGESTION.chomp
+            Consider the pg_trgm extension with a GIN index:
+              CREATE EXTENSION IF NOT EXISTS pg_trgm;
+              CREATE INDEX index_#{table}_on_#{column}_trgm ON #{table} USING gin (#{column} gin_trgm_ops);
+          SUGGESTION
+        )
+      end
+
+      # Pattern string from a literal, a cast literal, or a bind parameter.
+      def pattern_value(query, rexpr)
+        node = strip_type_casts(rexpr)
+        case node
+        when PgQuery::A_Const
+          value = constant_value(node)
+          value.is_a?(String) ? value : nil
+        when PgQuery::ParamRef
+          value = query.bind_value(node.number)
+          value.is_a?(String) ? value : nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # NOT IN (SELECT ...) is a double trap: if the subquery ever returns a
+    # NULL the whole predicate yields no rows, and the planner cannot use an
+    # anti-join as effectively as with NOT EXISTS.
+    class NotInSubquery < Base
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          next unless scope.where_clause
+
+          walk_within_scope(scope.where_clause) do |node|
+            next unless not_expr?(node)
+
+            node.args.each do |arg|
+              sublink = unwrap_node(arg)
+              next unless any_sublink?(sublink)
+
+              detections << build(query, scope, sublink)
+            end
+          end
+        end
+        detections
+      end
+
+      private
+
+      def not_expr?(node)
+        node.is_a?(PgQuery::BoolExpr) && node.boolop == :NOT_EXPR
+      end
+
+      # x NOT IN (SELECT ...) parses as NOT(SubLink ANY, "=" test).
+      def any_sublink?(node)
+        return false unless node.is_a?(PgQuery::SubLink)
+        return false unless node.sub_link_type == :ANY_SUBLINK
+
+        operator = string_values(node.oper_name).last
+        operator.nil? || operator == "="
+      end
+
+      def build(query, scope, sublink)
+        test = strip_type_casts(sublink.testexpr)
+        table, column = test.is_a?(PgQuery::ColumnRef) ? scope.resolve(test) : nil
+
+        detection(
+          query,
+          table: table,
+          columns: column,
+          message: "NOT IN (SELECT ...) returns zero rows if the subquery yields even one NULL, " \
+                   "and the planner optimizes it poorly compared to an anti-join — a classic slow query.",
+          suggestion: <<~SUGGESTION.chomp
+            Consider rewriting to NOT EXISTS:
+              SELECT ... FROM t WHERE NOT EXISTS (SELECT 1 FROM sub WHERE sub.ref_id = t.id)
+          SUGGESTION
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): OR conditions spanning different columns. PostgreSQL
+    # can sometimes combine per-column indexes with a BitmapOr, so this is a
+    # warning-level hint rather than a certainty.
+    class OrAcrossColumns < Base
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        true
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          next unless scope.where_clause
+
+          seen = []
+          walk_within_scope(scope.where_clause) do |node|
+            next unless node.is_a?(PgQuery::BoolExpr) && node.boolop == :OR_EXPR
+
+            columns = predicate_columns(query, scope, node)
+            next if columns.length < 2
+            next if seen.include?(columns)
+
+            seen << columns
+            detections << build(query, columns)
+          end
+        end
+        detections
+      end
+
+      private
+
+      # Distinct (table, column) pairs among the OR branches' simple
+      # column-vs-constant predicates.
+      def predicate_columns(query, scope, bool_expr)
+        columns = bool_expr.args.filter_map do |arg|
+          expr = unwrap_node(arg)
+          next nil unless expr.is_a?(PgQuery::A_Expr)
+          next nil unless comparison_expr?(expr) || %i[AEXPR_IN AEXPR_LIKE AEXPR_ILIKE].include?(expr.kind)
+
+          column_ref = strip_type_casts(expr.lexpr)
+          next nil unless column_ref.is_a?(PgQuery::ColumnRef)
+
+          resolved = scope.resolve(column_ref)
+          resolved if resolved && applicable_table?(query, resolved.first)
+        end
+        columns.uniq.sort
+      end
+
+      def build(query, columns)
+        column_list = columns.map { |table, column| "#{table}.#{column}" }.join(", ")
+        detection(
+          query,
+          table: columns.first.first,
+          columns: columns.map(&:last),
+          message: "OR across different columns (#{column_list}) often prevents a single index scan.",
+          suggestion: "Ensure each column has its own index (PostgreSQL can then BitmapOr them), " \
+                      "or split the query into a UNION of two indexed queries."
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # ORDER BY RANDOM() sorts the entire result set just to pick rows —
+    # always suspicious regardless of table size.
+    class OrderByRandom < Base
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          scope.sort_items.each do |sort_by|
+            func = unwrap_node(sort_by.node)
+            next unless func.is_a?(PgQuery::FuncCall)
+            next unless function_name(func) == "random"
+
+            detections << detection(
+              query,
+              table: scope.tables.length == 1 ? scope.tables.first : nil,
+              message: "ORDER BY RANDOM() reads and sorts every row, so it gets slower " \
+                       "in proportion to table size.",
+              suggestion: <<~SUGGESTION.chomp
+                Alternatives:
+                  - TABLESAMPLE: SELECT * FROM t TABLESAMPLE SYSTEM (1) LIMIT n
+                  - random primary-key range: WHERE id >= (SELECT (random() * max(id))::bigint FROM t) LIMIT n
+              SUGGESTION
+            )
+          end
+        end
+        detections
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): "spaghetti query" guard — too many joins or too much
+    # subquery nesting. Thresholds:
+    #   config.rules.query_complexity.max_joins (default 8)
+    #   config.rules.query_complexity.max_depth (default 4)
+    class QueryComplexity < Base
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def self.options
+        { max_joins: 8, max_depth: 4 }
+      end
+
+      def check(query)
+        max_joins = rule_config(query).max_joins
+        max_depth = rule_config(query).max_depth
+        stmt = query.parse_result.tree.stmts.first&.stmt
+        return [] unless stmt
+
+        problems = []
+        joins = count_joins(stmt)
+        depth = max_select_depth(stmt)
+        problems << "#{joins} joins (max #{max_joins})" if joins > max_joins
+        problems << "subquery depth #{depth} (max #{max_depth})" if depth > max_depth
+        return [] if problems.empty?
+
+        [detection(
+          query,
+          message: "Query complexity exceeds thresholds: #{problems.join(", ")}.",
+          suggestion: "Consider splitting the query, precomputing intermediate results, " \
+                      "or reviewing whether every join/subquery is necessary."
+        )]
+      end
+
+      private
+
+      def count_joins(stmt)
+        joins = 0
+        walk_ast(stmt) { |node| joins += 1 if node.is_a?(PgQuery::JoinExpr) }
+        joins
+      end
+
+      # Maximum nesting depth of SELECT statements (a flat query is 1).
+      def max_select_depth(node)
+        node = unwrap_node(node)
+        return 0 unless node.is_a?(Google::Protobuf::MessageExts)
+
+        deepest_child = 0
+        each_ast_child(node) do |child|
+          depth = max_select_depth(child)
+          deepest_child = depth if depth > deepest_child
+        end
+        (node.is_a?(PgQuery::SelectStmt) ? 1 : 0) + deepest_child
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Regular-expression search (~, ~*, SIMILAR TO) cannot use a plain btree
+    # index; only a pg_trgm GIN/GiST index can serve it. The regex variant of
+    # leading_wildcard_like.
+    class RegexWithoutTrgm < Base
+      include IndexPredicates
+
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      REGEX_OPS = %w[~ ~* !~ !~*].freeze
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          next unless scope.where_clause
+
+          walk_within_scope(scope.where_clause) do |node|
+            next unless node.is_a?(PgQuery::A_Expr)
+
+            operator = display_operator(node)
+            next unless operator
+
+            column_ref = strip_type_casts(node.lexpr)
+            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 trgm_index?(query, table, column)
+
+            detections << detection(
+              query,
+              table: table,
+              columns: column,
+              message: "Regular-expression search (#{operator}) on #{table}.#{column} cannot use " \
+                       "a btree index and will scan every row in production.",
+              suggestion: <<~SUGGESTION.chomp
+                Consider the pg_trgm extension with a GIN index:
+                  CREATE EXTENSION IF NOT EXISTS pg_trgm;
+                  CREATE INDEX index_#{table}_on_#{column}_trgm ON #{table} USING gin (#{column} gin_trgm_ops);
+              SUGGESTION
+            )
+          end
+        end
+        detections
+      end
+
+      private
+
+      def display_operator(a_expr)
+        case a_expr.kind
+        when :AEXPR_OP
+          operator = operator_name(a_expr)
+          REGEX_OPS.include?(operator) ? operator : nil
+        when :AEXPR_SIMILAR
+          "SIMILAR TO"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): SELECT * (ActiveRecord's default) on a table that has
+    # heavy columns (bytea / text / jsonb) transfers those payloads on every
+    # query. Whether that matters depends on the data, hence opt-in.
+    # Heavy types: config.rules.select_star_with_heavy_columns.heavy_types.
+    class SelectStarWithHeavyColumns < Base
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def self.options
+        { heavy_types: %w[bytea jsonb text].freeze }
+      end
+
+      def check(query)
+        heavy_types = rule_config(query).heavy_types
+        detections = []
+        query.each_scope do |scope|
+          star_tables(scope).each do |table|
+            next unless applicable_table?(query, table)
+
+            heavy = query.column_types(table).select { |_, type| heavy_types.include?(type) }.keys
+            next if heavy.empty?
+
+            detections << detection(
+              query,
+              table: table,
+              columns: heavy,
+              message: "SELECT * on #{table} transfers its heavy columns (#{heavy.join(", ")}) " \
+                       "on every query.",
+              suggestion: "Select only the columns you need (.select(:id, ...)), or move large " \
+                          "payloads to a separate table loaded on demand."
+            )
+          end
+        end
+        detections
+      end
+
+      private
+
+      # Tables whose rows are fetched with a star target (t.* or bare *).
+      def star_tables(scope)
+        tables = []
+        scope.stmt.target_list.each do |target|
+          res_target = unwrap_node(target)
+          next unless res_target.is_a?(PgQuery::ResTarget)
+
+          column_ref = unwrap_node(res_target.val)
+          next unless column_ref.is_a?(PgQuery::ColumnRef)
+
+          fields = column_ref.fields.map { |f| unwrap_node(f) }
+          next unless fields.last.is_a?(PgQuery::A_Star)
+
+          qualifier = fields[-2]
+          if qualifier.is_a?(PgQuery::String)
+            table = scope.aliases[qualifier.sval]
+            tables << table if table
+          else
+            tables.concat(scope.tables)
+          end
+        end
+        tables.uniq
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): join-condition columns with no index leading with
+    # them. Unlike active_record_doctor's static association check, this
+    # looks at joins that actually ran, so raw-SQL joins are covered too.
+    class UnindexedJoin < Base
+      include IndexPredicates
+
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        true
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          join_columns(scope).each do |table, column|
+            next unless applicable_table?(query, table)
+            next if index_leading_with?(query, table, column)
+
+            detections << detection(
+              query,
+              table: table,
+              columns: column,
+              message: "Join condition on #{table}.#{column} has no index leading with it — " \
+                       "joins on unindexed columns degrade as the tables grow.",
+              suggestion: <<~SUGGESTION.chomp
+                Consider indexing the join column:
+                  CREATE INDEX index_#{table}_on_#{column} ON #{table} (#{column});
+              SUGGESTION
+            )
+          end
+        end
+        detections
+      end
+
+      private
+
+      # Unique [table, column] pairs appearing in cross-table equality
+      # conditions (JOIN ... ON and comma joins connected in WHERE).
+      def join_columns(scope)
+        columns = []
+        scope.stmt.from_clause.each do |item|
+          collect_join_quals(unwrap_node(item)) do |quals|
+            columns.concat(equality_columns(scope, quals))
+          end
+        end
+        columns.concat(equality_columns(scope, scope.where_clause)) if scope.where_clause
+        columns.uniq
+      end
+
+      def collect_join_quals(node, &)
+        return unless node.is_a?(PgQuery::JoinExpr)
+
+        yield node.quals if node.quals
+        collect_join_quals(unwrap_node(node.larg), &)
+        collect_join_quals(unwrap_node(node.rarg), &)
+      end
+
+      def equality_columns(scope, clause)
+        columns = []
+        walk_within_scope(clause) do |node|
+          next unless node.is_a?(PgQuery::A_Expr) && node.kind == :AEXPR_OP && operator_name(node) == "="
+
+          left = unwrap_node(node.lexpr)
+          right = unwrap_node(node.rexpr)
+          next unless left.is_a?(PgQuery::ColumnRef) && right.is_a?(PgQuery::ColumnRef)
+
+          left_resolved = scope.resolve(left)
+          right_resolved = scope.resolve(right)
+          next unless left_resolved && right_resolved
+          next if left_resolved.first == right_resolved.first # same table: not a join condition
+
+          columns << left_resolved << right_resolved
+        end
+        columns
+      end
+    end
+  end
+end