Skip to content
Bullematic

A Ruby gem for your Rails workflow

Fix N+1 queries detected by Bullet.

Bullematic adds eager loading to supported Active Record queries using Bullet's runtime detections. Preview the changes before applying them.

Get started Read the docs

Open source. MIT licensed. Made for development and test.

A warning. A focused fix. Example
posts_controller.rb 
class PostsController < ApplicationController
  def index
    @posts = Post.all
  end
end

Bullet detected N+1

Post => [:comments]

Bullematic adds the missing eager load

After applying the fix

@posts = Post.includes(:comments).all

For a direct query with a verified association.

Fits the stack you already use

  • Ruby 3.1+
  • Rails
  • Bullet 6–8
  • RSpec
  • Minitest

From a Bullet warning
to a change you can ship.

Run the code you already test. Review the proposed fix. Apply it, then check the result with the same command.

  1. 1

    Record

    Capture Bullet detections and their call sites while your tests or app run.

    bullematic record -- …

  2. 2

    Preview

    Inspect the planned changes before writing anything to your source files.

    bullematic plan

  3. 3

    Apply

    Rewrite supported queries with Prism. Keep a backup of the original file.

    bullematic apply

  4. 4

    Verify

    Rerun the recorded command and check for remaining N+1 warnings.

    bullematic verify

Small code changes.
Clear boundaries.

Bullematic works from what Bullet observes at runtime. It matches a detection to a query, verifies the association, and rewrites the Ruby syntax tree.

includes preload eager_load
Preview first, apply when ready
Dry-run mode is on by default. Choose your target paths, skip paths, and eager-loading strategy.
A focused fix, backed by evidence
Direct Active Record queries with a clear origin and a verifiable association are candidates for a fix.
Uncertain cases stay with you
Ambiguous origins, dynamic scopes, memoized relations, and cross-method or cross-file relation builders are skipped.

Your next N+1 fix
starts here.

Add Bullematic to a Rails app where Bullet already runs in development or test.

Using RSpec or Minitest? Enable the matching integration before recording your test run.

Set up your integration

Requires Ruby 3.1+ and Bullet 6.0–8.x.

Add to your Gemfile

gem 'bullematic', group: [:development, :test]

Install, then record and review

bundle install

# After setting up your test integration
bundle exec bullematic record -- bundle exec rspec
bundle exec bullematic plan

# When you're ready to write the changes
bundle exec bullematic apply
bundle exec bullematic verify

Review the changes and rerun your tests before committing. Explore configuration