In a Rails app, what is db/schema.rb, what writes it, and why do teams commit it instead of editing it by hand?
answer
- a dump of the live database
- rewritten after migrate and rollback
- ActiveRecord::Schema[8.1].define(version: ...)
- the source for new databases
- 8.1.4 reverted alphabetical columns
basics
~20 sdb/schema.rb is Active Record's Ruby snapshot of the current database structure, rewritten from the live database after db:migrate and db:rollback. Teams commit it because new and test databases are built from it, and hand edits are overwritten at the next dump.
solid answer
~40 s`db/schema.rb` is produced by Active Record's schema dumper, which **inspects the database** and writes tables, columns, indexes, check constraints and foreign keys as Ruby inside `ActiveRecord::Schema[8.1].define(version: 2026_10_05_181200)`. The `version:` is the highest applied migration. Rails rewrites it after `db:migrate`, `db:rollback` and `db:schema:dump`, except where `dump_schema_after_migration` is false, as in the generated `production.rb`. It is committed because `db:schema:load`, `db:setup`, `db:prepare`, a fresh `db:migrate` and the test database are all built from it. Editing it by hand does not change any database and is overwritten by the next dump. Column order is version-sensitive: Rails 8.1.0 sorted columns alphabetically, and 8.1.4 reverted that, so columns follow the database's own order again.
code
bash · 3 linesbin/rails db:migrate # migrates, then rewrites db/schema.rb
bin/rails db:schema:dump # rewrite it from the current database only
git add db/migrate db/schema.rbgo deeper
Know that schema.rb is generated from the database after migrations, is committed, and is never edited by hand.
Explain what the version line means, what the dumper includes and leaves out, and which tasks build databases from the file.
Review schema.rb diffs as the true record of a migration's effect, and explain patch-release churn such as the 8.1 column-order change and its revert.
Decide whether the Ruby dump or a SQL dump is the team's schema of record, given the database features the product relies on.
## A dump, not a source file Every Rails app with Active Record has a `db/schema.rb` (unless it switched to SQL dumps). The file begins with a comment that says what it is: > This file is auto-generated from the current state of the database. Instead of editing this file, please use the migrations feature of Active Record to incrementally modify your database, and then regenerate this schema definition. The **schema dumper** connects to the database, reads its catalogue, and writes what it finds as Ruby. Migrations change the database; the database is then dumped to the file. The direction never reverses: nothing reads `schema.rb` to change an existing database except an explicit schema load, which rebuilds tables from scratch. ## What it contains For an online-auction app it looks like this: ```ruby ActiveRecord::Schema[8.1].define(version: 2026_10_05_181200) do create_table "auctions", force: :cascade do |t| t.string "title", null: false t.integer "current_price_cents", default: 0, null: false t.datetime "closes_at", null: false t.datetime "created_at", null: false t.datetime "updated_at", null: false end create_table "bids", force: :cascade do |t| t.bigint "auction_id", null: false t.integer "amount_cents", null: false t.index ["auction_id"], name: "index_bids_on_auction_id" end add_foreign_key "bids", "auctions" end ``` - **Tables** in name order, each with `force: :cascade`, so loading the file recreates them. - **Columns** with type, `null:`, `default:`, `limit:` and the like; **indexes** inside each table block. - **Check constraints** in the table block and **foreign keys** at the end, once every table exists. Names that Rails generates itself (`fk_rails_...`, `chk_rails_...`) are left out, because loading regenerates them. - On PostgreSQL also **extensions** and **enum types**. - Not the internal `schema_migrations` and `ar_internal_metadata` tables, and nothing the Ruby DSL cannot express, such as triggers, functions and views. ## The version line `ActiveRecord::Schema[8.1]` pins the DSL to Rails 8.1 behaviour, as a migration's `[8.1]` does. `define(version: 2026_10_05_181200)` records the **highest migration version applied** to the database that was dumped, with underscores for readability. When the file is loaded into a new database, Rails inserts that version, and the version of every migration file below it, into `schema_migrations`, so `db:migrate` later runs only newer migrations. ## When it is rewritten - After `bin/rails db:migrate`, `db:rollback`, `db:migrate:redo` and the other migration tasks, through a hidden dump step. - On demand with `bin/rails db:schema:dump`. - **Not** in production by default: the generated `config/environments/production.rb` sets `config.active_record.dump_schema_after_migration = false`, because the committed file comes from development. ## Why commit it and never hand-edit it 1. **New databases come from it.** `db:schema:load`, `db:setup`, `db:reset`, `db:prepare` on a missing database, and since Rails 8.0 `db:migrate` on an empty one, all load this file instead of replaying migrations. 2. **The test database comes from it.** Rails keeps the test schema in step by loading the schema file. 3. **It is the readable summary.** It is the quickest place to see every column a model has. 4. **Hand edits do nothing useful.** Changing the file does not change any existing database, and the next dump overwrites the edit. If the edit is loaded somewhere first, that database now differs from every migrated one. ## Reading it in code review A migration's diff shows what someone intended; the `schema.rb` diff in the same commit shows what the database actually became. Reviewers look for: - a `version:` line that moved to the new migration's timestamp, which proves the file was regenerated after migrating; - unexpected changes in unrelated tables, a sign that the author's local database had drifted (a branch switched without rolling back, or a hand edit); - `null:`, `default:` and index options that differ from what the migration claims; - a missing `add_foreign_key` or `t.check_constraint` that the migration was supposed to add, which usually means the adapter did not support it. ## Column order across 8.1 patch releases | Rails version | Column order in `schema.rb` | |---|---| | up to 8.0 | the database's own column order | | 8.1.0 to 8.1.3 | alphabetical within each table | | 8.1.4 | the database's own order again: the sort was reverted | The 8.1.4 changelog gives the reason: alphabetical sorting "creates improper production tables when using `db:prepare`", because a database built from the dump got its columns in a different order from the migrated ones. An app moving through 8.1 patch releases may therefore see two large reorderings in `schema.rb` diffs. Teams that need an exact column order everywhere use the SQL dump format instead.
- Why does running db:migrate in production not rewrite db/schema.rb?The generated `production.rb` sets `config.active_record.dump_schema_after_migration = false`, so the dump step after migrating is skipped. That is intended: the committed `db/schema.rb` comes from development, where the same migrations ran, and a production server has no reason to write files into the app.
- Why did Rails 8.1.4 undo the alphabetical column sort added in 8.1.0?The changelog says alphabetical sorting "creates improper production tables when using `db:prepare`": a database created by loading the dump got columns in alphabetical order while migrated databases kept their real order. 8.1.4 went back to dumping columns in the database's own order.
- db/schema.rb is compiled from the migration files rather than read from the database
- Editing db/schema.rb by hand changes the database on the next db:migrate
- db/schema.rb lists every migration version that has been applied
- Rails 8.1.4 always writes schema.rb columns in alphabetical order
- db/schema.rb should be gitignored because each machine generates its own
Assumes Rails 8.1.4. Rails 8.1.0 began sorting schema.rb columns alphabetically and 8.1.4 reverted it, so the dump follows database column order again; the release notes and upgrade guide still describe the sort.