Herb changes that. On August 25, 2026, the Ruby on Rails core team merged Add Herb as an HTML-aware ERB implementation, which brings in Herb, an ERB implementation that parses HTML and ERB into a single syntax tree and uses Prism for the Ruby inside the tags. Broken markup can now fail while the template compiles, instead of reaching a browser.

In this article, you will learn what Herb is, how to audit your own views with it today, what it can fix for you, what it cannot, and what it costs to run. We used the FastRuby.io views as the test subject.

What Herb actually is

Herb is not one tool, it is a parser with a lot of things built on top of it. The parser is written in C, it handles HTML and ERB together, and it hands the Ruby inside the tags to Prism. Everything else in the project is a consumer of that one syntax tree. We have leaned on syntax trees for this kind of work before, when we extracted every deprecation warning out of the Rails source, and the appeal is the same: a parser knows things a regular expression can only guess at.

That second half is easy to overlook. Every <% %> tag in your application gets parsed as Ruby, including the ones inside branches that almost never render. GitHub found invalid Ruby this way while adopting Herb, in template code they had never run outside of production. If your views have accumulated conditionals for states nobody has hit in years, that Ruby has probably never been parsed by anything.

The gem installs a CLI that exposes most of it:

Some of those delegate to Node packages under the hood, so the linter and formatter are the same code whether you reach them from Ruby or from npx.

That shared parser is the part worth understanding, because it is what makes the Rails change more than a swapped dependency. Your editor, your linter, your formatter, and now your template compiler can all agree on what a template means.

Herb v0.9 added a set of erb-safety-* rules that cover the security checks from better-html and erb_lint, which matters if you have been relying on either of those.

Running Herb on our own views

Install the gem and point it at your views:

gem install herb
herb analyze app/views

It parses every template, tries to compile each one, and groups what it finds into sections. The ten possible sections are in the table below, and which ones you see depends on what is wrong with your templates:

Our run against the FastRuby.io views identified the five marked in the first column, along with twenty-one templates containing issues. This is a reasonable outcome for an application whose views have been accumulating since 2017.

What caught my attention was the “Reportable issues” block Herb prints after those sections. It pulls out the files that landed in the categories it treats as probable bugs in itself, under a note saying they “likely failed due to issues in Herb, not in your templates”. Two of ours landed there, both from the unexpected parse errors row. That seems like a good way to make the Herb gem more robust over time, and the CLI hands you both halves of the job, one to share as an issue and the other to debug it yourself:

herb report prints a Markdown bug report with the gem, Prism, and libherb versions, your Ruby and platform, the categorized error list, and the template source, ready to paste into an issue.

herb playground compresses the template into the fragment of a URL and opens it in the playground, where you can inspect the tree the parser built and the diagnostics it produced. Browsers do not send the fragment part of a URL to the web server, so the template travels no further than your own browser, which matters when the file belongs to a client.

As for the errors themselves, they are readable. Here is one of ours:

Analyze parse errors:
 These files have issues detected during analysis. Review the errors and update your templates.

 app/views/static/rails_3_0_vulnerabilities.html.erb:
   ⚠ MissingClosingTagError at 18:2 - Opening tag `<section>` at (18:3) doesn't have a matching closing tag `</section>` in the same scope.
   ⚠ MissingOpeningTagError at 2131:2 - Found closing tag `</section>` at (2131:4) without a matching opening tag in the same scope.
   ⚠ MissingOpeningTagError at 2132:0 - Found closing tag `</div>` at (2132:2) without a matching opening tag in the same scope.

The run ends with a summary that counts how many files were checked, how many came out clean, and separate tallies for the parser and the engine. Those two tallies are worth reading separately, since “parses but will not compile” and “will not parse at all” are different problems with different fixes.

What you can fix automatically

herb analyze tells you what is broken. Fixing the smaller stuff is the linter’s job:

herb lint "app/views/**/*.erb"
herb lint "app/views/**/*.erb" --fix

On our views that found 1,404 offenses, 547 of them autocorrectable: unescaped entities, indentation, spaces inside tags, missing trailing newlines. What --fix will not touch is anything structural. The 143 offenses from parser-no-errors, the rule that overlaps with what stops a template from compiling, are all yours to fix by hand, and that is the right call, since an extra </div> could mean “delete this line” or “add the opening tag twenty lines up”.

Both commands run on defaults until you give them a config, which you generate with:

herb lint --init

That writes a .herb.yml file that pins the Herb version, so a later upgrade does not enable new rules behind your back. The rest of the file is commented out but worth reading through once. You can enable or disable individual rules, exclude paths for specific rules, set the severity that causes the run to fail, toggle the security, nesting, and accessibility validators, and choose the template engine, with herb as one of the options.

What you get, and what it costs

From your application’s rendering point of view, Herb and Erubi are the same thing: same public API, same job, no templates to rewrite.

What changes is the tooling around them. Because the herb gem is now a dependency of actionview, the analysis, the linter, the formatter, the render graph, and the language server all come along with it. Some of that existed before as third-party gems, erb_lint and better-html among them, but none of it shipped with Rails, so nobody has to be talked into adding a gem for good practices.

The review thread points at Herb arriving opt-in first and becoming a framework default in some later version. That is reason enough to get ahead of it. Run the linter now, check that your views compile through Herb, and wire it into CI alongside RuboCop or whatever else you already run there, so the work happens before the release day instead of after it. A missing closing tag stops being something a reader finds for you months later.

The trade is compile time. Herb does more work than Erubi, so a template takes longer to compile, and on our views the difference is measured in milliseconds per template.

Where that lands is the part worth understanding. Rails compiles a template the first time something renders it and caches the compiled method for the life of the process, so the cost is paid once per template. Every request after that is identical, because the Ruby that Herb generates is the same Ruby, byte for byte. Nothing about serving a page is slower once the template has been compiled.

It is also early days. Marco Roth, who built Herb, has noted that it has not had much performance optimization yet, and that he believes it can be improved.

Conclusion

We pointed Herb at an application whose views have been accumulating since 2017, and it found real problems in twenty-one templates, including markup we had been shipping for years. The run took a few seconds and needed nothing beyond a gem install.

That is what we would suggest doing now, well before any of this becomes a default. Views are where upgrade work tends to hide, and we have written before about ERB syntax changes catching teams mid-upgrade. Herb has earned a spot next to the open source tools we already reach for on upgrades. The linter will clear the cosmetic offenses for you, the structural ones are hand work, and knowing which is which is most of the planning. Once you have cleared them, both herb analyze and herb lint exit non-zero when something fails, so either one can sit in CI and keep the next broken template out of the branch.

Marco Roth is presenting Herb in Rails 8.2: Your ERB views, now HTML-aware at Rails World on September 24.

Is your team getting ready for the next version of Rails, or still catching up on the last one? We can help!

I set up a small application on edge Rails to check it working. The routing and the request object are ready, but the parts of the specification that make QUERY more than a POST with better manners are not quite there yet, since Rails parses only JSON bodies and does not enforce the content type rule RFC 10008 requires. In this article, we will check how the QUERY method works in Rails, how to route and test it, how Puma is handling it, and which pieces of the specification are still missing. Everything below reflects the state of things at the beginning of September 2026, and since Rails, Rack, and Puma all have the interesting parts sitting on unreleased branches, it is worth checking the versions yourself before trusting any of it.

What the QUERY method is

RFC 10008 became a Proposed Standard in June 2026. It defines QUERY as a request method that is safe and idempotent with regard to the target resource, and that carries content in the request body.

That combination is the part neither GET nor POST can offer. It is worth noting that a GET with a body is not actually illegal, it is just that nothing useful is defined for it. RFC 9110 section 9.3.1 puts it plainly: a payload in a GET “has no defined semantics”, and sending one “might cause some implementations to reject the request”. A POST carries the body reliably, and it also announces to every cache and every client library that the request may have changed something on the server, so nothing retries it automatically. Its responses are cacheable in principle, but only with the cache control headers that section 9.3.3 requires, which is not something a typical search endpoint sets up.

Back in RFC 10008, a few details are worth knowing before you reach for it. Servers MUST fail the request if the Content-Type field is missing or is inconsistent with the request content (section 2). Responses are cacheable, but the cache key MUST incorporate the request content (section 2.7), which is a harder problem for a shared cache than hashing a URL. Section 3 defines an Accept-Query response header so a resource can advertise which query format media types it accepts, although Rails does not implement that part yet.

Those are the mechanics, and the specification is just as explicit about why you would want the query in the body to begin with. Size is the obvious half, since every proxy and CDN in front of you picks its own URL length limit. The other half is exposure, and it is worth being precise about: a URI is “more likely to be logged or otherwise processed by intermediaries than the request content”. This is not an encryption argument, because under TLS the path and query travel inside the same tunnel as the body. It is that a URI ends up in access logs, proxy logs, browser history, and Referer headers, and a request body usually ends up in none of them. In section 4, it follows the thought through: if a server mints a URI to represent the results of a QUERY, that URI SHOULD NOT contain sensitive portions of the original request content.

WebDAV defined SEARCH back in 2008 at RFC 5323, and ActionDispatch::Request has recognized it for years, in the same HTTP_METHODS list that QUERY now joins a few lines below it. And now QUERY has one advantage SEARCH never had: it is a general-purpose HTTP method rather than a WebDAV extension.

Routing a QUERY request

Rails 8.2 adds a query route helper that sits alongside get and post. It is a thin wrapper that delegates straight to match with via: :query, so you can write it either way. Here is the routes file from the small application I set up to test it:

# config/routes.rb
Rails.application.routes.draw do
  query "search", to: "search#index"
  match "filter", to: "search#filter", via: :query
end

bin/rails routes then reports the verb the same way it reports any other:

Prefix Verb  URI Pattern         Controller#Action
search QUERY /search(.:format)   search#index
filter QUERY /filter(.:format)   search#filter

These routes are scoped to the verb, which is worth spelling out because it is easy to assume otherwise when you are used to resources generating several verbs for one path. A GET to /search does not fall through to the QUERY action, it just does not match, and neither does a POST. Both come back as a 404 while the QUERY request returns a 200. The named helpers work as usual, so search_path is there alongside them.

The pull request notes that the helper also works inside resources blocks with on: :collection and on: :member, but the resources shortcuts themselves were left out of scope, so there is no generated QUERY route yet.

What the request object gives you

Inside the controller, QUERY behaves like any other verb. request.query? does what you would expect, and request.request_method_symbol returns :query. More useful is request.safe_method?, which now returns true for QUERY alongside GET, HEAD, OPTIONS, and TRACE, with request.unsafe_method? as its inverse. If you have written a middleware or an audit log that branches on whether a request is allowed to change state, that predicate is a better thing to call than a hand-maintained list of verbs.

The controller I tested does nothing but echo back what the request reports:

# app/controllers/search_controller.rb
class SearchController < ApplicationController
  def index
    render json: {
      method: request.request_method,
      method_symbol: request.request_method_symbol,
      query?: request.query?,
      safe_method?: request.safe_method?,
      filters: params[:filters]
    }
  end
end

Sending it a QUERY request with a JSON body gives back:

{
  "method": "QUERY",
  "method_symbol": "query",
  "query?": true,
  "safe_method?": true,
  "filters": { "status": "active" }
}

Notice where filters came from, it arrived in the request body rather than the query string, and it landed in params anyway. That is ActionDispatch::Http::Parameters#parse_formatted_parameters doing the work, picking a parser out of DEFAULT_PARSERS based on the request’s content type without ever looking at the verb, and #parameters then merging what comes back together with the query string and the path parameters.

That dependency on the content type cuts both ways. RFC 10008 says a server MUST fail the request when the Content-Type is missing or inconsistent with the content, and Rails does not do that, so on this point the implementation is not yet spec compliant. A QUERY request with no Content-Type at all comes back as a 200 with an empty params and the body quietly discarded. The only parser Rails registers by default is the JSON one, since form data is handled upstream by Rack, so anything else gets dropped the same way: an application/sql body never reaches params at all, which is worth knowing given that the RFC has exactly those structured query formats in mind. A body that contradicts its declared type does fail, but as a 400 from the parameter parser rather than as anything QUERY-specific.

Testing it

Integration tests get a query helper that mirrors get and post, so the test reads like any other request test:

# test/integration/query_method_test.rb
class QueryMethodTest < ActionDispatch::IntegrationTest
  test "routes a QUERY request and parses the JSON body" do
    query "/search", params: { filters: { status: "active" } }, as: :json

    assert_response :success
    body = JSON.parse(response.body)
    assert_equal "QUERY", body["method"]
    assert_equal true, body["query?"]
    assert_equal true, body["safe_method?"]
    assert_equal({ "status" => "active" }, body["filters"])
  end

  test "the same path does not answer GET or POST" do
    get "/search"
    assert_response :not_found
    post "/search"
    assert_response :not_found
  end
end

Controller tests do not get a dedicated helper, but process takes the method explicitly with process :index, method: "QUERY". One thing to watch there: a controller test written that way sends its params as application/x-www-form-urlencoded unless you say otherwise, so it will not exercise the JSON parsing path that your actual client uses.

QUERY and CSRF protection

Because QUERY is safe, Rails exempts it from forgery protection the same way it exempts GET and HEAD. The exemption is narrower than it first looks, though. As the comment in the source puts it, QUERY requests are exempt “but only when the request actually arrived with the QUERY method”, which is why the predicate checks two things that look like the same thing:

# actionpack/lib/action_controller/metal/request_forgery_protection.rb
def verified_request?
  request.get? || request.head? || verified_query_request? || !protect_against_forgery? ||
    (valid_request_origin? && verified_request_for_forgery_protection?)
end

def verified_query_request?
  request.query? && request.method == "QUERY"
end

The difference is that request_method reflects the method after any override has been applied, while request.method reads rack.methodoverride.original_method first and only falls back to REQUEST_METHOD, so it reports the method the request actually arrived with. The rationale for exempting genuine QUERY requests is that an HTML form cannot emit one, and that a cross-origin QUERY from JavaScript is always preflighted. Neither of those holds for a form POST carrying an override parameter.

Whether that guard does anything depends on which Rack you are running, which took me a failing test to work out. On Rack 3.2.7, the current release, Rack::MethodOverride::HTTP_METHODS does not list QUERY, so a form posting _method=query is ignored outright: the request stays a POST, request.query? is false, and it needs a token for the ordinary reason rather than the QUERY-specific one. On Rack main that constant does list QUERY, and ALLOWED_METHODS is still just POST, so the override goes through and the Rails predicate is the thing standing between a plain form submission and a skipped CSRF check.

An open pull request proposes dropping QUERY from the _method form parameter while keeping it available through the X-HTTP-Method-Override header, on the grounds that a custom header always forces a CORS preflight and a form parameter does not.

Puma has to allow it first

Everything above works in tests, and tests run the Rack application directly. Rails reads REQUEST_METHOD out of the Rack env and trusts it, so as far as Rails is concerned the method is whatever the server handed over. That makes the server the real gatekeeper, and the current release of Puma does not let QUERY through.

Puma keeps an allowlist, which it introduced in Puma 6 and made configurable after the WebDAV crowd pointed out what it broke. On Puma 8.0.2, Puma::Const::SUPPORTED_HTTP_METHODS holds HEAD, GET, POST, PUT, DELETE, OPTIONS, TRACE, and PATCH, and nothing else. Send a QUERY request to a default Puma and it never reaches your routes:

HTTP/1.1 501 Not Implemented

Puma caught this error: QUERY method is not supported (Puma::HttpParserError501)
.../puma-8.0.2/lib/puma/client.rb:305:in 'Puma::Client#parser_execute'

We can allow it with one line in config/puma.rb, using the supported_http_methods option Puma exposes for exactly this:

# config/puma.rb
supported_http_methods Puma::Const::SUPPORTED_HTTP_METHODS + ["QUERY"]

With that in place the same request reaches the controller and comes back with a 200. Passing supported_http_methods :any also works and turns the check off completely, which is worth avoiding if you can just name the methods you serve.

Treat that line as a stopgap rather than something to keep, because Puma has already fixed this upstream. On main, both SUPPORTED_HTTP_METHODS and IANA_HTTP_METHODS list QUERY, annotated with QUERY added based on https://www.rfc-editor.org/rfc/rfc10008.html, which means version 8.0.3 will accept QUERY with no configuration at all.

That fix is also a good illustration of how the pieces had to line up. In the Rails pull request, Sean Doyle raised the point that support needs coordinating across Rack, Puma, and nginx, and then wrote it: the Rack change landed on July 12, 2026 and the Puma change the day before. The part nobody can patch for you is the rest of the path. If you have a CDN, a load balancer, or an nginx in front of the application, each one has its own opinion about methods it does not recognize.

Conclusion

In this article we talked about the QUERY method from RFC 10008, the query route helper and its match via: :query equivalent, the request.query? and request.safe_method? predicates, the query integration test helper, and why Rails exempts genuine QUERY requests from CSRF protection but not the ones tunneled through a form POST.

The support was merged on August 14, 2026 and sits on main under the 8.2.0 milestone.

SEARCH got recognized and then went nowhere: Action Dispatch has accepted it for years and Puma lists it among the IANA methods, but it never made Puma’s default allowlist. QUERY has had Rack, Puma, and Rails all land support inside about five weeks, and Puma took it straight into the defaults.

Is your application several versions behind, with even the upgrade from Rails 8.0 to 8.1 still ahead of you? Send us a message, we can help!

Its website, icu.ie, has been maintained by webmaster Jonathan O’Connor since 2015. Earlier this year, Jonathan reached out to us. He wanted help taking the ICU’s Rails application from 7.0 to 8.1.

We used Claude Code and our open source Claude Code Rails Upgrade Skill to get it done. We also recorded the sessions as a video series, so other teams could see the methodology in practice.

In this article, we’ll walk through the upgrade, one version at a time, and share what Jonathan thought of the process.

Here was our challenge

The ICU’s application was built and is maintained by professionals, just not on the clock. Everyone involved works on it nights and weekends, as volunteers. It was written mostly by Mark Orr, a ratings officer who had just retired and wanted to give back to the community.

That project became learning Ruby on Rails and building the ICU a website from scratch. He wrote about 90% of the code that’s still running today. Jonathan took over as webmaster in 2015.

He’d learned Ruby a few years earlier, on a six-week trip to Rwanda building credit card payment systems. Rails’ conventions weren’t as disorienting to him as they are to developers who come to it cold.

He kept the application current on his own for a while. When he upgraded it from Rails 3 to 5, he did it the patient way: bumping the Gemfile one patch version at a time, running the test suite, and fixing whatever the deprecation warnings in the logs pointed at.

His colleague Ben Murray later carried it from 5.0 to 7.0. Then Jonathan tried to take it from 7.0 to 7.1 by himself. The same approach that had worked for years stopped working.

He’d been away from daily Rails work since 2016. The deprecation warnings piled up faster than he could make sense of them.

“It was a lot harder,” he said. Eventually it became impossible to tell which warnings actually mattered.

Here’s how we solved it

We used the same methodology we’ve documented for years: dual-boot the app with the next_rails gem, and upgrade one minor Rails version at a time, never skipping a hop.

For the ICU, that meant an unhurried climb from 7.0 to 7.1, then 7.2, then 8.0, and finally 8.1. Each hop got its own pull request. Each one had a green test suite against both Rails versions before we merged it and moved to the next.

Here’s what that looks like under the hood, for anyone who hasn’t dual-booted a Ruby app before:

Before we touched the Rails version at all, we spent some time on groundwork.

We set up GitHub Actions, so the ICU had CI for the first time. We patched the Docker configuration, so the app could build against either Gemfile.

That kind of scaffolding is easy to underestimate. It’s usually what makes the rest of the upgrade boring, in a good way.

This was also a great opportunity to share with the community how we leverage our open source Claude Code Rails Upgrade Skill, instead of just publishing it and hoping people would try it themselves. In 3 different pairing sessions, we drove Claude to use the skill to handle the mechanical work that happens in every upgrade project.

Claude handled a lot of the mechanical work in each hop: previewing what rails app:update would change, running the test suite against both Gemfiles, and flagging deprecation warnings before they piled up.

Our engineers, Henrique Medeiros, Ariel Juodziukynas, Aysan Isayo, and Juan Vasquez, made the judgment calls the skill is deliberately not built to make on its own.

One of those calls was a small shim in the ICU’s codebase. Even Jonathan, after nearly a decade of maintaining the app, said he never would have found it on his own.

“There’s one thing I would never have found, even if I kept working at trying to figure out how to do the upgrade myself, and that was this shim in our code,” Jonathan said. “I think that’s one of the places where you earn your keep, because these are tricks that people won’t know, since they’re not doing upgrades every day.”

Part of why the rest of the upgrade went smoothly is that the ICU’s codebase is, in Jonathan’s own words, unusually well-behaved.

No monkeypatches. No reopened core classes. No weird code in weird places.

And on top of that: A real test suite with both model and integration coverage.

None of that is guaranteed for an application built by a single volunteer. But Mark Orr and Jonathan had both stuck close to the Rails way, and it showed in how predictable each hop turned out to be.

The ICU never had to pause its own work, either.

Jonathan’s small team of volunteer contributors kept shipping features throughout the upgrade. The app’s Stripe integration, the dependency that worried us most going in since it handles ICU’s membership payments, never broke stride.

See the results

Now the ICU is current on Rails 8.1.

“I didn’t notice any issues at all. There were no breakages at all. You made maybe seven or eight pull requests, probably thirty or forty commits over that time, and they just fitted seamlessly into all our changes. Nothing ever broke. And thank you so much for setting up our Docker, because now we have our tests running on GitHub, which is brilliant.”

Jonathan O’Connor, Webmaster, Irish Chess Union

Here’s one of those pull requests, upgrading the app to Rails 7.2:

Eight pull requests, somewhere around thirty to forty commits, and zero breakages.

That’s not a coincidence. It’s what a sequential, dual-booted upgrade against a clean codebase and a stable test suite looks like when it goes right.

There’s also a quieter story here, about who can afford this kind of work.

A volunteer-run federation with no engineering budget to speak of got a five-version Rails upgrade done. Not because the work got easier, but because one senior engineer driving Claude Code and our upgrade skill can now get much closer to what it used to take two.

This is a real shift we’re seeing across our upgrade engagements, and it’s a big part of why an organization like the ICU can now afford this kind of work at all.

If you’re trying to make this case internally, here’s some advice on how to pitch a Rails upgrade to your boss.

Watch the pairing sessions

We recorded four sessions from this project, so you can watch the actual pairing work instead of just reading about it.

Part 1: Setting up CI

Henrique Medeiros and I spend about an hour setting up CI for the ICU’s application: wiring up GitHub Actions and using Claude Code to work through the setup issues that came up along the way:

Part 2: Dual booting and API compatibility

Henrique and I dig into dual booting and the API differences between Rails 7.0 and 7.1.

We set up next_rails and a Gemfile symlink strategy, chase down a few gem compatibility issues using RailsBump.org, and configure GitHub Actions and Docker to run the test suite against both Rails versions:

Part 3: Upgrading to Rails 7.2, and getting ready for 8.0

Juan Vasquez and I carry the app from Rails 7.1 to 7.2, while preparing the codebase for Rails 8.0.

We walk through how the upgrade skill checks the current patch version, confirms dual boot is set up, and generates an upgrade report, then track down a Capybara and Selenium WebDriver compatibility issue that turns out to have nothing to do with Rails itself:

Recap: A quick recap of the entire upgrade project

Jonathan and I talk about the project end to end: the ICU’s volunteer culture, why the upgrade stalled at Rails 7.1, the results, and Jonathan’s own take on where AI helps and where he still won’t let it near ICU’s data.

Keep an eye out for the Easter egg: a shim in the ICU’s codebase that Jonathan says he’d never have thought of himself.

Conclusion

The ICU’s upgrade worked because the methodology did the heavy lifting, not the AI on its own. Our AI tooling certainly help speed things up! 🚀

Dual booting, sequential hops, a deprecation-first approach: none of that is new.

What’s new is that Claude Code, guided by a skill that encodes those opinions, can now execute most of it, while our engineers focus on the handful of judgment calls, like that one shim, that still need a human who’s done this before.

It’s worth saying plainly: this went smoothly in part because the ICU’s codebase was clean and well-tested.

A messier application, full of monkeypatches and flaky tests, would have taken longer.

Has your team been putting off a Rails upgrade? Let’s talk and get your up to the latest stable versions of Ruby and Rails!

References

All of the pull requests below were merged into the ICU’s master branch, and the full history is public:

• #117: Remove deprecation warnings
• #134: Set up GitHub Actions
• #145: Docker setup configuration patches
• #150: Dual boot the application (Rails 7.0 and 7.1)
• #152: Upgrade to Rails 7.1
• #157: Upgrade to Rails 7.2
• #165: Upgrade to Rails 8.0
• #184: Upgrade to Rails 8.1

You can find the ICU’s full application source code at github.com/irishchessunion/icu_www_app, and our own upgrade skill at github.com/ombulabs/claude-code_rails-upgrade-skill.

If you want the version-by-version details behind each hop, our Rails Upgrade Series covers every jump from 2.3 onward.

Staying in control of when that happens beats finding out on Heroku’s schedule, so I upgraded it that same night. I skipped the method Heroku recommends for a documented one that suited this database better, and still finished the job with commands that are not in their documentation.

In this article, you will learn how we moved a Heroku Postgres database off a deprecated version, why we copied the data into a new database instead of upgrading in place, how much downtime to plan for, and which parts of Heroku’s tooling failed on us. We upgraded from Postgres 15 to 18, but the steps are much the same whichever version you are leaving behind.

The email that started it

Here is the email Heroku sent us:

That date is Heroku retiring the version on their platform, not upstream PostgreSQL dropping support for it. It also travels with the notice rather than with the version: Heroku’s Postgres version support page lists Postgres 15 reaching end-of-life on February 28, 2027, later than the date in our email. Go by whichever comes first for your database.

The email names one database, and the dashboard has no aggregate view of versions, so the first thing to find out is whether your other apps are in the same position. There is no single command for that, but heroku apps speaks JSON, which is enough to ask each one:

for app in $(heroku apps --team your-team --json | jq -r '.[].name'); do
  version=$(heroku pg:info -a "$app" 2>/dev/null | grep "PG Version" | awk '{print $NF}')
  [ -n "$version" ] && echo "$app: $version"
done

Drop --team if your apps are personal. Apps without a database print nothing.

The reason to run this yourself, rather than letting the deadline arrive, is the downtime. Replacing a database version means putting the app in maintenance mode and taking it offline for a few minutes, and after the deadline Heroku picks that moment for you. I would rather schedule that outage myself than have Heroku cut requests off mid-flight.

Choosing how to upgrade

Heroku documents three ways to upgrade a database version, and they mostly differ in how long your app is unavailable.

A direct upgrade with pg:upgrade:run takes “around 10 minutes for most use cases, although this amount can vary”.

A follower failover needs 20 to 30 minutes. Copying the data into a new database needs “approximately 3 minutes of app downtime per GB of your current database, although this amount can vary substantially depending on your schema and database plan”.

I went with the data copy, for two reasons that had nothing to do with speed. The old database stays exactly where it is, so you can point the app back at it with heroku pg:promote if the new one misbehaves. And since you choose the plan when you provision a database, an upgrade is a good moment to move to a plan that matches how the app behaves today rather than when the database was created.

None of the three avoid downtime. The documentation is explicit that “all methods require some application downtime to ensure that no data is lost during the upgrade”, so pick a low-traffic window.

New databases are created on the current default version, 18.3 as of this writing, so provisioning one gets you the version bump for free:

heroku addons:create heroku-postgresql:<your-plan> -a example-app
heroku pg:wait -a example-app
heroku pg:info -a example-app

Freezing writes, and the part where pg:copy did not run

Before copying anything, the app has to stop writing. Maintenance mode alone is not enough, because it does not scale down your dynos, and a running dyno can still open connections and commit rows:

heroku maintenance:on -a example-app
heroku ps:scale web=0 -a example-app

While the app is down, check whether DATABASE_URL is a real attachment or a config var somebody set by hand years ago. Ours was the second kind, so pg:promote would have created the attachment while the hand-set variable kept pointing at the old database:

heroku addons -a example-app

If DATABASE_URL does not show up there as an attachment, unset it before promoting, and let Heroku manage it from then on:

heroku config:unset DATABASE_URL -a example-app

Heroku names each database attachment after a color, so yours will be something like HEROKU_POSTGRESQL_GOLD_URL. I have relabeled them OLD and NEW in the commands below, including in the output, so it stays obvious which database is which.

With writes frozen and a fresh database waiting, the documented copy command failed:

$ heroku pg:copy HEROKU_POSTGRESQL_OLD_URL HEROKU_POSTGRESQL_NEW_URL -a example-app --confirm NEW
Starting copy of OLD to NEW... !
 ›   Error: Internal server error.
 ›   Error ID: internal_server_error

It failed twice, and heroku pg:backups showed no copy job at all, so nothing had started on Heroku’s side. The target was still empty and the source untouched, the good version of this failure.

So I fell back to a backup and a restore, which is the same idea through a different subsystem:

heroku pg:backups:capture HEROKU_POSTGRESQL_OLD_URL -a example-app
heroku pg:backups:restore b011 HEROKU_POSTGRESQL_NEW_URL -a example-app --confirm example-app

The b011 is the id the capture prints when it finishes, and heroku pg:backups lists them if you lose it. Pass it explicitly: leaving it out shifts the arguments along, so the target becomes DATABASE_URL and you restore the old database over itself.

The restore takes a --confirm because it destroys something: it wipes the target database before loading into it. The capture just writes a new backup, so it has no confirmation flag at all. Look closely at that value, though. Both destructive commands ask you to confirm, but they want different things: pg:copy wants the target database, pg:backups:restore wants the app. Passing the database name to the restore gets you this:

Error: Confirmation NEW did not match example-app. Aborted.

The restore aborts before it starts and leaves nothing under the Restores section of heroku pg:backups, so it looks like you never ran it. With the app name, it went through on the first try.

Falling back to pg_dump and pg_restore

Later that night the restore started failing the same way on another database, so I moved the data myself. This is an escape hatch, not the path I would recommend.

These commands run on your own machine, not on a Heroku dyno. pg_dump and pg_restore are ordinary Postgres clients that connect over the network like your app does, so a full copy of your production database lands on your laptop before going back up to the new one.

That is a problem that has nothing to do with Postgres. If your database holds personal data, health records, payment details, or anything else covered by an agreement you have signed, downloading it to a development machine may violate that agreement no matter how careful you are with the file afterwards. Heroku’s copy and restore commands keep the data inside their infrastructure, and the in-place pg:upgrade:run never moves it at all. When the data is sensitive those are the better answers, and a support ticket beats a local dump when they fail.

Ours holds public benchmark results and no personal data, which is the only reason I was comfortable doing this. Size matters too: the round trip is quick for a small database and slow for a large one.

The clients have to be at least as new as the server you are dumping from: “pg_dump cannot dump from PostgreSQL servers newer than its own major version; it will refuse to even try”. On macOS, brew install libpq is enough.

Get both connection strings first, then dump and restore:

OLD_URL=$(heroku config:get HEROKU_POSTGRESQL_OLD_URL -a example-app)
NEW_URL=$(heroku config:get HEROKU_POSTGRESQL_NEW_URL -a example-app)

pg_dump -Fc --no-owner --no-privileges -f old.dump "$OLD_URL?sslmode=require"
pg_restore --no-owner --no-privileges --no-comments -d "$NEW_URL?sslmode=require" old.dump

-Fc asks for the custom archive format, which is compressed and is what pg_restore expects; a plain SQL dump works too but goes through psql instead. --no-owner and --no-privileges drop ownership and grant statements you cannot apply anyway, because Heroku gives you no superuser.

This worked on the first attempt, after two of Heroku’s own commands had not. Expect one harmless error about not owning pg_stat_statements, for the same superuser reason. Delete the dump file afterwards.

Then promote the new database, bring the app back, and check the data:

heroku pg:promote HEROKU_POSTGRESQL_NEW_URL -a example-app
heroku ps:scale web=1 -a example-app
heroku maintenance:off -a example-app

Row counts are the obvious check, and the lesson I keep relearning, including the time I moved another app from Heroku to Railway. The easier one to forget is the sequence behind each primary key, because a stale sequence starts handing out ids that already exist:

heroku pg:psql -a example-app -c "select last_value from reports_id_seq"

That shells out to a local psql, so it fails with “The local psql command could not be located” if you skipped the client tools. heroku run rails runner works instead.

Conclusion

In this article we moved a Heroku Postgres database off a deprecated version by copying it into a newly provisioned database, which also gave us a moment to reconsider the plan, and we went through the commands that failed on the way. If both pg:copy and pg:backups:restore fail for you, the local dump is there, but when the data is sensitive a support ticket is the better next step.

A few things worth keeping in mind. The table counts in pg:info lag by several minutes, so a fresh restore can report zero tables while the data is already there, and only a direct query is worth trusting. Keep the old database for a few days before destroying it, since it is your cheapest rollback. And update the Postgres image in your CI workflow, because one pinned to postgres:15.17-alpine keeps testing the version you just left.

The app whose database started all this is at ips.fastruby.io. Point your benchmark-ips script at it and you get a shareable link for your results instead of a wall of terminal output.

Is your team carrying deadlines like this one behind a product roadmap that never has room for them? We can help you deal with that maintenance work.

I’ll get into what’s changing in each of the eight, why the Rails team made the change, and what to update in your own code once it ships. If you want the general playbook for handling deprecation warnings during an upgrade, we have a guide for that too.

Attribute writes: write_attribute(:id, ...) is deprecated

If you’re using a custom primary key, write_attribute(:id, value) used to translate :id into your actual primary key column behind the scenes:

