ombulabs/claude-code_rails-upgrade-skill / rails-upgrade
rails-upgrade
VerifiedAnalyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, querying version-specific changes, or answering what stands between the app and the next Rails version. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.
detection-scripts/patterns/rails-80-patterns.yml
View on GitHubversion: "8.0"
description: "Breaking change patterns for Rails 7.2 → 8.0 upgrade"
upgrade_findings:
high_priority:
- name: "Ruby version requirement"
kind: "breaking"
pattern: "^\\s*(?:ruby\\s*\\(?\\s*[\"'](?:=\\s*|~>\\s*(?=\\d+\\.\\d+\\.\\d))?|ruby-|ruby\\s+)?(?:1\\.\\d+|2\\.\\d+|3\\.[01])(?:\\.\\d+)*(?![\\d.])|^\\s*ruby\\s*\\(?\\s*[\"']~>\\s*[12]\\.\\d+(?![\\d.])"
exclude: ""
search_paths:
- "Gemfile"
- ".ruby-version"
- ".tool-versions"
explanation: "Rails 8.0 requires Ruby 3.2.0 or newer (rails.gemspec: required_ruby_version = '>= 3.2.0'). Apps on Ruby 3.1 or older fail to bundle. Flags a Ruby below 3.2.0 in .ruby-version or .tool-versions, and a Gemfile `ruby` line that rules it out (an exact version, or a `~>` whose upper bound is below 3.2.0); a requirement that still allows 3.2.0, such as `>=`, is not flagged"
fix: "Upgrade Ruby to 3.2.0+ before bumping Rails. Update Gemfile and .ruby-version, then `bundle update rails`"
variable_name: "RUBY_VERSION"
- name: "enum with keyword-arguments form"
kind: "breaking"
pattern: "^\\s*enum\\s+\\w+:\\s*"
exclude: ""
search_paths:
- "app/models/"
explanation: "Rails 8.0 removes the keyword-arguments form of enum (`enum status: { ... }, _prefix: true`). The 7.0 / 7.1 hash form (`enum :status, { ... }, prefix: true`) is now the only supported syntax. activerecord/CHANGELOG.md: 'Remove deprecated support for defining `enum` with keyword arguments.' Models still using the old form raise ArgumentError on class load — the app fails to boot"
fix: "Convert to the explicit form: `enum :status, { active: 0, archived: 1 }, prefix: true`. Mechanical migration; no runtime behavior change once converted"
variable_name: "ENUM_KWARGS"
- name: "assume_ssl configuration"
kind: "optional"
pattern: "force_ssl\\s*="
exclude: "assume_ssl"
search_paths:
- "config/environments/production.rb"
explanation: "Rails 8.0 introduces assume_ssl for better SSL handling behind proxies"
fix: "Add config.assume_ssl = true alongside force_ssl for proper SSL termination"
variable_name: "ASSUME_SSL"
- name: "sqlite3_deprecated_warning"
kind: "breaking"
pattern: "sqlite3_deprecated_warning"
exclude: ""
search_paths:
- "config/"
explanation: "sqlite3_deprecated_warning option removed in Rails 8.0"
fix: "Remove sqlite3_deprecated_warning configuration"
variable_name: "SQLITE3_WARNING"
- name: "belongs_to/has_many query_constraints: option"
kind: "breaking"
pattern: "query_constraints:"
exclude: ""
search_paths:
- "app/models/"
explanation: "Rails 8.0 removes the `query_constraints:` association option (deprecated in 7.2; activerecord/CHANGELOG.md 7.2: 'Association option `query_constraints` is deprecated in favor of `foreign_key`.'). At 8.0 it raises `ActiveRecord::ConfigurationError` at class load, so the model — and the app — fails to boot. Not mentioned in the official upgrade guide or release notes. Verify the match is an association option, not an unrelated query_constraints: hash key."
fix: "Pass the composite key as an Array to `foreign_key:` instead: `belongs_to :activity, foreign_key: [:activity_id, :school_id]`. AR maps an Array `foreign_key` to query_constraints internally on both 7.2 and 8.0, so the change is behavior-preserving and needs no dual-boot branch."
variable_name: "QUERY_CONSTRAINTS_OPTION"
- name: "warn_on_records_fetched_greater_than config"
kind: "breaking"
pattern: "warn_on_records_fetched_greater_than"
exclude: "^\\s*#"
search_paths:
- "config/"
explanation: "Rails 8.0 removes config.active_record.warn_on_records_fetched_greater_than. 7.2 still logs large result sets and warns that the setting is deprecated. On 8.0 the Active Record railtie calls ActiveRecord::Base.warn_on_records_fetched_greater_than= when ActiveRecord::Base loads, which raises `NoMethodError: undefined method 'warn_on_records_fetched_greater_than=' for class ActiveRecord::Base` (at boot with eager loading, otherwise on the first model access)"
fix: "Delete the line (safe on 7.2 and 8.0). To keep the check, subscribe to `sql.active_record` notifications and read `payload[:row_count]`, which both versions provide"
variable_name: "WARN_ON_RECORDS_FETCHED"
- name: "allow_deprecated_singular_associations_name config"
kind: "breaking"
pattern: "allow_deprecated_singular_associations_name"
exclude: "^\\s*#"
search_paths:
- "config/"
explanation: "Rails 8.0 removes config.active_record.allow_deprecated_singular_associations_name. On 7.2 the setter already does nothing but warn (the singular-name lookup in where was removed in 7.2). On 8.0 the Active Record railtie calls ActiveRecord::Base.allow_deprecated_singular_associations_name= when ActiveRecord::Base loads, which raises NoMethodError (at boot with eager loading, otherwise on the first model access)"
fix: "Delete the line. It has no effect on 7.2 either, so this is safe on both sides of a dual boot"
variable_name: "ALLOW_DEPRECATED_SINGULAR_ASSOCIATIONS_NAME"
- name: "commit_transaction_on_non_local_return config"
kind: "breaking"
pattern: "commit_transaction_on_non_local_return"
exclude: "^\\s*#"
search_paths:
- "config/"
explanation: "Rails 8.0 removes config.active_record.commit_transaction_on_non_local_return. On 7.2 the setter already does nothing but warn: a return, break or throw out of a transaction block always commits. On 8.0 the Active Record railtie calls ActiveRecord::Base.commit_transaction_on_non_local_return= when ActiveRecord::Base loads, which raises NoMethodError (at boot with eager loading, otherwise on the first model access)"
fix: "Delete the line. It has no effect on 7.2 either: a non-local return commits on both 7.2 and 8.0, so this is safe on both sides of a dual boot"
variable_name: "COMMIT_TRANSACTION_ON_NON_LOCAL_RETURN"
medium_priority:
- name: "Redis cache store"
kind: "optional"
pattern: "redis_cache_store|:redis_store"
exclude: "solid_cache"
search_paths:
- "config/environments/"
explanation: "Rails 8.0 defaults to Solid Cache - Redis is optional"
fix: "Keep Redis if working well, or migrate to Solid Cache for simpler infrastructure"
variable_name: "REDIS_CACHE"
- name: "Sidekiq/Redis queue"
kind: "optional"
pattern: "sidekiq|:sidekiq|:async"
exclude: "solid_queue"
search_paths:
- "config/application.rb"
- "config/environments/"
explanation: "Rails 8.0 defaults to Solid Queue - Sidekiq still works"
fix: "Keep Sidekiq if needed, or consider Solid Queue for database-backed jobs"
variable_name: "SIDEKIQ_QUEUE"
- name: "ActionCable Redis adapter"
kind: "optional"
pattern: "adapter:\\s*redis|:redis"
exclude: "solid"
search_paths:
- "config/cable.yml"
explanation: "Rails 8.0 defaults to Solid Cable - Redis adapter still works"
fix: "Keep Redis if needed, or migrate to Solid Cable"
variable_name: "CABLE_REDIS"
- name: "Kamal deployment"
kind: "optional"
pattern: "kamal|deploy\\.yml"
exclude: ""
search_paths:
- "config/"
- "Gemfile"
explanation: "Rails 8.0 includes Kamal for deployment"
fix: "Review Kamal configuration if upgrading deployment process"
variable_name: "KAMAL_DEPLOY"
- name: "Docker/Thruster"
kind: "optional"
pattern: "thruster"
exclude: ""
search_paths:
- "Gemfile"
- "Dockerfile"
explanation: "Rails 8.0 apps include Thruster for HTTP/2 and static assets"
fix: "Add thruster gem if using Docker deployment"
variable_name: "THRUSTER"
- name: "Database pool configuration"
kind: "optional"
pattern: "pool:\\s*\\d+"
exclude: "max_connections"
search_paths:
- "config/database.yml"
explanation: "A hard-coded pool: in database.yml is a sign the file predates the Rails 8.0 generator layout, which splits production into primary, cache, queue and cable databases for Solid Cache, Solid Queue and Solid Cable. Rails 8.0 reads a single-database file and the pool: key as 7.2 did, so nothing breaks"
fix: "Only if adopting Solid gems: split production into primary, cache, queue and cable entries, each non-primary one with its own migrations_paths (db/cache_migrate, db/queue_migrate, db/cable_migrate). Otherwise leave database.yml as it is"
variable_name: "DB_POOL"
- name: "to_time_preserves_timezone default (load_defaults below 8.0)"
kind: "deprecation"
pattern: "load_defaults[\\s(]+[\"']?[5-7]\\.\\d+\\b"
exclude: "^\\s*#"
search_paths:
- "config/application.rb"
explanation: "Rails 8.0 warns at boot, from an after_initialize hook, whenever `config.active_support.to_time_preserves_timezone` is anything other than `:zone`. `load_defaults 8.0` sets `:zone`, so the warning fires only for apps still on `load_defaults` 5.0 to 7.2 (value `:offset`: `DEPRECATION WARNING: to_time will always preserve the full timezone rather than offset of the receiver in Rails 8.1`). An app with no `load_defaults` line at all gets `false` and a different message (`... preserve the receiver timezone rather than system local time in Rails 8.1`); this line-based pattern cannot see a missing line, so check for that case by hand. The opt-in itself is absent when the warning fires, so the `load_defaults` value is the proxy signal. False positive: an app on `load_defaults` 7.2 that already sets `:zone` (in application.rb or an uncommented config/initializers/new_framework_defaults_8_0.rb) is still flagged"
fix: "Default fix: set the flag for this one deprecation, `config.active_support.to_time_preserves_timezone = :zone`, after `load_defaults` in config/application.rb. Aligning `load_defaults` to 8.0 also removes the warning, but it flips every other 8.0 default at the same time, so treat it as the follow-up in Workflow 12 (rails-load-defaults skill), which moves `load_defaults` one setting at a time after the upgrade ships. 7.2 accepts `:zone` and treats it like `true`, so set it unconditionally, no NextRails.next? branch needed. On 8.0 it is a behavior change: `to_time` returns a Time carrying the receiver's full zone (DST-aware) instead of a fixed UTC offset, so run the suite after adding the line. If the app also assigns the value directly elsewhere, that line keeps warning (see TO_TIME_PRESERVES_TIMEZONE_ASSIGNMENT). Delete the explicit line once `load_defaults 8.0` is in place: 8.1 deprecates the setting itself (see rails-81-patterns.yml TO_TIME_PRESERVES_TIMEZONE_CONFIG)"
variable_name: "TO_TIME_PRESERVES_TIMEZONE"
- name: "to_time_preserves_timezone assigned a value other than :zone"
kind: "deprecation"
pattern: "to_time_preserves_timezone\\s*=\\s*(?:true|false|nil|:offset)\\b"
exclude: "^\\s*#"
search_paths:
- "config/"
explanation: "Rails 8.0's `ActiveSupport.to_time_preserves_timezone=` warns for any value other than `:zone`: `false` / `nil` get `to_time will always preserve the receiver timezone rather than system local time in Rails 8.1`, `true` / `:offset` get `... preserve the full timezone rather than offset of the receiver in Rails 8.1`. An explicit assignment therefore keeps warning after `load_defaults 8.0`. The usual source is `config/initializers/to_time_preserves_timezone.rb` (`ActiveSupport.to_time_preserves_timezone = true`), which the Rails 4.2 generator added as a forward-compat shim and many apps still carry. An explicit `config.active_support.to_time_preserves_timezone = :offset` or `false` also warns"
fix: "Delete the direct `ActiveSupport.to_time_preserves_timezone = true` assignment (and the initializer file if that is all it holds). `load_defaults` 5.0 and later already set `true` on 7.2, and on 8.0 the after_initialize hook overwrites the direct assignment with the config value anyway, so removing it changes nothing on either side of the dual boot. For a `config.active_support.to_time_preserves_timezone = :offset` / `false` line, switch it to `:zone` or delete it once `load_defaults 8.0` is in place; `:zone` changes what `to_time` returns, so run the suite after the change"
variable_name: "TO_TIME_PRESERVES_TIMEZONE_ASSIGNMENT"
- name: "Routes drawn with multiple paths"
kind: "deprecation"
pattern: "^\\s*(?:get|post|put|patch|delete|match)\\s*\\(?\\s*(?:\"[^\"\\n]*\"|'[^'\\n]*'|:\\w+(?!\\w))\\s*,\\s*(?:\"[^\"\\n]*\"|'[^'\\n]*'|:\\w+(?!\\w))(?!\\s*(?:=>|:[^:]))"
exclude: ""
search_paths:
- "config/routes.rb"
- "config/routes/"
explanation: "Rails 8.0 deprecates passing more than one path to a single route call (`get \"/old1\", \"/old2\", to: \"foo#bar\"`). actionpack 8.0 Mapper#map_match warns `Mapping a route with multiple paths is deprecated and will be removed in Rails 8.1. Please use multiple method calls instead.` The routes are still drawn. 7.2 accepts the same call with no warning. An Array path (`get [\"/a\", \"/b\"], ...`) is a different shape: it draws no route at all on 7.2 or 8.0 and is not flagged here. Symbol paths (`get :a, :b`) are flagged; a call whose paths are built from variables is missed"
fix: "Write one route call per path: `get \"/old1\", to: \"foo#bar\"` and `get \"/old2\", to: \"foo#bar\"`, or loop: `%w[/old1 /old2].each { |path| get path, to: \"foo#bar\" }`. Works on 7.2 and 8.0, so no NextRails.next? branch is needed"
variable_name: "ROUTES_MULTIPLE_PATHS"
low_priority:
- name: "Sprockets usage (optional Propshaft migration)"
kind: "optional"
pattern: "sprockets|Sprockets"
exclude: "propshaft"
search_paths:
- "Gemfile"
- "config/"
- "app/assets/"
explanation: "Rails 8.0 makes Propshaft the default asset pipeline for new apps, but Sprockets stays a first-class citizen. Existing apps can keep Sprockets at 8.0 with no changes — sprockets-rails continues to ship and work. Migrating from Sprockets to Propshaft is a separate, opt-in modernization, not a fix-before-bump"
fix: "No action required for the version bump. Optionally migrate to Propshaft as a separate effort if you want the new defaults (faster, no preprocessing pipeline). See https://github.com/rails/propshaft"
variable_name: "SPROCKETS"
- name: "Asset pipeline configuration (sprockets-style)"
kind: "optional"
pattern: "config\\.assets\\."
exclude: ""
search_paths:
- "config/environments/"
- "config/initializers/"
explanation: "config.assets.* keys (compile, css_compressor, js_compressor, paths, version, debug, quiet, precompile) are Sprockets-era. They keep working at 8.0 if you stay on Sprockets. They become irrelevant only if you migrate to Propshaft, which is optional"
fix: "No action required for the version bump if you keep Sprockets. If migrating to Propshaft later, audit each key — Propshaft removes most of these knobs (no compilation step, no compressor configuration; minification is handled at the asset-source layer)"
variable_name: "ASSET_CONFIG"
- name: "javascript_include_tag (sprockets-style)"
kind: "optional"
pattern: "javascript_include_tag"
exclude: "importmap"
search_paths:
- "app/views/layouts/"
explanation: "javascript_include_tag is the Sprockets-era helper. It keeps working at 8.0 on the Sprockets pipeline. Import Maps / javascript_importmap_tags is the new-app default but is not required for the version bump"
fix: "No action required for the version bump. If migrating to Import Maps later, replace javascript_include_tag with javascript_importmap_tags and move JS bundling to importmap.rb"
variable_name: "JS_INCLUDE"
- name: "read_encrypted_secrets config"
kind: "breaking"
pattern: "read_encrypted_secrets"
exclude: "^\\s*#"
search_paths:
- "config/"
explanation: "Rails 8.0 removes config.read_encrypted_secrets. railties/CHANGELOG.md: 'Remove deprecated `config.read_encrypted_secrets`.' The setting drove the legacy encrypted-secrets feature (config/secrets.yml.enc), already dead since 7.2 removed `Rails.application.secrets`. The setter does not raise at 8.0: the assignment falls through to Railtie::Configuration#method_missing and is stored with no effect and no warning. Only the 7.2 side of a dual boot warns (`'config.read_encrypted_secrets=' is deprecated and will be removed in Rails 8.0`), which clutters boot and assets:precompile logs. 7.1 and earlier do not warn. Reading `config.read_encrypted_secrets` without assigning it first raises NoMethodError at 8.0"
fix: "Delete the `config.read_encrypted_secrets = true` line and its comment block (usually in config/environments/production.rb). Safe on both 7.2 and 8.0, no dual-boot branch needed. If the app still keeps secrets in config/secrets.yml.enc, move them to credentials (`bin/rails credentials:edit`) first"
variable_name: "READ_ENCRYPTED_SECRETS"
- name: "unsigned_float / unsigned_decimal in migrations"
kind: "deprecation"
pattern: "\\bunsigned_(float|decimal)\\b"
exclude: ""
search_paths:
- "db/migrate/"
explanation: "Rails 8.0 deprecates the `t.unsigned_float` and `t.unsigned_decimal` short-hand column methods. activerecord/CHANGELOG.md: 'Deprecate `unsigned_float` and `unsigned_decimal` short-hand column methods.' Background: as of MySQL 8.0.17 the UNSIGNED attribute is itself deprecated for FLOAT / DOUBLE / DECIMAL columns at the database level. Removed at 8.1 (see rails-81-patterns.yml MYSQL_UNSIGNED)"
fix: "Replace `t.unsigned_float :amount` with `t.float :amount, unsigned: true` (column-option form on integer / bigint stays unaffected). For DECIMAL, prefer a CHECK constraint on the value range"
variable_name: "UNSIGNED_FLOAT_DECIMAL"
- name: "ENV[\"SCHEMA_CACHE\"] usage"
kind: "breaking"
pattern: "ENV\\[['\"]SCHEMA_CACHE['\"]\\]|\\bSCHEMA_CACHE="
exclude: ""
search_paths:
- "config/"
- "lib/"
- "bin/"
- ".github/"
- ".circleci/"
explanation: "Rails 8.0 removes the last trace of ENV[\"SCHEMA_CACHE\"]. activerecord 7.1 read it as the schema cache dump path; 7.2 already ignores it and only warns (`Setting ENV[\"SCHEMA_CACHE\"] is deprecated and will be removed in Rails 8.0`); 8.0 ignores it with no warning. A script or CI step that sets it has used the default db/schema_cache.yml since 7.2"
fix: "Set `schema_cache_path:` on the database entry in config/database.yml and drop the SCHEMA_CACHE variable. The key works on both 7.2 and 8.0, so no NextRails.next? branch is needed"
variable_name: "ENV_SCHEMA_CACHE"
- name: "Benchmark.ms"
kind: "deprecation"
pattern: "\\bBenchmark\\.ms\\b"
exclude: ""
search_paths:
- "app/"
- "lib/"
explanation: "Rails 8.0 deprecates the Active Support `Benchmark.ms` core extension. activesupport 8.0 lib/active_support/core_ext/benchmark.rb still returns the elapsed milliseconds but warns `Benchmark.ms is deprecated and will be removed in Rails 8.1 without replacement.` 7.2 has no warning. The method is defined by Active Support, not by the benchmark gem, so adding that gem does not keep it"
fix: "Replace `Benchmark.ms { ... }` with `Benchmark.realtime { ... } * 1000` (Ruby's benchmark library, seconds as a Float). Works on 7.2 and 8.0, so no NextRails.next? branch is needed. Add `require \"benchmark\"` where it is called: Active Support 8.0 requires the library, 8.1 no longer does, so without it the call raises NameError after the 8.1 bump. On Ruby 3.4 and newer also add `gem \"benchmark\"` to the Gemfile: Ruby 3.4 warns that benchmark leaves the default gems in Ruby 4.0"
variable_name: "BENCHMARK_MS"
- name: "rake stats"
kind: "deprecation"
pattern: "\\brake\\s+stats\\b"
exclude: ""
search_paths:
- "bin/"
- ".github/"
- ".circleci/"
- "Rakefile"
explanation: "Rails 8.0 deprecates `bin/rake stats` in favor of `bin/rails stats`. railties/CHANGELOG.md: 'Deprecate `bin/rake stats` in favor of `bin/rails stats`.' The rake task continues to work at 8.0 with a deprecation warning"
fix: "Replace `rake stats` with `rails stats` in CI configs, scripts, and developer docs"
variable_name: "RAKE_STATS"
dependencies:
propshaft:
check: true
gem_name: "propshaft"
message: "Rails 8.0 uses Propshaft instead of Sprockets for assets"
url: "https://github.com/rails/propshaft"
solid_cache:
check: false
gem_name: "solid_cache"
message: "Rails 8.0 includes Solid Cache for database-backed caching (optional)"
url: "https://github.com/rails/solid_cache"
solid_queue:
check: false
gem_name: "solid_queue"
message: "Rails 8.0 includes Solid Queue for database-backed jobs (optional)"
url: "https://github.com/rails/solid_queue"
solid_cable:
check: false
gem_name: "solid_cable"
message: "Rails 8.0 includes Solid Cable for database-backed WebSockets (optional)"
url: "https://github.com/rails/solid_cable"
kamal:
check: false
gem_name: "kamal"
message: "Rails 8.0 includes Kamal for deployment"
url: "https://kamal-deploy.org"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |