SeedTracker 🌱

SeedTracker transforms your db/seeds.rb from a silent script into a clear, structured, and self-reporting process.

If you are tired of writing repetitive puts statements to figure out what your db/seeds.rb file actually did (what was created, updated, or left unchanged), SeedTracker provides a clean DSL and a beautiful summary output out-of-the-box.

Rails seeds are often:

• Silent
• Hard to debug
• Difficult to audit
• Unclear about what actually changed

SeedTracker solves this by turning your seeding process into a predictable and observable workflow.

• 🚀 Lightweight: No runtime dependencies beyond Rails.
• 📊 Automated Summaries: Get a final report with counts of created, updated, and unchanged records per category.
• 🔍 Smart Diffing: It leverages ActiveRecord dirty tracking to detect exactly which attributes changed before saving.
• 💅 Visual Sections: Group your seed logs into readable, elegant blocks.

• Ruby >= 3.0
• Rails >= 6.0

Add this line to your application's Gemfile:

gem 'seed_tracker'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install seed_tracker

Instead of relying on find_or_create_by! (which may silently create records without visibility into what changed), SeedTracker works best with find_or_initialize_by.

Here is how you can use it in your db/seeds.rb:

# 1. Initialize the tracker
tracker = SeedTracker::Base.new

puts "Running Seeds..."

# 2. Group your seeds using 'section'
tracker.section("PACKAGES") do
  
  # 3. Use 'track' to process your records
  # track(category_symbol, initialized_record, human_readable_label)
  tracker.track(:packages, Package.find_or_initialize_by(category: :basic), 'Basic Package') do |p|
    p.name = 'Basic'
    p.price = 9.99
  end

  tracker.track(:packages, Package.find_or_initialize_by(category: :premium), 'Premium Package') do |p|
    p.name = 'Premium'
    p.price = 19.99
  end

end

tracker.section("PLANS") do
  # You can also assign the returned record to a variable to use it in associations
  basic_package = Package.find_by(category: :basic)

  tracker.track(:plans, Plan.find_or_initialize_by(period: :monthly, package: basic_package), 'Basic Monthly Plan') do |p|
    p.name = 'Monthly'
    p.active = true
  end
end

# 4. Print the final summary dashboard at the end of the file
tracker.print_summary

When you run rails db:seed, you will get a beautiful, detailed output in your terminal:

Running Seeds...

PACKAGES

      CREATED: Basic Package
      UPDATED: Premium Package (Fields: price)

PLANS

      UNCHANGED: Basic Monthly Plan

================================================================================
SEEDING SUMMARY
================================================================================

PACKAGES:
   Created: 1
   Updated: 1
   Unchanged: 0
   Total: 2

PLANS:
   Created: 0
   Updated: 0
   Unchanged: 1
   Total: 1

================================================================================
✅ Seeding completed successfully!
================================================================================

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/pablosxz/seed_tracker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.