class Order < ApplicationRecord
  self.primary_key = "legacy_id"
end

order = Order.new
order.write_attribute(:id, 42)
order.legacy_id # => 42

That’s going away. Pull request #58347 deprecates the translation. Eventually write_attribute(:id, value) will write straight to the id column instead of your custom primary key. It’s a follow-up to an earlier change to read_attribute(:id), which stopped returning the custom primary key value a few versions back. The Rails team calls the old write-side behavior “most likely an oversight”, since it’s never gotten the same treatment as the read side.

The PR doesn’t spell out an official migration path, but one way to keep the old behavior is to write to your actual primary key attribute by name instead of through :id:

order.write_attribute(:legacy_id, 42)

Treat that as a starting point, not an official fix, and check whether order.id = 42 (Active Record’s own primary key alias) does the job for your case too. This only affects apps with a custom or composite primary key. If your models use Rails’ default id column, there’s nothing to change.

SQL internals cleanup: positional #insert args, binds, and the create alias

Four separate pull requests share the same focus: pieces of Active Record’s low-level connection API that come before Arel’s current way of handling bind parameters (the ? placeholders in a query that carry their values separately, like WHERE id = ? paired with 1) are getting deprecated.

PR #58297 deprecates three positional arguments to #insert: pk (primary key), id_value, and sequence_name. Each gets its own warning and its own replacement:

# before: pk selects which column #insert returns
connection.insert(sql, name, "id")

# after: use the returning: keyword instead
connection.insert(sql, name, returning: "id")

id_value used to let #insert echo back a value the caller already had, for cases where the database couldn’t compute the last inserted ID. If you’re passing it in, you already have the value, you don’t need it returned. sequence_name only mattered for a PostgreSQL currval() fallback tied to a config path that’s already deprecated on its own.

The binds argument (the separate array holding those placeholder values) is going away in two places. PR #58310 deprecates passing binds to to_sql, and PR #58323 deprecates it as a positional argument to insert, update, and delete. Both come down to the same root cause: since Rails 5.2, Arel has tracked bind values as part of the query itself, so passing binds in separately hasn’t done anything for years, to_sql never even looked at the value you gave it. The fix is to build the bind values into the SQL itself with Arel.sql:

# before
connection.update("UPDATE topics SET title = ? WHERE id = 1", [title])

# after
connection.update(Arel.sql("UPDATE topics SET title = ? WHERE id = 1", title))

Arel.sql can now wrap a SQL string and its bind values together, the same pattern Model.where already uses internally. The old positional binds argument is planned to be removed in Rails 8.3, so you have more time to update this one than the others.

Last in this group, PR #58426 deprecates the create alias for insert on connection adapters. insert, update, and delete map to their SQL verbs, but create reads like DDL (create_table, create_database) when it’s actually running an INSERT. If you’re calling connection.create(...) directly, switch to connection.insert(...). Same behavior, clearer name.

Relation changes: uniq! deprecated, and update/update! now respect scope

Two changes here, one minor cleanup and one real behavior fix, both about making a Relation’s behavior more consistent. This is the same family of change as the Rails 6.1 merge deprecation we ran into a while back.

PR #58525 deprecates Relation#uniq!. Rails added it back to help with the move to automatic deduplication of multi-value query methods (SELECT DISTINCT and friends), a Rails 7.0 feature. Deduplication happens automatically now, so the method doesn’t do anything useful anymore. Rails plans to remove it in 9.0. If you’re on Rails 7.0 or newer and still have uniq! calls lying around, they’re safe to delete today.

The bigger one is PR #58320, which changes how update and update! behave when you call them with an ID on a scoped relation:

post.comments.update!(comment_id, body: "edited")

Before this change, that call delegated to the model class method (in this case Comment.update!), which resolved comment_id against the whole comments table, not just the ones belonging to post. If comment_id pointed at a comment on a different post, the update would go through anyway. The Rails team’s commit message says it directly: an update through an association could silently write to a record that belonged to a different post, even though the association was supposed to scope it.

After this change, update and update! move to the Relation class and respect its scope the same way update_all, delete, and destroy already do. If the ID isn’t in the relation’s scope, Rails raises ActiveRecord::RecordNotFound instead of writing to a record you didn’t mean to touch.

The fix cuts both ways. The Rails team calls the second half “the same bug seen from the other side”: Model.unscoped.update(id, attributes) now actually stops applying your model’s default scope too. Before, update/update! ignored whatever scope you called it through, whether that scope was meant to narrow your options (an association) or remove them (unscoped). Now it honors the relation’s real scope either way, so it’s also worth testing any unscoped.update call that was relying on a default scope to still filter things out.

This is the one worth actually testing for. Does your app call update/update! with an ID through an association anywhere, where that ID could realistically belong to a different parent record? That call will start raising once this ships. It’s the right behavior, but it’s a behavior change, not just a rename.

Schema config consolidation: schema_ignored_tables

If you’ve ever needed to keep a table out of schema.rb and out of the schema cache, you’ve probably set two separate options:

config.active_record.schema_cache_ignored_tables = ["audit_logs"]
ActiveRecord::SchemaDumper.ignore_tables = ["audit_logs"]

PR #58554 merges both into one:

config.active_record.schema_ignored_tables = ["audit_logs"]

The reasoning is simple: the two old options were sort of doing the same job, and the PR description asks the obvious question, why would you want to ignore a table from schema caching but not from the dumper, or the other way around? Both old configs still work for now, they delegate to the new one and print a deprecation warning, but if you set both, only the last one you assign wins.

One thing to watch: table matching now happens against the actual database table name, not the logical name with your table_name_prefix/table_name_suffix removed. If your app uses either of those and you’re ignoring a table by its logical name, double check the entry still matches once you switch to schema_ignored_tables. If schema config in general feels unfamiliar, we’ve covered the other schema changes that landed in Rails 7 too.

Conclusion

All eight of these are sitting on Rails main right now, not in a tagged release, so nothing in your app breaks today. write_attribute(:id, ...), the #insert/to_sql/create cleanup, uniq!, and the schema_ignored_tables merge are all low-risk renames you can get ahead of whenever you have a few minutes. The one to actually go test for is the update/update! scope change. If any of your code writes to a record by ID through an association, check now whether that ID could ever belong to something outside the association’s scope, before Rails starts raising on it for you. Once you’ve fixed these, here’s how to keep the fixed ones from creeping back into your codebase.

Has your team been struggling with an upgrade? We can help.

Then a few months pass, a dozen new pages ship, and the next audit reports the same findings again. Not because anyone ignored the first round, but because the first round fixed pages instead of fixing the process that produces pages.

That happened to us, on this site and on OmbuLabs.ai. So the second time around we spent the effort somewhere else. Instead of just fixing the pages, we wrote checks that run on every build and say when a new page has the same problem. It is roughly the same idea as automating a tech debt audit: most of the value is not in the report, it is in being able to produce the report again for free. No two of them wanted the same kind of check.

The goal here is search traffic, not a clean report. Thin pages, vague link text, and duplicated title tags are the things that hold a page back in search results, and a page that ships with them costs us traffic until the next audit finds it. A check on every build moves that discovery from months later to the pull request.

In this article, you will learn how we turned three kinds of audit findings into checks that run in CI.

Word count, text ratio, and semantic ratio

The first group of findings was about the content itself, the pages a crawler treats as thin. By crawler I mean Googlebot, Bing and the AI crawlers that feed answer engines. There are three metrics that matter here:

Word count. How many words the page actually says.

Text ratio. The size of the visible text divided by the size of the whole HTML file. A page can look full to you and still be 5% words and 95% tags, and a crawler reads that as a page built to hold a layout rather than to say something.

Semantic ratio. How many of the page’s tags are ones that carry meaning (h2, p, ul, article, footer) instead of plain div and span. Semantic tags are what tell a crawler which part is a heading and which part is the body. A page made of nested divs says nothing about its own structure.

We put all three in one class, ContentQualityChecker, that parses the page with Nokogiri, with the thresholds at the top:

class ContentQualityChecker
  WORD_COUNT_MIN = 200
  TEXT_RATIO_MIN = 0.10
  SEMANTIC_RATIO_MIN = 0.115

  SEMANTIC_ELEMENTS = %w[
    header nav main article section aside footer figure figcaption time mark details summary
    h1 h2 h3 h4 h5 h6 ul ol li p blockquote table tr td th
  ].freeze

Those numbers are not set in stone. They are in the range the common audit tools complain about, and they are low enough that a real article never trips them, which is what you actually want from a threshold. If yours flag half your posts, they are set too high for your layout.

The one number that needs care is the word count. Counting the whole <body> sounds right but it is not, because every page carries the same nav, sidebar, and footer, and on our pages that added roughly 40% to the number. Thin pages looked fine. So the count cuts out everything but the main content area, doc.at("main"), falling back to the body for anything without one.

With the checker in place the rest is two rake tasks, and they do not work the same way. Our blog is a Jekyll build, so the pages are already HTML on disk and that task just globs the files and needs nothing but Nokogiri. Rails pages only exist once something renders them, so that task opens an ActionDispatch::Integration::Session and requests each path the way a visitor would. It is the cheapest way we found to measure a rendered page without a browser in the loop.

The report prints one line per flagged page, worst first:

/blog/tags/railsconf                  195w  text  11.0%  semantic  16.2%  low word count
/blog/fortify-rails-security-webinar  280w  text   9.7%  semantic  25.8%  low text ratio

Today it flags 20 pages out of the 304 it measures on the blog, and most of them are edge cases we are fine with. Tag and author listings are thin because they are navigation, not articles. A group of long posts from years ago trips the semantic ratio because their markup is older than the current layout. Expect a tail like that of your own, every site has one. The report is there to tell the pages that are thin on purpose from the one somebody shipped last week without noticing.

Anchor text that describes the destination

The second group is the interesting one, because the audit finding and an accessibility bug turn out to be the same bug.

Anchor text is the visible words inside a link. A crawler just extracts that text, so click here gets read as exactly that, “click here”, with no information about where the link takes you. A screen reader user gets the same nothing, out of context, from a list of links on the page.

Two findings came up. Links with no anchor text at all, and links whose anchor text describes nothing: here, click here, read more, learn more, details, download, continue. If you have read anything about accessibility, and I covered some of this in Usability Meets Accessibility and From Code to Compliance: Accessibility Testing, that list is familiar. The way people usually try to fix the first one misses the point.

Take an icon-only link, a social icon in the footer for example. It has no text node at all. The first thing people try is an aria-label on the <a>, or alt text on the image inside it, and then they consider it handled. For a screen reader that mostly works. For a crawler it does not, because it reads the anchor’s text content, and neither an attribute on the link nor an attribute on a child image is text content. The fix that works for both readers is a real text node that happens to be invisible: a <span> with the sr-only class, a CSS convention that pushes text off screen while leaving it in the document. The name says “screen reader only”, but it fixes crawlers too: both read text content, not what is visible on screen.

Our scroll-to-top link is the smallest example. Before, an image and an attribute:

<a class="scrollto" href="#top">
  <img src="circle-black-lg.svg" alt="Scroll to top">
</a>

After, the image is marked as decoration and the words live in the document:

<a class="scrollto" href="#top">
  <img src="circle-black-lg.svg" alt="" aria-hidden="true">
  <span class="sr-only">Scroll to top</span>
</a>

Nothing changes on screen. The difference is that the second link has anchor text and the first one has none.

Then there was the part that gave me the most headaches, and it came from one of our own gems. Our blog builds with jekyll-external-link-accessibility, a plugin we maintain that appends a note to every external link so screen reader users know it opens a new tab. That is a good thing to do, and it also means that by the time the checker sees the HTML, a link reading “here” reads “here opens a new window”, which matches nothing. Every non-descriptive link on the blog passed clean. So the text has to be cleaned up before it is judged:

DECORATION = /\s*opens a new window\s*\z/i

def visible_text(anchor)
  stripped = anchor.dup
  stripped.css("[aria-hidden='true']").each(&:remove)
  stripped.text.gsub(/\s+/, " ").strip.sub(DECORATION, "")
end

The aria-hidden removal is the same idea running the other way. An icon marked aria-hidden="true" is decoration nobody hears, so it should not count as anchor text either.

A baseline spec for page metadata

The third group was metadata. A rake task is the wrong tool here. There is no threshold to report on, the tags are either present or they are not. So this one is a request spec. It requests each public page and asserts the tags a crawler and a link preview need:

aggregate_failures("SEO/social baseline for #{path}") do
  expect(body).to match(/<meta\s+name="description"\s+content="[^"]+"/),
    %(Missing or empty <meta name="description"> on #{path}. Add static.<action>.description in config/locales/en.yml.)

  expect(body).not_to match(/translation missing/i),
    %(Found an unresolved I18n key ("translation missing") on #{path}. Add the missing key in config/locales/en.yml.)

  expect(body).to match(/<meta\s+property="og:url"\s+content="http[^"]+"/),
    %(Missing or non-canonical og:url on #{path}. It should be the full URL of the page, not a hardcoded value.)
end

There are a dozen more like that, covering the rest of the og: tags and the JSON-LD blocks. aggregate_failures reports everything wrong with the page in one run, and every message names where the fix goes, down to the locale key. A spec that fails with “expected false to equal true” gets skipped by the next person who hits it.

None of that matters if the spec never visits the page. Keep a list of the paths left out on purpose, with a reason for each one, so a new page never slips through unnoticed:

IGNORED_PATHS = {
  "/search" => "redirects to /blog when query is blank, so does not render HTML",
  "/success" => "redirects to /roadmap after Stripe checkout",
  "/robots.txt" => "non-HTML",
  "/sitemap.xml" => "non-HTML"
}.freeze

Writing the reason down is worth more than it looks. An ignore list without reasons becomes a place to hide failures, and six months later nobody remembers whether /success is skipped because it redirects or because someone was in a hurry.

The list only works if it cannot go stale, so one example asks the router what exists and compares. Trimmed a little:

it "covers every public GET route or lists it in IGNORED_PATHS" do
  discovered = Rails.application.routes.routes.flat_map do |route|
    next [] unless Array(route.verb).first.to_s.include?("GET")

    spec = route.path.spec.to_s.sub(/\(\.:format\)\z/, "")
    next [] if spec.match?(/[:*]/)

    controller = route.defaults[:controller].to_s
    next [] if ignored_controller_prefixes.any? { |prefix| controller.start_with?(prefix) }

    [spec]
  end.uniq

  expect(discovered - (PUBLIC_PAGE_PATHS + IGNORED_PATHS.keys)).to be_empty
end

Routes with parameters are skipped, since you cannot request them without making up a record, and so are admin, API, and framework controllers, since nothing there is meant to be indexed. Everything else has to be in one list or the other. Add a public page and the spec fails with the path in the message. It fails the other way too, when a listed path no longer exists in routes.rb, so old pages cannot stay in the list.

Conclusion

In this article, we went through three ways to keep an audit finding from coming back, so the pages we ship keep earning search traffic instead of losing it a little at a time. By setting a concrete metric or rule for each kind of finding, a word count and markup ratio for content, a matching tag for metadata, we could check it automatically in CI on every pull request. That let us tell which problems needed fixing right away and which ones were fine to track and fix over time.

Automate the metadata spec first. It pays for itself the first time somebody adds a page in a hurry.

Is your team carrying a backlog of findings that nobody has time to keep fixed? We can take that off your hands, send us a message.

APM is worth having when it’s used well: it resolves incidents faster by showing you where in the stack a problem started, it gives you warning before a threshold alert turns into an outage, and it gives you a defensible answer when a client or stakeholder asks whether you hit your SLA (often measured through percentile response times like p95 and p99). None of that is in question here. What tends to go unexamined is whether the bill still matches what you’re getting for it.

In this article, we’ll walk through where APM spend typically concentrates, the warning signs that a bill has drifted from usage-driven growth into unmanaged creep, and a concrete checklist for getting ahead of it before your next renewal.

Where the Money Goes

Annual APM spend scales with organization size, and the gap between the low end and the high end is wide. As a rough illustration: a small startup running a handful of hosts might land in the low five figures a year, a mid market company running dozens of hosts often lands in the mid five to low six figures, and a large enterprise running hundreds of hosts across multiple environments can move well into six or seven figures. Treat these as illustrative bands, not a quote; your own host count, environment count, and data volume are what actually set the number.

APM monthly spend usually concentrates in a few areas. The exact split depends on the size of your organization and how log or host heavy your workload is, so treat the following as a description of where the money tends to go, not shares that add up to 100%.

Host and container monitoring is the steady, predictable baseline, since it scales directly with host count and rarely surprises anyone. Data ingestion for metrics and traces adds a smaller share on top, and scales with traffic. Log ingestion is where the real growth happens, and it often ends up the largest line on the bill, because it’s priced at a premium and billed by volume rather than by host.

The rest are smaller but add up: custom metrics (billed per metric per host, and easy to accumulate without anyone noticing), retention that multiplies ingestion cost rather than showing up on its own line, unused user seats sitting as dead cost, and synthetic or RUM (Real User Monitoring) checks that can spike if uncapped.

None of this is unreasonable on its own. The trouble starts when nobody is responsible for where those costs compound over time.

Where the Cost Hides

This is the part that catches executives off guard, because it rarely shows up as a single suspicious charge. It shows up as gradual drift, and it tends to hide in the same handful of places.

The data itself is the usual culprit. Custom metrics get priced at a premium and added incrementally without anyone tracking the cumulative bill, and high cardinality tags (user IDs, request IDs, and the like) multiply billing under per series pricing (each unique combination of tags counted as its own billable metric), often invisibly. Logs are the big one: priced far higher than metrics or traces and billed by volume rather than by host, so a single verbose service, especially one left on DEBUG level logging in production, can generate a disproportionate share of your billable data relative to its actual footprint. This is one of the most common places log spend runs away from teams.

The contract and the environment hide the rest. Usage beyond your committed or budgeted volume typically bills at a higher rate, whether that’s an on demand rate above a negotiated price or the next pricing tier on a self-serve plan. The exact multiplier is contract and vendor specific; check yours rather than assuming a standard rate. Uncapped auto scaling settings let billing grow with no ceiling at all, negotiated or otherwise. Meanwhile the waste you have stopped noticing adds up: non production environments instrumented at the production tier, agents (the small process each host runs to report data back to the vendor) left running on decommissioned services and still billing for data nobody uses, and redundant coverage across APM, logging, and infrastructure platforms that means paying twice for the same signal.

Individually, each of these is minor. Together, over a year, they are the difference between a tool that pays for itself and one that becomes a budget problem nobody can explain.

Cost Leak Warning Signs

Whoever manages the tool day to day usually spots the drift first, since it shows up as more logs enabled, more custom metrics added, or an extra environment instrumented. Whoever pays the bill only sees the invoice. If those aren’t the same person, and they aren’t comparing notes when they’re not, nobody can tell a legitimate increase from a creeping one until the bill is already high enough to raise a question. You don’t need to be an APM expert to catch it, you need whoever’s watching usage and whoever’s watching spend looking at the same signals.

The financial tells come first: invoice variance with no matching change in infrastructure or business growth, and a flat host count next to a rising bill, which points to volume or feature growth rather than scale.

The contractual and structural ones are just as telling: plan or contract terms with no ceiling or advance notice clause on overages, licensed seats or modules nobody uses, APM spend sitting next to overlapping logging or observability tooling, and production tier instrumentation still running on non production environments. Underneath all of them is the same root cause: when no single person is accountable for this line item, it goes unmanaged by default, not by decision.

APM Renewal Preparation

These costs go unnoticed because no single vantage point sees the whole picture. Someone needs to know the instrumentation scope, retention settings, and which environments are monitored. Someone needs to track spend against usage over time. Someone needs to know the contract terms, renewal date, and any negotiated caps. And someone needs to reconcile the invoice against budget and catch variance early. At a larger company those are four different people, in engineering, FinOps, procurement, and finance. At a smaller one, it might be the same engineer or founder wearing all four hats, which makes it easier to miss the gap between what one hat knows and what another hat is tracking.

In practice, whoever owns the budget for this line item usually drives the renewal, whether that’s a dedicated FinOps team or the person who first approved the tool. Either way, preparing usage data on a regular cadence, quarterly if you can manage it, beats scrambling at contract time. The preparation itself comes down to six steps:

1. Audit actual usage against contract terms, starting 60 to 90 days out (or ahead of your next plan review if you’re on a self-serve plan without a fixed renewal date). Pull 12 months of usage (host count at peak, not average; ingestion volume by category for metrics, traces, and logs; and retention actually used versus contracted) and flag any gap between what you’re paying for and what you’re actually using, in either direction.
2. Identify what is inflating the bill. Check log ingestion volume specifically, look for orphaned agents on decommissioned hosts still reporting data, watch custom metric count and high cardinality tags for creep, and confirm non production environments are not running production tier instrumentation.
3. Right size before renewing, not after. Cut unused seats, disable unused modules, reduce retention windows that exceed actual need, and turn off verbose logging left on in production, so you negotiate, or simply re-subscribe, from your actual usage number rather than the inflated one.
4. Review the terms themselves, not just the price, whether or not you have a negotiated contract. Look at the overage rate versus the base rate (push for a cap or a lower multiplier if you’re in a position to negotiate one), any auto scaling clause and whether it carries advance notice or a ceiling, how often actual usage is reconciled against the plan, and termination and data export terms that confirm you are not locked in if you switch later.
5. Benchmark before deciding. Get at least one competitive quote (Datadog, New Relic, Grafana Cloud, and so on), even if you do not intend to switch, and bring your actual usage number to the table, not the vendor’s projected one. If the bill has fully outgrown what you’re getting from it, self-hosting your observability stack is also worth pricing out, not just switching vendors.
6. Assign an owner. One person, whether that’s a dedicated FinOps lead or simply whoever manages the account, owns the renewal outcome and stays accountable for usage monitoring afterward.

That’s the same group as the quarterly cost review, however many people that group actually is; a renewal is just its highest leverage version.

Conclusion

APM cost creep is rarely about APM. It’s a symptom of a familiar pattern in infrastructure decisions generally: tools get adopted quickly under real pressure, nobody assigns ongoing ownership, and by the time the cost or the technical debt is visible, it’s expensive to unwind.

If your APM bill has grown faster than your infrastructure, that’s worth a look. The tool itself is probably fine; the growth was likely never a decision at all, just the default outcome of nobody watching it.

That’s usually true of the surrounding infrastructure too. If you’re re-examining monitoring spend, it’s a good moment to ask the same question about your broader stack: what’s running today because someone chose it, and what’s running today because nobody revisited it?

Is your APM bill outgrowing your infrastructure? We can help you audit where it’s leaking.

The Problem: A Business-Critical System You’re Afraid to Touch

Most organizations don’t wake up one day and decide to replace a legacy system. It happens gradually, as the cost and risk of maintaining the system tends to increase over time.

One common problem is that the application becomes difficult to change. As a result, teams may avoid making necessary improvements because the risk of introducing regressions is too high. Older dependencies may no longer be supported and infrastructure may require specialized operational knowledge. Security vulnerabilities accumulate. Old dependencies stop receiving patches, frameworks fall out of active support, and the gap between “known vulnerable” and “actually fixed” widens.

Despite these problems, replacing the application can be risky. The system may contain years of accumulated business logic, including edge cases that are not documented anywhere else. A complete replacement must account for those behaviors while continuing to support current users, integrations, and operational requirements. This makes a full rewrite difficult to estimate and potentially disruptive.

Doing nothing, however, is not a sustainable strategy. Technical debt continues to accumulate as dependencies age, knowledge is lost, and temporary workarounds become permanent parts of the application. Over time, the organization has fewer safe options and less flexibility in deciding how and when to replace the system.

Why “Just Rewrite It” Doesn’t Work

Faced with a system like this, the instinct is often to start fresh: freeze the old system, build a new one properly, and cut over once it’s ready. In practice, this approach carries its own set of serious risks, which is why full rewrites so often stall, run over budget, or get abandoned partway through.

Instead of a series of small, reversible changes, the business is betting on one large release, often after months (or years) of work, with no real-world validation until the very end. If something is wrong it surfaces all at once, after the cost of building the replacement has already been paid.

It is also rarely practical to freeze feature development while the replacement is being built. The existing application still supports an active business, and users continue to request changes. Regulations, market conditions, internal processes, and customer expectations may also change during the rewrite. As a result, the legacy system continues to evolve while the new system is under development.

If the old system keeps changing while the new one is being built, then the team is effectively maintaining two systems in parallel (one in production, one in development). This work grows more difficult the longer the rewrite takes, and it’s easy for parity to quietly erode without anyone noticing until launch.

The Strangler Fig Pattern

The name comes from a real botanical phenomenon: strangler fig vines take root in the branches of a host tree, gradually growing around it. Over years, the fig develops its own root and trunk system, until eventually it no longer needs the host at all. Applied to software, this idea gives us a middle path between keeping a legacy system indefinitely and replacing it all at once.

The mechanics are straightforward:

1. First create a seam, a well-defined point where requests or behavior can be intercepted, such as a router, API gateway, or facade layer.
2. Next intercept requests at that seam and decide, for each one, whether it should be handled by the legacy system or the new implementation.
3. Then redirect traffic to the new implementation gradually, one slice of functionality at a time, validating each piece before moving to the next.
4. Finally decommission the corresponding old code path once a piece has been fully and reliably replaced.

The old and new systems therefore operate together for a period of time. As each replacement is tested and proven, more requests are routed to the new system and the corresponding legacy code path is decommissioned. This cycle continues until the legacy application has few or no remaining responsibilities and can be retired.

How This Helps With Technical Debt

Before we get to the mechanics, it’s worth connecting this pattern to the problem it’s actually solving. The strangler fig pattern allows teams to reduce technical debt without stopping product development. The process can also improve the structure of the application. Creating seams between capabilities encourages clearer architectural boundaries, while migrating individual areas often leads to better automated tests, monitoring, and operational visibility. If you’re also looking to improve the code you’re keeping, our post on refactoring Rails applications covers how we approach that work alongside debt reduction.

However, creating a modern system is not enough on its own. Technical debt is only reduced when the corresponding legacy capability is removed. If the old code path remains active, the organization must maintain both implementations and may end up increasing complexity instead. For that reason, decommissioning should be part of the definition of done. Over time, this turns technical-debt reduction from a one-time project into an ongoing delivery practice: identify a costly area, replace it safely, remove the old implementation, and repeat.

Running the Old and New Systems Together

The strangler fig pattern requires the legacy and modern systems to operate at the same time. A routing mechanism decides which system should handle each request.

The routing mechanism can take a few different forms, depending on where the seam naturally falls in the architecture. This mechanism might be a reverse proxy, an API gateway, an application façade, or routing logic inside the application itself. For asynchronous workflows, a message broker or event stream can serve a similar purpose by directing events to legacy or modern consumers.

The other key decision we need to make is how to divide the system into pieces that can be migrated independently. There are two common approaches. Divide the system by route or endpoint, migrating one API endpoint or URL path at a time, well suited to systems with a clear request/response structure. Alternativly, use modules or domains as boundaries, then migrate one area of business logic at a time (billing, authentication, reporting), better suited to systems where the seams are conceptual rather than purely technical.

Managing Data During the Transition

Data is often the most difficult part of running the legacy and modern systems together. The key question is not only where data is stored, but: which system is the source of truth for it, right now?

A few common approaches:

• The legacy system remains the source of truth, even for capabilities that have already been migrated. The new system reads from or defers to the legacy system’s data, which keeps ownership simple but limits how independently the new system can operate.
• The new system takes ownership of data for capabilities it has already migrated, with the legacy system deferring to it instead. This is usually the direction migrations move toward over time.
• The two systems’ data is kept synchronized, with neither fully deferring to the other. This can work as a transitional state, but it requires clear rules about how conflicts are resolved when both systems can write.
• Changes are propagated via events, so that whichever system makes a change publishes it, and the other system consumes and applies it. This decouples the two systems more cleanly than direct synchronization, at the cost of eventual (rather than immediate) consistency.

Whichever combination of these is used, the risk of leaving ownership ambiguous is the same. The main safeguard is explicit ownership. For each category of data, the team should define which system can write it, how changes are propagated, and how inconsistencies are detected and corrected. Without those restrictions, both systems can begin modifying the same information independently, making errors difficult to trace and resolve.

The data strategy may change as the migration progresses, but ownership should never be ambiguous.

Mitigating Risk Along the Way

The strangler fig pattern reduces risk by design, simply by breaking a migration into smaller steps. But smaller steps need to be paired with safeguards that catch problems early and make it easy to back out when something isn’t working.

Feature flags and incremental traffic routing allow the team to control what traffic to send to the new implementation. A new capability can first be enabled for internal users, a small customer segment, or a limited percentage of requests. If problems appear, traffic can be redirected to the legacy implementation without needing to redeploy or reverse the entire migration.

Automated tests are important, but they are not sufficient on their own. The new system must also be observed in production, at minimum, this means tracking completed transactions, processing times, and mismatched records between the two systems.

Reconciliation processes help detect issues that normal monitoring may miss. For example, a scheduled comparison can verify that both systems processed the same orders, produced the same totals, or reached the same final state.

Every migration step should also have a documented rollback procedure. The team should know how to restore the previous routing, what happens to data created by the new system, and whether any actions need to be reconciled after the rollback.

A Practical Game Plan

A strangler fig migration usually follows a repeatable sequence.

1. Identify a seam. Look for a boundary that’s already relatively clean such as a single API endpoint, a self-contained module, or a domain with limited dependencies on the rest of the system.
2. Build the interception point. Stand up whatever routing mechanism fits the seam (a proxy rule, a facade method, a conditional branch) so that traffic for this piece can be redirected, without yet redirecting all of it.
3. Migrate one capability. The first candidate should be meaningful enough to provide value, but contained enough to limit risk. Moving one well-defined capability also gives the team a chance to test the migration approach before applying it more broadly.
4. Validate before fully switching over. Tests confirm the new implementation behaves correctly in isolation. Shadow traffic sends real production requests to the new implementation without using its response, so its behavior can be observed under real conditions before it’s trusted. Finally we compare logging outputs of both systems side by side, looking for differences between the legacy and new implementations.
5. Expand. Once the new capability behaves reliably, traffic can be shifted gradually. The same process can then be repeated for the next capability.
6. Know what “done” looks like. It is critical that we define what “done” means for both the migration as a whole and each individual slice. We must know what capabilities need to move, what the legacy system’s retirement looks like, and how success will be measured along the way.

When It Goes Wrong

The strangler fig pattern is straightforward to describe, but easy to execute poorly. Most failures come from losing sight of the discipline the pattern requires, rather than from the pattern itself being wrong for the job. One common mistake is building the new system without retiring the old one, but there are other important missteps worth being aware of.

One such misstep is choosing the wrong migration boundaries. Moving technical components, such as a database table or utility module, may not remove a complete responsibility from the legacy system. Migrating an end-to-end business capability usually creates a clearer ownership boundary and makes decommissioning more practical.

A newer technology stack does not automatically produce a better system. Teams can reproduce the same coupling and unclear boundaries if they copy the legacy architecture too closely. At the same time, they may underestimate undocumented behavior and discover late in the process that important edge cases were not included in the replacement.

Trying to migrate too many areas at once can make these problems harder to control. Each stream introduces its own routing, data, testing, and operational concerns. A smaller number of focused migrations makes it easier to learn from each step and apply those lessons to the next one.

Modernization also needs business ownership. If it is treated as a side project, feature work will usually take priority and the legacy system will remain in place. The migration is more likely to succeed when each step has a business reason, a responsible owner, and a specific decommissioning outcome.

A Practical Example

To make this concrete, consider a hypothetical order-management application, imagine a Rails monolith that’s been in production for years. It handles order creation, payment processing, shipment tracking, customer notifications, and reporting, all in one codebase.

The team decides to migrate customer notifications first. Notifications have a clear boundary, depend on a limited set of order data, and can be validated without impacting the critical path for order or payment processing.

Initially, the legacy application sends notifications directly after an order changes state:

# app/models/order.rb

class Order < ApplicationRecord
  after_update :send_status_notification, if: :saved_change_to_status?

  private

  def send_status_notification
    LegacyOrderMailer.status_changed(self).deliver_later
  end
end

Step 1: The legacy system publishes an event.

The first step is to introduce an event at the point where the order status changes. The specific mechanism depends on what’s already in the stack, this could be ActiveSupport::EventReporter, ActiveSupport::Notifications, a Sidekiq job if the codebase already leans on background jobs, or a message broker like Kafka or SQS if the team wants stronger decoupling from the start. The example below uses ActiveSupport::Notifications, since it requires no new infrastructure and is available in any Rails app.

The legacy application is changed to publish an event describing the change:

# app/models/order.rb

class Order < ApplicationRecord
  after_update :send_status_notification, if: :saved_change_to_status?
  after_update :publish_status_event, if: :saved_change_to_status?

  private

  def send_status_notification
    LegacyOrderMailer.status_changed(self).deliver_later
  end

  def publish_status_event
    ActiveSupport::Notifications.instrument(
        "order.status_changed",
        order_id: id,
        status: status,
        customer_id: customer_id,
        occurred_at: Time.current
        )
  end
end

This is the seam: a single, well-defined point where order status changes become observable to other systems, without yet changing who acts on them.

Step 2: The new notification service consumes the event.

For this example migration, the new notification logic lives in an isolated module within the same repository (app/services/notifications_v2/). A subscriber listens for order.status_changed and hands the payload off to a builder, which is defined in Step 3:

# app/services/notifications_v2/order_status_subscriber.rb

module NotificationsV2
  class OrderStatusSubscriber
    ActiveSupport::Notifications.subscribe("order.status_changed") do |*args|
      event = ActiveSupport::Notifications::Event.new(*args)
      # MessageBuilder#build_and_log is shown in Step 3.
      # Here we construct and log a message, it does not send anything.
      NotificationsV2::MessageBuilder.new(event.payload).build_and_log
    end
  end
end

At this point, nothing customer-facing has changed. The new service is simply listening and building notifications for its own internal record.

Step 3: Notifications are generated by both systems, but sent only by the legacy system.

The legacy application continues to send every notification, exactly as before. The new service does not send anything, instead it generates what it would send, but its output is logged rather than delivered:

# app/services/notifications_v2/message_builder.rb

module NotificationsV2
  class MessageBuilder
    def initialize(payload)
      @payload = payload
    end

    def build_and_log
      message = build_message
      ComparisonLog.record(
        order_id: @payload[:order_id],
        source: "notifications_v2",
        message: message
      )
      message
    end

    private

    def build_message
      # message construction logic
    end
  end
end

For this comparison to mean anything, the legacy mailer also needs to log what it actually sends. A small change records that:

# app/mailers/order_mailer.rb

class LegacyOrderMailer < ApplicationMailer
  def status_notification(order)
    LegacyNotificationLog.record(
      order_id: order.id,
      message: notification_body(order)
    )
    mail(to: order.customer.email, subject: "Order update")
  end
end

Step 4: Outputs are compared.

A comparison job checks the legacy system’s sent notifications against the new service’s logged output for the same events, flagging any mismatches in content, timing, or recipients:

# app/jobs/notification_comparison_job.rb

class NotificationComparisonJob < ApplicationJob
  def perform(order_id)
    legacy = LegacyNotificationLog.for_order(order_id)
    new_service = ComparisonLog.for_order(order_id)

    unless legacy.message == new_service.message
      MismatchReporter.report(order_id:, legacy:, new_service:)
    end
  end
end

This shadow period gives the team production evidence without changing customer-facing behavior. Differences can be reviewed to determine whether there are defects in the new service or undocumented behavior in the legacy application.

Step 5: The new service starts sending notifications.

Once mismatches have dropped to zero (or an accepted, understood baseline), a feature flag controls which implementation sends the notification. Before the flag is enabled, the new service is updated to actually deliver notifications. The MessageBuilder gains a build_and_send path alongside the existing build_and_log, using the same message construction logic already validated during the shadow period. The subscriber checks the feature flag to decide which path to call.

# app/models/order.rb

class Order < ApplicationRecord
  after_update :send_status_notification, if: :saved_change_to_status?
  after_update :publish_status_event, if: :saved_change_to_status?

  private

  def send_status_notification
    # Legacy mailer runs when the flag is off; new system takes over when enabled
    LegacyOrderMailer.status_notification(self).deliver_later unless Feature.enabled?(:modern_order_notifications, customer)
  end

  def publish_status_event
    # Always fires; the subscriber decides whether to act or just log
    ActiveSupport::Notifications.instrument(
        "order.status_changed",
        order_id: id,
        status: status,
        customer_id: customer_id,
        occurred_at: Time.current
        )
  end
end

The flag can first be enabled for internal accounts, then for a small percentage of customers, and eventually for all traffic. During the rollout, the team monitors delivery failures, processing times, duplicate notifications, and differences in message content.

Step 6: Notification code is removed from the legacy application.

The legacy notification-sending code is deleted, not just disabled. This includes everything from templates, delivery logic and related configuration. This is the step that actually pays down technical debt, everything before it was preparation.

# app/models/order.rb

class Order < ApplicationRecord
  after_update :publish_status_event, if: :saved_change_to_status?

  private

  def publish_status_event
    ActiveSupport::Notifications.instrument(
        "order.status_changed",
        order_id: id,
        status: status,
        customer_id: customer_id,
        occurred_at: Time.current
        )
  end
end

Step 7: The team moves on to shipment tracking.

With one capability fully migrated and one seam retired, the same process (publish an event, build the new implementation, compare outputs, cut over, remove the old code) is applied to the next capability. Order creation, payment processing, and reporting remain untouched in the legacy system for now, each waiting its turn.

Nothing in this example required stopping the order-management system, freezing feature work, or making a single high-stakes cutover. The legacy and new systems coexisted for exactly as long as it took to validate one piece of functionality.

Conclusion

Replacing a legacy system does not require a single high-risk launch. As this post has covered, the strangler fig pattern offers a way to modernize gradually. It allows us to validate each replacement in production before committing to it, while keeping the business operating throughout the transition.

It is particularly useful when the legacy system is large enough that a full rewrite is not practical, must remain available, and cannot be replaced without interrupting ongoing feature development. It also works best when the application contains distinct capabilities that can be separated and migrated independently.

The pattern may be unnecessary for a small system that can be replaced safely in a short period. For a large, business-critical application, however, spreading risk across a series of controlled releases is often more practical than concentrating it in one cutover.

Technical debt reduction, approached this way, stops being a single high-stakes project and becomes something closer to routine engineering practice. Done well, modernization becomes a sequence of measurable and reversible improvements. Each step reduces the scope of the legacy system, lowers a specific source of technical debt, and creates a safer foundation for the next migration.

Is your Rails application carrying more legacy code than it should? We can help.

So eventually the question will appear: what would it take to delete all of this and use a Rails-way solution like Hotwire? The honest answer is “it depends.” In this article, we will go through what the code difference actually looks like, what you can expect from bundle size, which pain points to plan for, and how to scope the work before committing to it.

The code difference

Creating a plain list of todos in classic React + Redux takes an action creator, a reducer, and a connected component. That is three JS files, plus an API controller and serializer on the Rails side. Redux Toolkit collapses a lot of this boilerplate, but the apps that raise this question are rarely on it:

// actions/todos.js
export const fetchTodos = () => async (dispatch) => {
  dispatch({ type: "FETCH_TODOS_REQUEST" });
  try {
    const res = await fetch("/api/todos");
    dispatch({ type: "FETCH_TODOS_SUCCESS", payload: await res.json() });
  } catch (e) {
    dispatch({ type: "FETCH_TODOS_FAILURE", error: e.message });
  }
};

// reducers/todos.js
const initialState = { items: [], loading: false, error: null };
export default function todos(state = initialState, action) {
  switch (action.type) {
    case "FETCH_TODOS_REQUEST": return { ...state, loading: true };
    case "FETCH_TODOS_SUCCESS": return { ...state, loading: false, items: action.payload };
    case "FETCH_TODOS_FAILURE": return { ...state, loading: false, error: action.error };
    default: return state;
  }
}

// components/TodoList.jsx
class TodoList extends Component {
  componentDidMount() { this.props.fetchTodos(); }
  render() {
    const { items, loading } = this.props;
    if (loading) return <p>Loading…</p>;
    return <ul>{items.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
  }
}
export default connect((s) => ({ items: s.todos.items, loading: s.todos.loading }), { fetchTodos })(TodoList);

The same feature in Hotwire would require only a controller and a view, no store, no serializer, no loading state, because the server sends HTML that’s already populated:

# app/controllers/todos_controller.rb
class TodosController < ApplicationController
  def index
    @todos = current_user.todos
  end
end

<%# app/views/todos/index.html.erb %>
<ul>
  <% @todos.each do |todo| %>
    <li><%= todo.title %></li>
  <% end %>
</ul>

That gap is why the migration is worth doing, and it’s also where the cost comes from. Porting a screen means deleting a whole layer and moving its responsibilities back to the server, which is slower work than translating code line for line. That cost lands on developers, and it’s paid during the migration rather than after.

It’s hard to port a screen mechanically. Each one has to be rethought: where its state lived, what the server can render directly, and what genuinely needs to stay in JavaScript. The client-side tests won’t carry over either, so every flow has to be re-covered.

Interactivity

Hotwire covers interactivity in two ways. For server-driven updates, Turbo Streams replace just the piece that changed, no reducer, no re-rendering the whole list. A simple toggle action that used to be a Redux action and a connected component becomes a single controller action and a Turbo Stream view that re-renders the todo partial:

<%# app/views/todos/toggle.turbo_stream.erb %>
<%= turbo_stream.replace @todo %>

For client-side behavior, a small Stimulus controller replaces what used to be a stateful component. The mental shift is the whole point: a Redux store that mirrors the database makes the client the source of truth and syncs it to the server; Hotwire keeps the server as the source of truth.

The case for the second model isn’t speed. React can be fast, and on most screens users won’t feel the difference either way. The real cost is keeping two copies of the truth in sync: every mutation updates the server, then reconciles the local store, invalidates its cache, and manages its own loading, error, and rollback states. A data layer like React Query or RTK Query automates much of that, but the apps that prompt this question are usually on a hand-rolled Redux store where all of it is yours to maintain.

Hotwire deletes most of that work: with one source of truth, there’s no client store to reconcile. Cache invalidation is still yours, and Turbo’s page cache can still show a stale preview on a restoration visit, but you maintain one copy of the truth instead of two. Where a screen genuinely needs rich client state, React earns that overhead; most screens don’t, and that’s the trade the migration is really making.

Bundle size

This is the number stakeholders actually feel. react + react-dom alone are about 45 KB gzipped before Redux, the router, and your own code, and a mature SPA bundle usually lands in the low hundreds of KB gzipped. Turbo and Stimulus together are about 35 KB gzipped, and with importmaps you can often drop the JS build step entirely. That leaves a hundred KB or more of JavaScript that never has to be downloaded, parsed, and executed on every page load.

What drives the cost, and what bites

Two apps with the same page count can differ in effort by an order of magnitude. The estimate is driven by how much genuine client-side state and app-like behavior you have (optimistic UI, wizards, real-time dashboards, drag-and-drop), far more than by raw page count.

A handful of pain points show up in this work every time, and they are worth planning for before the first screen moves.

Most of the Redux store turns out to be server state in disguise, and it disappears along with the API that fed it. The hard cases are optimistic UI and unsaved multi-step forms, and for each of those you have to decide deliberately whether it becomes a server round trip, a bit of Stimulus state, or a screen you leave in JavaScript for now. Routing is a similar story. Anything stored in the front-end route, a modal as a URL or a wizard step, needs a home on the server, so it’s worth verifying deep links, the back button, and scroll restoration as you go.

The complex widgets deserve to be identified first. They are usually the wrong thing to rebuild in Hotwire and the right thing to keep as islands, since reimplementing a mature JS date picker or drag-and-drop grid in Stimulus is where effort tends to blow up. The JSON API is easier to reason about: if it only feeds React, you delete it along with the front end, but if a mobile app or a partner also consumes it, you will be maintaining two paradigms for the length of the transition.

Testing and authentication are the two slices teams tend to underestimate. The React app’s component tests won’t translate, and end-to-end coverage of the flows you touch is what makes this safe, so expect to write tests ideally before each migration rather than after. And if the SPA authenticates with tokens, moving to Rails sessions and cookies touches login, session expiry, and CSRF, which is enough surface area to plan as its own slice instead of folding it into a screen.

How to scope it

A practical approach is to turn the unknown into a spreadsheet: inventory every screen, Redux slice, and front-end-only API endpoint, then bucket each screen. A trivially server-rendered, B needs a Stimulus sprinkle, C needs a real JS island, D stays as React for now.

Starting with the A/B buckets gets the cheapest wins first, and builds the team’s Hotwire fluency before anything hard gets touched. It’s the same logic we apply to upgrading Rails in increments, where small shippable slices beat a long-lived branch. To keep the work fundable, track numbers people can watch: lines of JavaScript deleted, dependencies removed, bundle size, and screens migrated out of the total.

Conclusion

One caveat before you start: this work pays off least when the app is genuinely application-like, such as heavy real-time collaboration, serious offline support, or rich client state a round trip would ruin. There the SPA earns its keep, and the better investment is modernizing it.

For everything else, the honest estimate comes out of the inventory: how many screens land in the A and B buckets, how many complex widgets you have to keep as islands, and how much of the Redux store turns out to be server state in disguise. Start with the cheap buckets, track the numbers people can watch, and let the hard screens wait until the team has the Hotwire fluency to handle them. One thing worth keeping in mind: the D bucket is allowed to stay a D bucket. An app that serves most of its screens with Hotwire and keeps three React islands is a perfectly reasonable place to stop, and stopping there is usually cheaper than chasing the last few screens.

Weighing a move off React and Redux and want a realistic read on the cost and the right incremental path? Talk to us today!

Which is why, after more than a decade at 0.x, we were super excited to see SimpleCov ship its first stable release on July 12, 2026. In this article we’d like to share the details on the breaking changes, the deprecations and how to address them, if you’re impacted by them.

Everything below refers only to the 1.0.0 entry in the changelog.

Also, it’s worth noting that the minimum required Ruby version for this release is 3.2.

Breaking changes

How filters match paths

Two related changes can quietly alter which files end up in your report.

The first is that SourceFile#project_filename now returns a relative path, lib/foo.rb instead of /lib/foo.rb, which affects any anchored RegexFilter that relied on the leading slash. Because this breaks without a warning, you need to grep your codebase for patterns relying on the leading slash:

grep -rn "add_filter\|remove_filter\|add_group" .simplecov spec/spec_helper.rb test/test_helper.rb

Any pattern that anchors on a slash needs rewriting:

# Before
add_filter %r{^/lib/}

# After
add_filter %r{\Alib/}

The second change is that StringFilter now matches at path-segment boundaries, so "lib" matches /lib/ but no longer matches /library/. If you were deliberately relying on substring behavior, like saying add_filter "_spec" to catch user_spec.rb, switch that filter to a Regexp:

# Before: matched anything containing the substring
add_filter "generated"

# After: explicit substring matching
add_filter(/generated/)

This change has one very important observation to note, however: An argument containing a dot is still treated as a filename pattern and still matches as a substring, so add_filter "test.rb" continues to catch faked_test.rb. A trailing slash likewise still means directory-only matching. Only dot-free arguments like "lib" or "_spec" became segment-anchored.

The status line moved to stderr

The “Coverage report generated for X to Y” line, and the per-criterion totals under it, now go to stderr instead of stdout. If a CI script of yours parsed that line from stdout, it will now see nothing. You can suppress the message entirely on the formatter:

SimpleCov.formatter = SimpleCov::Formatter::HTMLFormatter.new(silent: true)

Or you can restore the old behavior at the call site:

bundle exec rspec 2>&1

HTMLFormatter now outputs coverage.json

SimpleCov used to automatically activate JSONFormatter when the CC_TEST_REPORTER_ID environment variable was set, and that special case is gone. It is no longer needed, because the default HTMLFormatter now writes coverage.json alongside the HTML report, serializing the same payload JSONFormatter would. If you relied on the old auto-activation and you weren’t using the HTML formatter, you’ll need to add either the JSONFormatter or the HTMLFormatter explicitly. Note that only one of them is needed and using HTMLFormatter gives you the JSONFormatter output plus the HTML report.

coverage.json schema change

coverage.json changed shape, from { "covered_percent": 80.0 } to the full { "covered": 8, "missed": 2, "total": 10, "percent": 80.0, "strength": 0.0 }, with covered_percent renamed to percent. On a related note, both simplecov_json_formatter and simplecov-html have been merged into the main gem. The old requires still work through a shim, so you can drop the separate gems from your Gemfile whenever it is convenient.

SimpleCov.start now loads the test_frameworks profile by default

Calling SimpleCov.start with no arguments now loads the test_frameworks profile by default, which filters out paths under test/, spec/, features/, and autotest/. Rails applications usually call SimpleCov.start "rails" instead, and the rails profile has loaded test_frameworks for as long as the profile has existed, so those projects need no change.

If you do call start with no arguments, your report will drop its overall coverage percentage, and how much depends on the ratio of test code to application code. Should you also set the minimum_coverage attribute and the new number fall below that threshold, you’ll need to either establish a new acceptable threshold or remove the filters:

# Option A: accept the more honest number and re-baseline the threshold
SimpleCov.minimum_coverage 80

# Option B: keep the old behavior by dropping the new filter
SimpleCov.start do
  remove_filter %r{\A(test|features|spec|autotest)/}
end

Option B is genuinely useful if you want to surface dead test helpers that nothing calls anymore. For everything else, re-baselining is the better move. If the number you land on is lower than you are comfortable with, we put together 10 strategies for upgrading apps with low test coverage that should help.

Parallel waits and two removals

Under parallel_tests, SimpleCov now waits in the first process rather than the last, using ParallelTests.first_process?, which matches what the parallel_tests README recommends. For most people this fixes a deadlock, and the old PARALLEL_TEST_GROUPS=1 workaround is no longer needed. The rare project that wired up its own wait_for_other_processes_to_finish in an after(:suite) hook keyed on last_process? now hits the symmetric deadlock and has to switch to first_process?.

Two removals round out this section. SimpleCov.coverage_criterion is gone and primary_coverage (or coverage :branch, primary: true) replaces it and the docile dependency is gone too, with SimpleCov.configure blocks now evaluated via instance_exec and instance variable proxying, which needs no action on your side unless you were doing something exotic inside a configure block.

Deprecations

Below we give a small description of the deprecations that were created in this version. While these don’t break now, we recommend effecting these changes so that future upgrades go smoothly.

The configuration API was redesigned

The config API has been reorganized around a smaller, more consistent set of verbs:

Most of these are a straight rename:

# Before
SimpleCov.start do
  add_filter "/vendor/"
  add_group "Services", "app/services"
  use_merging true
end

# After
SimpleCov.start do
  skip "/vendor/"
  group "Services", "app/services"
  merging true
end

The one to pay attention to is cover. It includes unloaded files the way track_files did, but it also restricts the report to the matching set given to it, so a single cover "lib/**/*.rb" will drop app/ from your report entirely. To keep the old behavior, pass every directory you want reported:

# Before
track_files "lib/**/*.rb"

# After: list everything, not just the previously-tracked glob
cover "lib/**/*.rb", "app/**/*.rb"

SimpleCov.start cannot be called from .simplecov

Calling SimpleCov.start from .simplecov is deprecated. Tracking still begins for backward compatibility, but you get a one-time warning, and a future release will require the explicit call to live in spec_helper.rb or test_helper.rb. Treat .simplecov as configuration only:

# .simplecov
SimpleCov.configure do
  skip "/spec/"
  minimum_coverage 90
end

# spec/spec_helper.rb, at the very top, before anything else is required
require "simplecov"
SimpleCov.start "rails"

:nocov: comments and associated configurations are deprecated

This means specifically the SimpleCov.nocov_token and SimpleCov.skip_token configurations. Every file still using # :nocov: emits a one-time warning to stderr at load time. Instances of # :nocov: must be replaced with the new directive comments, # simplecov:enable and # simplecov:disable:

# Before
# :nocov:
def hard_to_test
  legacy_thing
end
# :nocov:

# After
# simplecov:disable
def hard_to_test
  legacy_thing
end
# simplecov:enable

It’s worth mentioning that the directive comments also allow you to specify if you want to disable only line, branch or method coverage, like so: # simplecov:disable line. By default, all 3 are enabled.

branches_coverage_percent and methods_coverage_percent are deprecated

This will likely affect you only if you have custom formatters. SimpleCov::SourceFile#branches_coverage_percent and #methods_coverage_percent are now replaced by covered_percent which take a criterion argument that defaults to :line:

# Before
file.branches_coverage_percent
file.methods_coverage_percent

# After
file.covered_percent(:branch)
file.covered_percent(:method)

minimum_coverage_by_* setters deprecated

Finally, the minimum_coverage_by_file and minimum_coverage_by_group setters give way to the new coverage method’s minimum_per_file and minimum_per_group verbs:

# Before
SimpleCov.minimum_coverage_by_file line: 70, "app/x.rb" => 100

# After
SimpleCov.coverage(:line) do
  minimum_per_file 70
  minimum_per_file 100, only: "app/x.rb"
end

The no-arg getters are unchanged, and only the setter forms warn.

New features worth your time

Once you are migrated, there is a real payoff here.

Configuring criteria and scoping the report

The new criterion-first coverage method configures each criterion (:line, :branch, :method) in one place, with identical syntax regardless of which one you are configuring:

SimpleCov.start do
  coverage :line do
    minimum 90
    minimum_per_file 80
    maximum_drop 5
  end

  coverage :branch, minimum: 80, primary: true
end

The options are minimum, maximum, exact, maximum_drop, minimum_per_file (with only: overrides), and minimum_per_group.

Alongside it, SimpleCov.cover finally provides an allowlist. Where add_filter could only ever subtract, cover is the positive counterpart:

SimpleCov.start do
  cover "app/**/*.rb", "lib/**/*.rb"
end

It accepts string globs, Regexps, blocks, or arrays of those, and multiple calls union together.

Finally, if you want to start from a blank slate, SimpleCov.no_default_skips opts out of the filters SimpleCov.start installs.

Directive comments and synthetic branches

On the branch side, SimpleCov.ignore_branches lets you opt out of the synthetic :else branches that Ruby’s Coverage library reports for constructs with no literal else keyword, which includes exhaustive case/in matches, case/when without else, ||=, &&=, and if or unless without else:

SimpleCov.start do
  enable_coverage :branch
  ignore_branches :implicit_else
end

Rails applications get something else useful here: ignore_branches :eval_generated and the new ignore_methods :eval_generated drop the phantom branch and method entries that macros like delegate inject.

Parallel runners

SimpleCov’s coordination with parallel runners now goes through a pluggable SimpleCov::ParallelAdapters chain instead of hard-coding the parallel_tests gem’s API. Two adapters ship, one wrapping the parallel_tests gem and a generic one for any runner following the TEST_ENV_NUMBER and PARALLEL_TEST_GROUPS convention. Custom runners can register their own adapter by subclassing SimpleCov::ParallelAdapters::Base. There is also a new SimpleCov.parallel_wait_timeout (default 60 seconds) for the case where one worker runs much heavier files and routinely finishes well after the others, so raise it if you want that worker’s coverage in the merge rather than having the threshold checks run against a partial total.

Conclusion

There are other features we decided not to mention for brevity’s sake. They can all be found in the changelog, at any rate. Given what has changed, most migrations to SimpleCov 1.0 should be straightforward and we recommend to go through with it because the new features add many quality of life improvements for gathering good coverage reports especially in CI, which is essential for dealing with tech debt and guaranteeing your app is functioning as expected.

Here at FastRuby.io we use SimpleCov heavily and it’s one of the staple gems we always end up recommending to clients if they aren’t using anything.

If you want to also know what we can do for you and your team to make you move faster and not get dragged down by endless bugs, performance issues and legacy problems no one understands anymore, send us a message and let’s talk!.

Resources and Further Reading

• SimpleCov 1.0.0 changelog
• SimpleCov README
• Ruby’s Coverage library