skip to content

Dump Formats & Versions

Rails snapshots the schema into db/schema.rb or, for triggers and views, db/structure.sql, and rebuilds databases from that dump. Interviewers ask which format to pick and why.

part ofRuby on Railsread it →
on this pageshow

explore

questions

5

In a Rails app, what is db/schema.rb, what writes it, and why do teams commit it instead of editing it by hand?

level: juniorimportance: must knowfreq 60%

answer

  1. a dump of the live database
  2. rewritten after migrate and rollback
  3. ActiveRecord::Schema[8.1].define(version: ...)
  4. the source for new databases
  5. 8.1.4 reverted alphabetical columns

basics

~20 s

db/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 lines
bash
bin/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.rb

go deeper

for a junior

Know that schema.rb is generated from the database after migrations, is committed, and is never edited by hand.

for a middle

Explain what the version line means, what the dumper includes and leaves out, and which tasks build databases from the file.

for a senior

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.

for a principal

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.

open as a page

In a Rails online-auction app, a trigger on bids created with execute is missing from db/schema.rb; why, and how does schema_format :sql fix it?

level: middleimportance: must knowfreq 50%

basics

~20 s

db/schema.rb holds only what Active Record's Ruby DSL can express, so a trigger made with execute is silently left out and every database built from the file lacks it. With schema_format :sql, Rails writes db/structure.sql with the database's own dump tool, trigger included.

open as a page

In Rails 8.1, why build a new database with db:schema:load instead of replaying every migration, and what does loading record?

level: middleimportance: should knowfreq 45%

basics

~20 s

Loading the schema file is one fast pass that cannot trip over old migrations whose models or gems have since changed. It recreates every table, then marks the file's version and every older migration as applied, and stores the environment and schema checksum.

open as a page

In Rails, how do timestamped migration versions behave when two branches each add a migration, and how do you resolve the db/schema.rb conflict?

level: middleimportance: should knowfreq 40%

basics

~20 s

Each migration's version is a UTC timestamp, so two branches rarely collide, but both rewrite db/schema.rb's version line and often the same tables. Resolve by migrating the merged code and committing the regenerated file, never by hand-picking lines.

open as a page

An online-auction Rails app has 900 migration files going back years; how do you prune old migrations safely, and what changes afterwards?

level: seniorimportance: nice to knowfreq 25%

basics

~20 s

Delete migration files only after every environment has run them and the committed schema file is correct, because new databases load that file. Old schema_migrations rows stay and show as NO FILE, and rollbacks can no longer reach the pruned range.

open as a page