rspec-index-usage 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62522b9854e0ad0cd7d84b44dfa1b019f0ebca89a1121837d885e9b5d1782bfe
+  data.tar.gz: 6aa5e60ec2a3247fc07a0a131b2e05e8902c21e589c8e442c54d73b051aba03e
+SHA512:
+  metadata.gz: d848cf6f41f25b8ba1907ae344e65dcdc93f0ebc37d035f21a9326443567e94a5ddb1b038609838d00372177d7d83e3942bc30fc824da924dc5264bf10082b1b
+  data.tar.gz: c087d3c28fa3f1e13ab05ca6137cb8a7dd4c5bd7fef8e1eaca32fa235c09863488463135be21de3de52688535b4af14c3f5e71bf5ddf5899dab94fd6f35b09cb

data/lib/rspec/matchers/have_used_index.rb

@@ -0,0 +1,43 @@
+require 'rspec/matchers'
+require 'uses_index/index_checkers/base'
+require 'active_support/notifications'
+
+RSpec::Matchers.define :have_used_index do |expected_index|
+  supports_block_expectations
+
+  attr_accessor :connection
+
+  chain :on_connection do |conn|
+    @connection = conn
+  end
+
+  match do |block|
+    queries = []
+    subscriber = ActiveSupport::Notifications.subscribe('sql.active_record') do |*args|
+      event = ActiveSupport::Notifications::Event.new(*args)
+      sql = event.payload[:sql]
+      next unless sql
+
+      queries << sql if sql.start_with?('SELECT') && !sql.match?(/\A(EXPLAIN|BEGIN|COMMIT|ROLLBACK)/i)
+    end
+
+    block.call
+
+    ActiveSupport::Notifications.unsubscribe(subscriber)
+
+    connection = @connection || ActiveRecord::Base.connection
+    checker_class = IndexChecker.for_adapter(connection)
+    checker = checker_class.new
+
+    queries.any? { |sql| checker.check_sql(sql, expected_index, connection) }
+  end
+
+  failure_message do |block|
+    "expected the block to execute a query using index '#{expected_index}', but none did"
+  end
+
+  failure_message_when_negated do |block|
+    "expected the block not to execute a query using index '#{expected_index}', but one did"
+  end
+end
+

data/lib/rspec/matchers/use_index.rb

@@ -0,0 +1,20 @@
+require 'rspec/matchers'
+require 'uses_index/index_checkers/base'
+
+RSpec::Matchers.define :use_index do |expected_index|
+  match do |query|
+    # query is an ActiveRecord::Relation
+    connection = query.connection
+    checker_class = IndexChecker.for_adapter(connection)
+    checker = checker_class.new
+    checker.check(query, expected_index, connection)
+  end
+
+  failure_message do |query|
+    "expected query to use index '#{expected_index}', but it didn't"
+  end
+
+  failure_message_when_negated do |query|
+    "expected query not to use index '#{expected_index}', but it did"
+  end
+end

data/lib/rspec-index-usage.rb

@@ -0,0 +1,2 @@
+require_relative 'rspec/matchers/use_index'
+require_relative 'rspec/matchers/have_used_index'

data/lib/rspec_index_usage.rb

@@ -0,0 +1 @@
+require 'rspec-index-usage'

data/lib/uses_index/index_checkers/base.rb

@@ -0,0 +1,23 @@
+class IndexChecker
+  def self.for_adapter(connection)
+    adapter_name = connection.adapter_name
+    case adapter_name
+    when 'SQLite'
+      require_relative 'sqlite' unless defined?(SqliteIndexChecker)
+      SqliteIndexChecker
+    when 'PostgreSQL'
+      require_relative 'postgresql' unless defined?(PostgresqlIndexChecker)
+      PostgresqlIndexChecker
+    else
+      raise "Unsupported database adapter: #{adapter_name}. Currently supports SQLite and PostgreSQL."
+    end
+  end
+
+  def check(query, expected_index, connection = ActiveRecord::Base.connection)
+    raise NotImplementedError, 'Subclasses must implement check'
+  end
+
+  def check_sql(sql, expected_index, connection = ActiveRecord::Base.connection)
+    raise NotImplementedError, 'Subclasses must implement check_sql'
+  end
+end

data/lib/uses_index/index_checkers/postgresql.rb

@@ -0,0 +1,16 @@
+require_relative 'base'
+
+class PostgresqlIndexChecker < IndexChecker
+  def check(query, expected_index, connection = ActiveRecord::Base.connection)
+    sql = query.to_sql
+    check_sql(sql, expected_index, connection)
+  end
+
+  def check_sql(sql, expected_index, connection = ActiveRecord::Base.connection)
+    explain_sql = "EXPLAIN #{sql}"
+    result = connection.execute(explain_sql)
+    plan = result.map { |row| row[0] }.join("\n")
+    plan.include?(expected_index)
+  end
+end
+

data/lib/uses_index/index_checkers/sqlite.rb

@@ -0,0 +1,16 @@
+require_relative 'base'
+
+class SqliteIndexChecker < IndexChecker
+  def check(query, expected_index, connection = ActiveRecord::Base.connection)
+    sql = query.to_sql
+    check_sql(sql, expected_index, connection)
+  end
+
+  def check_sql(sql, expected_index, connection = ActiveRecord::Base.connection)
+    explain_sql = "EXPLAIN QUERY PLAN #{sql}"
+    result = connection.execute(explain_sql)
+    plan = result.map { |row| row.values.join(' ') }.join(' ')
+    plan.include?(expected_index)
+  end
+end
+

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: rspec-index-usage
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Pedro Sena
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: Provides RSpec matchers that verify whether ActiveRecord queries or code
+  blocks use specific database indexes by examining execution plans. Supports SQLite
+  and PostgreSQL.
+email: sena.pedro@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rspec-index-usage.rb
+- lib/rspec/matchers/have_used_index.rb
+- lib/rspec/matchers/use_index.rb
+- lib/rspec_index_usage.rb
+- lib/uses_index/index_checkers/base.rb
+- lib/uses_index/index_checkers/postgresql.rb
+- lib/uses_index/index_checkers/sqlite.rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/PedroSena/rspec-index-usage
+  source_code_uri: https://github.com/PedroSena/rspec-index-usage
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: RSpec matcher to check database index usage in queries
+test_files: []