pg_canary 0.1.0

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Searching an array column (@>, <@, &&, or value = ANY(column)) without
+    # a GIN index scans every row.
+    class ArraySearchWithoutGin < Base
+      include IndexPredicates
+
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      ARRAY_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)
+
+            case node.kind
+            when :AEXPR_OP
+              operator = operator_name(node)
+              next unless ARRAY_OPS.include?(operator)
+
+              detections << inspect_sides(query, scope, [node.lexpr, node.rexpr], operator)
+            when :AEXPR_OP_ANY
+              detections << inspect_sides(query, scope, [node.rexpr], "= ANY(column)")
+            end
+          end
+        end
+        detections.compact
+      end
+
+      private
+
+      def inspect_sides(query, scope, sides, operator)
+        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 array_type?(query.column_type(table, column))
+          next if gin_index_on?(query, table, column)
+
+          return detection(
+            query,
+            table: table,
+            columns: column,
+            message: "Array search (#{operator}) on #{table}.#{column} has no GIN index " \
+                     "and will scan every row in production.",
+            suggestion: <<~SUGGESTION.chomp
+              Consider a GIN index on the array column:
+                CREATE INDEX index_#{table}_on_#{column} ON #{table} USING gin (#{column});
+            SUGGESTION
+          )
+        end
+        nil
+      end
+
+      def array_type?(sql_type)
+        sql_type&.end_with?("[]")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # A JOIN with no join condition — an explicit CROSS JOIN between real
+    # tables, or a comma join whose WHERE clause never connects the tables —
+    # produces a cross product whose row count is the product of both sides.
+    class CartesianJoin < Base
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          scope.stmt.from_clause.each do |item|
+            each_join(unwrap_node(item)) do |join|
+              detections << join_detection(query, join) if unconditioned?(join)
+            end
+          end
+          detections << comma_detection(query, scope) if comma_cartesian?(scope)
+        end
+        detections
+      end
+
+      private
+
+      def each_join(node, &)
+        return unless node.is_a?(PgQuery::JoinExpr)
+
+        yield node
+        each_join(unwrap_node(node.larg), &)
+        each_join(unwrap_node(node.rarg), &)
+      end
+
+      def unconditioned?(join)
+        join.jointype == :JOIN_INNER &&
+          join.quals.nil? &&
+          !join.is_natural &&
+          join.using_clause.empty? &&
+          real_table?(join.rarg) &&
+          joinable_side?(join.larg)
+      end
+
+      # Restrict to joins between real tables so that deliberate cross joins
+      # against functions (generate_series etc.) stay silent.
+      def real_table?(node)
+        unwrap_node(node).is_a?(PgQuery::RangeVar)
+      end
+
+      def joinable_side?(node)
+        inner = unwrap_node(node)
+        inner.is_a?(PgQuery::RangeVar) || inner.is_a?(PgQuery::JoinExpr)
+      end
+
+      # FROM a, b (2+ plain tables) with no column-to-column equality in WHERE.
+      def comma_cartesian?(scope)
+        plain_tables = scope.stmt.from_clause.map { |n| unwrap_node(n) }.grep(PgQuery::RangeVar)
+        return false if plain_tables.length < 2
+
+        !cross_table_equality?(scope)
+      end
+
+      def cross_table_equality?(scope)
+        return false unless scope.where_clause
+
+        found = false
+        walk_within_scope(scope.where_clause) do |node|
+          next unless node.is_a?(PgQuery::A_Expr) && comparison_expr?(node)
+
+          left = unwrap_node(node.lexpr)
+          right = unwrap_node(node.rexpr)
+          next unless left.is_a?(PgQuery::ColumnRef) && right.is_a?(PgQuery::ColumnRef)
+
+          left_table, = scope.resolve(left)
+          right_table, = scope.resolve(right)
+          found ||= left_table && right_table && left_table != right_table
+        end
+        found
+      end
+
+      def join_detection(query, join)
+        tables = [join.larg, join.rarg].map { |n| unwrap_node(n) }
+                                       .grep(PgQuery::RangeVar).map(&:relname)
+        build(query, tables)
+      end
+
+      def comma_detection(query, scope)
+        build(query, scope.tables)
+      end
+
+      def build(query, tables)
+        detection(
+          query,
+          table: tables.first,
+          message: "JOIN between #{tables.join(" and ")} has no join condition, producing a cross " \
+                   "product — the result grows with the product of both tables' row counts.",
+          suggestion: "Add a join condition (ON / USING). If a cross product is really intended, " \
+                      "add the table to config.ignore_tables to silence this."
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # A scalar subquery in the SELECT list that references the outer table
+    # runs once per result row (N+1 inside a single query).
+    class CorrelatedSubqueryInSelect < Base
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          scope.stmt.target_list.each do |target|
+            res_target = unwrap_node(target)
+            next unless res_target.is_a?(PgQuery::ResTarget)
+
+            walk_within_scope(res_target.val) do |node|
+              next unless node.is_a?(PgQuery::SubLink) && node.sub_link_type == :EXPR_SUBLINK
+
+              table, column = correlated_reference(node, scope)
+              next unless table && column
+              next unless applicable_table?(query, table)
+
+              detections << detection(
+                query,
+                table: table,
+                columns: column,
+                message: "Scalar subquery in the SELECT list references #{table}.#{column} from the " \
+                         "outer query, so it executes once per returned row.",
+                suggestion: "Rewrite as a JOIN + GROUP BY (or a LATERAL join) so the lookup runs " \
+                            "once as a set operation."
+              )
+            end
+          end
+        end
+        detections
+      end
+
+      private
+
+      # [table, column] of the first outer-scope reference inside the
+      # subquery, or nil when the subquery is self-contained.
+      def correlated_reference(sublink, outer_scope)
+        subselect = unwrap_node(sublink.subselect)
+        return nil unless subselect.is_a?(PgQuery::SelectStmt)
+
+        inner_names = inner_relation_names(subselect)
+        found = nil
+        walk_ast(subselect) do |node|
+          next unless found.nil? && node.is_a?(PgQuery::ColumnRef)
+
+          fields = column_ref_fields(node)
+          next unless fields && fields.length >= 2
+          next if inner_names.include?(fields[-2])
+
+          found = outer_scope.resolve(node)
+        end
+        found
+      end
+
+      # Every relation name/alias visible anywhere inside the subquery.
+      def inner_relation_names(subselect)
+        names = []
+        walk_ast(subselect) do |node|
+          next unless node.is_a?(PgQuery::RangeVar)
+
+          names << node.relname
+          names << node.alias.aliasname if node.alias
+        end
+        names
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): SELECT COUNT(*) without WHERE. Because of MVCC,
+    # PostgreSQL has no O(1) row count — this scans the whole table.
+    class CountStarWithoutWhere < Base
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        true
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          stmt = scope.stmt
+          next if stmt.where_clause || stmt.group_clause.any?
+          next unless count_star?(stmt)
+
+          tables = scope.tables
+          next unless tables.length == 1
+
+          table = tables.first
+          next unless applicable_table?(query, table)
+
+          detections << detection(
+            query,
+            table: table,
+            message: "COUNT(*) without WHERE scans the whole #{table} table — PostgreSQL's MVCC " \
+                     "has no O(1) row count.",
+            suggestion: <<~SUGGESTION.chomp
+              If an approximation is acceptable, use the planner's estimate:
+                SELECT reltuples::bigint FROM pg_class WHERE relname = '#{table}';
+              For exact counts displayed frequently, maintain a counter cache.
+            SUGGESTION
+          )
+        end
+        detections
+      end
+
+      private
+
+      def count_star?(stmt)
+        stmt.target_list.any? do |target|
+          res_target = unwrap_node(target)
+          next false unless res_target.is_a?(PgQuery::ResTarget)
+
+          func = unwrap_node(res_target.val)
+          func.is_a?(PgQuery::FuncCall) && func.agg_star && function_name(func) == "count"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # OFFSET-based pagination reads and throws away every skipped row, so
+    # deep pages degrade linearly. The offset value is read from the runtime
+    # bind ($n), which static SQL linters cannot do.
+    # Threshold: config.rules.deep_offset.threshold (default 1000).
+    class DeepOffset < Base
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def self.options
+        { threshold: 1000 }
+      end
+
+      def check(query)
+        threshold = rule_config(query).threshold
+        detections = []
+        query.each_scope do |scope|
+          next unless scope.stmt.limit_offset
+
+          value = numeric_value(query, scope.stmt.limit_offset)
+          next unless value && value >= threshold
+
+          detections << detection(
+            query,
+            table: scope.tables.length == 1 ? scope.tables.first : nil,
+            message: "OFFSET #{value} reads and discards #{value} rows before returning anything — " \
+                     "offset pagination degrades linearly with page depth.",
+            suggestion: <<~SUGGESTION.chomp
+              Consider keyset pagination instead:
+                WHERE (created_at, id) < (:last_seen_created_at, :last_seen_id) ORDER BY created_at DESC, id DESC LIMIT n
+            SUGGESTION
+          )
+        end
+        detections
+      end
+
+      private
+
+      def numeric_value(query, node)
+        node = strip_type_casts(node)
+        case node
+        when PgQuery::A_Const
+          value = constant_value(node)
+          value.is_a?(Numeric) ? value.to_i : nil
+        when PgQuery::ParamRef
+          begin
+            Integer(query.bind_value(node.number), exception: false)
+          rescue TypeError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Tier 2 (opt-in): DISTINCT combined with JOIN. Frequently the DISTINCT
+    # only exists to undo row fanout caused by the join — the work of
+    # producing and then deduplicating the duplicates is wasted. Legitimate
+    # uses exist, hence opt-in.
+    class DistinctWithJoin < Base
+      def default_enabled
+        false
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def check(query)
+        detections = []
+        query.each_scope do |scope|
+          next unless scope.stmt.distinct_clause.any?
+          next unless joined?(scope)
+
+          detections << detection(
+            query,
+            table: scope.tables.first,
+            message: "DISTINCT combined with JOIN often hides row fanout from the join: duplicate rows " \
+                     "are produced and then sorted/hashed away.",
+            suggestion: "If DISTINCT only compensates for join duplication, rewrite the join as a " \
+                        "semi-join: WHERE EXISTS (SELECT 1 FROM joined WHERE joined.ref_id = t.id)."
+          )
+        end
+        detections
+      end
+
+      private
+
+      def joined?(scope)
+        scope.stmt.from_clause.any? { |item| unwrap_node(item).is_a?(PgQuery::JoinExpr) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # A column wrapped in a function inside WHERE (lower(email) = ?,
+    # date(created_at) = ?) can never use a plain index on that column.
+    # Silent when a matching expression index (same function, same column)
+    # exists.
+    class FunctionOnColumn < Base
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      CHECKED_KINDS = %i[AEXPR_OP AEXPR_LIKE AEXPR_ILIKE AEXPR_IN AEXPR_BETWEEN].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) && CHECKED_KINDS.include?(node.kind)
+
+            [node.lexpr, node.rexpr].each do |side|
+              detections << inspect_side(query, scope, side)
+            end
+          end
+        end
+        detections.compact
+      end
+
+      private
+
+      # The first ColumnRef inside the function call (arguments may nest,
+      # e.g. lower(trim(email))).
+      def first_column_ref(node)
+        found = nil
+        walk_within_scope(node) do |msg|
+          found ||= msg if msg.is_a?(PgQuery::ColumnRef)
+        end
+        found
+      end
+
+      def inspect_side(query, scope, side)
+        func = strip_type_casts(side)
+        return nil unless func.is_a?(PgQuery::FuncCall)
+
+        column_ref = first_column_ref(func)
+        return nil unless column_ref
+
+        table, column = scope.resolve(column_ref)
+        return nil unless table && column
+        return nil unless applicable_table?(query, table)
+
+        func_name = function_name(func)
+        return nil if expression_index?(query, table, column, func_name)
+
+        detection(
+          query,
+          table: table,
+          columns: column,
+          message: "#{table}.#{column} is wrapped in #{func_name}() inside WHERE, " \
+                   "so a plain index on #{column} cannot be used.",
+          suggestion: <<~SUGGESTION.chomp
+            Consider adding an expression index:
+              CREATE INDEX index_#{table}_on_#{func_name}_#{column} ON #{table} ((#{func_name}(#{column})));
+          SUGGESTION
+        )
+      end
+
+      # Matches by (function name, column name) word match against the index
+      # expression SQL — a deliberate approximation that already avoids the
+      # common false positives.
+      def expression_index?(query, table, column, func_name)
+        query.indexes(table).any? do |index|
+          expressions = index.expressions
+          next false unless expressions
+
+          expressions.match?(/\b#{Regexp.escape(func_name)}\s*\(/i) &&
+            expressions.match?(/\b#{Regexp.escape(column)}\b/)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # IN (...) / = ANY(...) with a huge number of values: the statement
+    # itself becomes expensive to parse/plan and usually signals a missing
+    # JOIN. Counts literal list items and runtime array binds, which static
+    # SQL linters cannot see.
+    # Threshold: config.rules.huge_in_list.threshold (default 500).
+    class HugeInList < Base
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      def self.options
+        { threshold: 500 }
+      end
+
+      def check(query)
+        threshold = rule_config(query).threshold
+        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)
+
+            count = value_count(query, node)
+            next unless count && count > threshold
+
+            table, column = resolve_lexpr(scope, node)
+            detections << detection(
+              query,
+              table: table,
+              columns: column,
+              message: "IN / ANY list with #{count} values (threshold: #{threshold}). Huge value lists " \
+                       "are expensive to parse and plan, and usually mean a JOIN is missing.",
+              suggestion: "Rewrite as a JOIN against the source of the values (subquery or VALUES list) " \
+                          "instead of materializing the ids in the query."
+            )
+          end
+        end
+        detections
+      end
+
+      private
+
+      def value_count(query, a_expr)
+        case a_expr.kind
+        when :AEXPR_IN
+          list = unwrap_node(a_expr.rexpr)
+          list.is_a?(PgQuery::List) ? list.items.length : nil
+        when :AEXPR_OP_ANY
+          param = strip_type_casts(a_expr.rexpr)
+          return nil unless param.is_a?(PgQuery::ParamRef)
+
+          value = query.bind_value(param.number)
+          value.is_a?(Array) ? value.length : nil
+        end
+      end
+
+      def resolve_lexpr(scope, a_expr)
+        column_ref = strip_type_casts(a_expr.lexpr)
+        return nil unless column_ref.is_a?(PgQuery::ColumnRef)
+
+        scope.resolve(column_ref)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module PgCanary
+  module Rules
+    # Comparing an integer-family column with a numeric/float literal
+    # (age = 1.5) makes PostgreSQL cast the *column* to numeric, which
+    # disables its index. Restricted to cases provable from the AST alone.
+    class ImplicitCast < Base
+      def default_enabled
+        true
+      end
+
+      def size_dependent?
+        false
+      end
+
+      INTEGER_TYPES = %w[smallint integer bigint].freeze
+      NUMERIC_TYPE_NAMES = %w[numeric decimal float4 float8].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) && comparison_expr?(node)
+
+            detections << inspect_comparison(query, scope, node)
+          end
+        end
+        detections.compact
+      end
+
+      private
+
+      def inspect_comparison(query, scope, expr)
+        left = unwrap_node(expr.lexpr)
+        right = unwrap_node(expr.rexpr)
+
+        column_ref, value = if left.is_a?(PgQuery::ColumnRef)
+                              [left, right]
+                            elsif right.is_a?(PgQuery::ColumnRef)
+                              [right, left]
+                            end
+        return nil unless column_ref
+        return nil unless numeric_literal?(value)
+
+        table, column = scope.resolve(column_ref)
+        return nil unless table && column
+        return nil unless applicable_table?(query, table)
+
+        column_type = query.column_type(table, column)
+        return nil unless INTEGER_TYPES.include?(column_type)
+
+        detection(
+          query,
+          table: table,
+          columns: column,
+          message: "Comparing #{table}.#{column} (#{column_type}) with a numeric literal implicitly " \
+                   "casts the column to numeric, disabling any index on #{column}.",
+          suggestion: "Use a literal that matches the column type (integer)."
+        )
+      end
+
+      # A numeric/float literal, or an explicit cast to numeric of a literal.
+      def numeric_literal?(node)
+        case node
+        when PgQuery::A_Const
+          node.val == :fval
+        when PgQuery::TypeCast
+          type = string_values(node.type_name.names).last
+          NUMERIC_TYPE_NAMES.include?(type) && strip_type_casts(node).is_a?(PgQuery::A_Const)
+        else
+          false
+        end
+      end
+    end
+  end
+end