Skip to content

Document schema-format skew in dual boot#21

Draft
JuanVqz wants to merge 1 commit into
mainfrom
feature/schema-format-skew-caveat
Draft

Document schema-format skew in dual boot#21
JuanVqz wants to merge 1 commit into
mainfrom
feature/schema-format-skew-caveat

Conversation

@JuanVqz

@JuanVqz JuanVqz commented Jul 7, 2026

Copy link
Copy Markdown
Member

What

Documents a dual-boot hazard hit during a live Rails 7.2 -> 8.0 upgrade: db/schema.rb pins a schema-format version in its header, and the older boot cannot load a schema dumped by the newer boot.

Running any schema-dumping task (db:migrate, db:prepare, db:schema:dump) under the next boot rewrites the header (ActiveRecord::Schema[7.1] -> [8.0]) and can change dumper cosmetics (Rails 8.0 writes enable_extension "pg_catalog.plpgsql" instead of "plpgsql"). Once committed, the current-version CI job's db:schema:load breaks:

ArgumentError: Unknown migration version "8.0"; expected one of "4.2", ... , "7.2"

This matters because the skill's own CI examples run db:schema:load on both boots.

Changes

  • references/ci-configuration.md — new "Schema Format Skew" caveat: keep the committed db/schema.rb in the lower (current) format for the whole dual-boot window, prepare CI/dev DBs via db:schema:load on both boots (newer Rails loads the older format fine; the reverse fails), and git checkout db/schema.rb after any local db:migrate under the next boot.
  • workflows/cleanup-workflow.md — new step to regenerate db/schema.rb in the new format at cutover, with a warning to treat column-type churn (e.g. integer -> bigint) as a separate deliberate decision: it usually comes from a gem's migration helper (e.g. kt-paperclip's t.attachment), not the Rails bump, and may not match the actual production column. Subsequent steps renumbered.
  • CHANGELOG.md — Unreleased entry.

Verification

The ArgumentError was reproduced directly: loading a Schema[8.0]-format file under Rails 7.2.3.1 raises Unknown migration version "8.0", while Rails 8.0.5 loads a Schema[7.1] file without issue.

db/schema.rb pins a schema-format version in its header, and the older
boot cannot load a schema dumped by the newer boot -- loading a
Schema[8.0] file under Rails 7.2 raises `ArgumentError: Unknown
migration version "8.0"`. This breaks the current-version CI job's
db:schema:load, which the skill's own CI examples rely on.

- references/ci-configuration.md: add a "Schema Format Skew" caveat --
  keep the committed schema in the lower (current) format during the
  dual-boot window, prepare DBs via db:schema:load on both boots, and
  revert db/schema.rb after any migrate run under the next boot.
- workflows/cleanup-workflow.md: add a step to regenerate db/schema.rb
  in the new format at cutover, flagging column-type churn (e.g.
  integer -> bigint from a gem's migration helper) as a separate
  deliberate decision that may not match the production column.

Observed on a live Rails 7.2 -> 8.0 upgrade.
@JuanVqz JuanVqz self-assigned this Jul 7, 2026
@JuanVqz JuanVqz marked this pull request as draft July 7, 2026 20:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant