seq_scanner 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1f0e35a3ccc03dc43a1c23626f5638fa2cc5702a7766d7e26d8fbd0460e07550
+  data.tar.gz: 9a0da447c4dc74af1b032426c6251fbe20f68735c6ce1192505afcfcb693a4d4
+SHA512:
+  metadata.gz: aec043f84166a6a0e0b41d2306f743a276a420181da71835c4f26493c323cb8c5d3c78dab0e134e74682f87a8027c4030e780106101bfc5271d023a6afc82cbd
+  data.tar.gz: 02b1fd9aa29ee300957d73933969ad0ca9c6b6ddd8a681e0da3d344dfb41e7aa48e1476ae3cca9f75968d4bad113df345249ea2ddc2dd8aab4c80e8ea99b06ee

data/.rspec

@@ -0,0 +1,4 @@
+--require 'spec_helper'
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Thomas Broomfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,55 @@
+# SeqScanner
+
+## SeqScanner is a testing tool for ActiveRecord models to verify that your queries are using the correct indexes.
+
+## Overview
+
+In development and test, with a small database, postgres will often use a sequence scan even when there is an index available, making it difficult to verify that your queries will use the correct indexes in production. SeqScanner is a testing tool for ActiveRecord models to verify that your queries are using the correct indexes.
+
+### Installation
+
+Add this line to your application's Gemfile in the test (or development) group:
+
+```ruby
+group :test do
+  gem 'seq_scanner'
+end
+```
+
+### Usage
+
+```ruby
+SeqScanner.scan do
+  User.order(:name).first
+end
+```
+
+This will do the following:
+
+* Tell postgres to not use any sequence scans, if possible.
+
+* Examine the query plan for the given block of code and raise an error if a sequence scan is used.
+
+* Reset postgres to default settings.
+
+Under these conditions, postgres will only use a sequence scan if there is no index that can be used to satisfy the query. This will raise an error if your query would not use the correct index in production.
+
+### In tests
+
+For rspec, you can wrap your tests in a `SeqScanner.scan` block:
+
+```ruby
+RSpec.configure do |config|
+  # ...
+
+  config.around(:each) do |example|
+    SeqScanner.scan do
+      example.run
+    end
+  end
+
+  # ...
+end
+```
+
+This will ensure that all queries in your tests have appropriate indexes.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/seq_scanner/checker.rb

@@ -0,0 +1,42 @@
+require_relative 'query_explainer'
+require_relative 'query_plan'
+
+module SeqScanner
+  class Checker
+    def initialize(**opts)
+      self.queries = []
+      self.explainer = opts.fetch(:explainer) { QueryExplainer }
+    end
+
+    def check_query_plan(&block)
+      subscribe
+      result = block.call
+      unsubscribe
+
+      execute_query_plans.each(&:validate)
+
+      result
+    end
+
+    private
+
+    def execute_query_plans
+      queries.map do |query|
+        QueryPlan.new(query, explainer.explain(query))
+      end
+    end
+
+    def subscribe
+      self.subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |_, _, _, _, details|
+        queries << details
+      end
+    end
+
+    def unsubscribe
+      ActiveSupport::Notifications.unsubscribe(subscriber)
+      self.subscriber = nil
+    end
+
+    attr_accessor :queries, :query_plans, :explainer, :validator, :subscriber
+  end
+end

data/lib/seq_scanner/errors/seq_scan_detected_error.rb

@@ -0,0 +1,32 @@
+require_relative '../plan_formatter'
+require 'paint'
+
+module SeqScanner
+  class SeqScanDetectedError < StandardError
+    def initialize(query_plan)
+      msg = <<~ERROR
+        #{white("Sequential scan detected in query plan for the #{yellow(query_plan.name)} query:")}
+        
+        #{white("Query:")}
+        #{white(query_plan.sql)}
+
+        #{white("Query plan:")}
+        #{PlanFormatter.format(query_plan.query_plan)}
+
+        #{white("Bindings")}
+        #{query_plan.binds.map { |bind| white("#{bind[:name]}: #{bind[:value]}") }.join("\n")}
+      ERROR
+      super(msg)
+    end
+
+    private
+
+    def white(text)
+      Paint[text, :white]
+    end
+
+    def yellow(text)
+      Paint[text, :yellow]
+    end
+  end
+end

data/lib/seq_scanner/plan_formatter.rb

@@ -0,0 +1,16 @@
+require 'paint'
+module SeqScanner
+  module PlanFormatter
+    class << self
+      def format(query_plan)
+        query_plan.map do |line|
+          if line =~ /Seq Scan/
+            Paint[line, :red]
+          else
+            Paint[line, :white]
+          end
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/seq_scanner/query_explainer.rb

@@ -0,0 +1,14 @@
+module SeqScanner
+  module QueryExplainer
+    class << self
+      def explain(query)
+        return false if query[:name] == "SCHEMA"
+        ActiveRecord::Base.connection.unprepared_statement do
+          ActiveRecord::Base.connection.exec_query("EXPLAIN #{query[:sql]}", 'SQL', query[:binds]).to_a.map do |row|
+            row['QUERY PLAN']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/seq_scanner/query_plan.rb

@@ -0,0 +1,42 @@
+require_relative 'errors/seq_scan_detected_error'
+
+module SeqScanner
+  class QueryPlan
+    attr_reader :name, :sql, :binds, :query_plan
+
+    def initialize(input, result)
+      self.sql = input[:sql]
+      self.name = input[:name]
+      self.binds = input[:binds].map do |bind|
+        {
+          name: bind.name,
+          value: bind.value,
+        }
+      end
+      self.query_plan = result
+    end
+
+    def validate
+      return true if schema_migrations?
+      return true unless seq?
+
+      raise SeqScanDetectedError.new(self)
+    end
+
+    private
+
+    def schema_migrations?
+      name == 'SCHEMA'
+    end
+
+    def seq?
+      return true if query_plan.find do |line|
+        line =~ /Seq Scan/
+      end
+
+      false
+    end
+    
+    attr_writer :sql, :name, :binds, :query_plan
+  end
+end

data/lib/seq_scanner/switcher.rb

@@ -0,0 +1,13 @@
+module SeqScanner
+  module Switcher
+    class << self
+      def on
+        ActiveRecord::Base.connection.execute("SET LOCAL enable_seqscan = on")
+      end
+
+      def off
+        ActiveRecord::Base.connection.execute("SET LOCAL enable_seqscan = off")
+      end
+    end
+  end
+end

data/lib/seq_scanner/version.rb

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

data/lib/seq_scanner.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "seq_scanner/version"
+require_relative "seq_scanner/switcher"
+require_relative "seq_scanner/checker"
+# require_relative "seq_scanner/errors/"
+
+module SeqScanner
+  class << self
+    def scan(&block)
+      transact do
+        discourage_seqscan do
+          validate &block
+        end
+      end
+    end
+
+    def discourage_seqscan
+      SeqScanner::Switcher.on
+      yield
+    ensure
+      SeqScanner::Switcher.off
+    end
+
+    private
+
+    def transact
+      # return yield
+      return yield if ActiveRecord::Base.connection.transaction_open?
+      ActiveRecord::Base.transaction { yield }
+    end
+
+    def validate(&block)
+      Checker.new.check_query_plan(&block)
+    end
+  end
+end

data/seq_scanner.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "lib/seq_scanner/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "seq_scanner"
+  spec.version = SeqScanner::VERSION
+  spec.authors = ["Thomas Broomfield"]
+  spec.email = ["tomplbroomfield@gmail.com"]
+
+  spec.summary = "A small ActiveRecord & Postgres extension for managing sequential scans"
+  spec.homepage = "https://github.com/tombroomfield/seq_scanner"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/tombroomfield"
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", ">= 6.1"
+
+  spec.add_dependency "activesupport", ">= 6.1"
+  spec.add_dependency "pg", ">= 1.2"
+  spec.add_dependency "paint", ">= 2.0"
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/sig/seq_scanner.rbs

@@ -0,0 +1,4 @@
+module SeqScanner
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: seq_scanner
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Broomfield
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-11-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: paint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description:
+email:
+- tomplbroomfield@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- LICENCE
+- README.md
+- Rakefile
+- lib/seq_scanner.rb
+- lib/seq_scanner/checker.rb
+- lib/seq_scanner/errors/seq_scan_detected_error.rb
+- lib/seq_scanner/plan_formatter.rb
+- lib/seq_scanner/query_explainer.rb
+- lib/seq_scanner/query_plan.rb
+- lib/seq_scanner/switcher.rb
+- lib/seq_scanner/version.rb
+- seq_scanner.gemspec
+- sig/seq_scanner.rbs
+homepage: https://github.com/tombroomfield/seq_scanner
+licenses: []
+metadata:
+  homepage_uri: https://github.com/tombroomfield/seq_scanner
+  source_code_uri: https://github.com/tombroomfield
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A small ActiveRecord & Postgres extension for managing sequential scans
+test_files: []