⚡ Quickstart	⚙️ Usage	🤖 Production automation	🔍 Analyzers	🛡️ Safety model	✅ CI	🧩 Configuration	💼 Pro

schema_reaper reads your live PostgreSQL schema and planner statistics and cross-references them against a static scan of your codebase (Ruby via the Prism AST, plus views and SQL string literals). Optionally it also fuses in a runtime signal — a sampled log of which columns are actually read in production. Every finding is scored by confidence and severity, carries an estimate of the disk it reclaims, and comes with a concrete fix.

It finds three kinds of schema debt:

# Gemfile
gem "schema_reaper"

bundle install
bundle exec schema_reaper scan

In a Rails app that's it — the connection comes from config/database.yml. You get a report like this:

Findings that say the same thing about different tables are rolled up into one entry; when several analyzers flag the same column, the strongest finding wins and notes the others that agreed. schema_reaper never changes your database — it only reads, and hands you migrations to review.

# Gemfile
gem "schema_reaper"

1. database_url: in .schema_reaper.yml
2. ENV["DATABASE_URL"]
3. config/database.yml for the current environment (SCHEMA_REAPER_ENV, then RAILS_ENV, then RACK_ENV, default development) — ERB and YAML aliases are handled, as are Rails 6+ multi-database sections (the primary entry is used)

bundle exec schema_reaper scan                    # grouped terminal report
bundle exec schema_reaper scan --format markdown  # PR-comment table
bundle exec schema_reaper scan --format sarif     # GitHub code scanning
bundle exec schema_reaper scan --format json
bundle exec schema_reaper scan --ci               # exit 1 on findings not in the baseline
bundle exec schema_reaper scan --min-confidence 0.8
bundle exec schema_reaper baseline                # accept current findings
bundle exec schema_reaper trend                   # snapshot + progress delta
bundle exec schema_reaper generate-migration users legacy_api_token

Colour is automatic on a terminal, and off when output is piped or NO_COLOR is set.

The railtie adds these to any Rails app with the gem in its bundle:

New in v2.0. Run schema_reaper unattended in production and have the report land in your team's chat and inbox — no DevOps ticket, and no server access beyond a normal deploy.

bin/rails generate schema_reaper:install

Re-running the generator is safe: every step checks for its own marker and skips itself rather than duplicating anything. Commit the files, deploy, and check it works end to end with one manual run in production:

bin/rails schema_reaper:alert

The generated initializer is commented out, so an unfilled config is a safe no-op, not an error. Uncomment one or both:

SchemaReaper::AlertConfig.configure do |config|
  # config.emails = %w[dev1@example.com dev2@example.com]
  # config.webhook_url = "https://hooks.slack.com/services/T000/B000/XXXX"
end

Both channels fire when both are set — not a fallback chain, but two audiences: a dev-facing chat channel, and an inbox record for people who don't watch chat.

• Webhook — a Slack-compatible {"text": "..."} JSON POST carrying the Markdown report, with a 10-second timeout.
• Email — sent by SchemaReaper::Mailer, which inherits your app's ApplicationMailer (its default from:, delivery settings and so on), or ActionMailer::Base if you don't have one. Delivered with deliver_later.

Delivery failures are logged with a [schema_reaper] prefix and never raised, so a flaky endpoint can't fail or retry-storm the scan.

The generator looks at your Gemfile.lock and uses whichever scheduler you already run. The default cadence is quarterly; edit the generated entry to change it.

rake schema_reaper:alert enqueues the scan on your ActiveJob backend. If that backend is Rails' in-process :async adapter (the default before Rails 8 unless you've set one up), the job would die with the short-lived rake process — so the task runs the scan inline instead, email included.

For "scan now" without shelling into a box:

curl -X POST https://your-app.example.com/internal/schema_scan \
  -H "Authorization: Bearer <token>"

The generator prints the token once, with the exact snippet to paste into bin/rails credentials:edit:

schema_reaper:
  trigger_token: <token>

Credentials are decrypted with the RAILS_MASTER_KEY your app already has, so this adds no new production configuration. The token is checked with a constant-time comparison. The controller deliberately doesn't inherit your ApplicationController and skips CSRF (it's a token-authenticated API endpoint, not a form), so your own auth filters don't apply to it.

Two misconfigurations would otherwise fail silently much later, so the generator flags them when it runs:

• the gem is scoped to group: :development — the scheduled scan would never run in production
• neither ApplicationMailer nor config.action_mailer.default_options sets a from: address — the mailer would fall back to a placeholder sender that most SMTP relays reject, so email reports would never arrive

--format sarif in CI is for PR- and staging-level checks. GitHub-hosted runners have no network path to your production database by default, and a CI database has no production traffic statistics. Production automation is the path for watching the real, live database.

Columns and tables owned by common gems are whitelisted automatically when the gem is in your bundle: devise, devise-api, paper_trail, audited, friendly_id, paranoia / acts_as_paranoid, activestorage, actiontext, pg_search, ahoy_matey and activeadmin.

Static analysis alone can't see metaprogrammed access, so dead_column confidence is capped at 0.6 without runtime data. To lift the cap, sample real column reads:

# config/initializers/schema_reaper_tracker.rb
SchemaReaper::Runtime::Tracker.install!(
  store: SchemaReaper::Runtime::Store.new(path: ".schema_reaper/runtime.jsonl"),
  sample_rate: 0.05
)

or, in Rails, boot with SCHEMA_REAPER_TRACK=1 (and optionally SCHEMA_REAPER_SAMPLE=0.05 for the sample rate). Let it run in staging or production for a couple of weeks. A column unseen in both code and ≥ 14 observed days of runtime data (min_age_days in .schema_reaper.yml) reaches 0.9 confidence (0.8 if it's NOT NULL).

schema_reaper never drops anything itself. For a dead column, generate-migration users legacy_api_token writes a pair:

1. …_ignore_users_legacy_api_token.rb — a no-op migration that reminds you to add self.ignored_columns += %w[legacy_api_token] to the model. Deploy that. Nothing is dropped; ActiveRecord just stops selecting the column.
2. …_drop_users_legacy_api_token.rb — the remove_column. Run it only after step 1 has soaked in production and nothing broke. Its down raises ActiveRecord::IrreversibleMigration on purpose.

The data-driven fixes are cautious too: always_null_column asks you to confirm with a SELECT count(...) first, single_value_column to check the value isn't a meaningful default, and dead_table to rule out external consumers.

# .github/workflows/schema_reaper.yml (the relevant parts)
permissions:
  contents: read
  security-events: write          # required by upload-sarif

# ...job setup: Ruby, a PostgreSQL service, DATABASE_URL...
    steps:
      - run: bin/rails db:schema:load
      - run: bundle exec schema_reaper scan --ci --format sarif > reaper.sarif
      - uses: github/codeql-action/upload-sarif@v4
        if: always()              # upload even when --ci fails the step above
        with: { sarif_file: reaper.sarif }

Commit .schema_reaper/baseline.json (from schema_reaper baseline) so the job fails only when a change adds new dead weight.

Every key is optional. Drop a .schema_reaper.yml in the project root to override any of these defaults.

database_url:          # falls back to DATABASE_URL, then config/database.yml
database_yml: config/database.yml
scan_paths: [app, lib, config]
view_globs: ["app/**/*.erb", "app/**/*.haml", "app/**/*.slim", "app/**/*.jbuilder"]
ignore:
  tables: [schema_migrations, ar_internal_metadata]
  columns: []          # exact names, or "/regex/" patterns
always_keep_columns: [id, created_at, updated_at, type]
gem_awareness: true    # auto-whitelist columns owned by known gems
min_age_days: 14       # days of runtime data before dead_column trusts it
runtime_log: .schema_reaper/runtime.jsonl
history_log: .schema_reaper/history.jsonl
baseline: .schema_reaper/baseline.json
require: []            # extra files to load, e.g. custom analyzers

# lib/schema_reaper/analyzers/my_check.rb
class MyCheck < SchemaReaper::Analyzers::Base
  SchemaReaper::Analyzers::Registry.register(self)

  def call
    schema.tables.filter_map { |t| ... finding(type: :my_check, table: t.name, ...) }
  end
end

# .schema_reaper.yml
require:
  - lib/schema_reaper/analyzers/my_check.rb

• Runtime verdict fusion for index and table findings
• Orphan-row and schema.rb↔DB drift analyzers
• Disk/$ reclaim from real pg_total_relation_size
• Mountable dashboard engine, trend charts
• MySQL adapter

The gem is free and complete for a single app — including the scheduled scans and alerts above. schema_reaper Pro adds the team-scale layer: MySQL adapter, multi-database fan-out, orphan-row and schema-drift analyzers, native Slack/Jira/PR-comment reporters, real pg_total_relation_size + $ estimates, a hosted zero-install scan runner, and a mountable dashboard engine. See PRO.md. Waitlist / early access: open an issue tagged pro.

schema_reaper is MIT and maintained in the open. If it saved you disk, money, or a nasty migration, sponsor its development via the Sponsor button on the repo.

bin/setup
bundle exec rake        # rspec + rubocop

# opt-in: live-database introspection specs
SCHEMA_REAPER_TEST_DATABASE_URL=postgres://localhost/schema_reaper_test bundle exec rspec

MIT.