In a new Rails 8.1 app whose production database.yml lists primary, cache, queue and cable, how do db:migrate, db:migrate:primary and db:rollback behave?
answer
- one task family per named database
- each database has its own schema_migrations
- migrations_paths per database
- unnamed rollback raises in multi-db
- development stays single-database
basics
~10 sRails generates namespaced tasks per database. db:migrate migrates all four, each against its own migrations_paths and schema_migrations; db:migrate:primary only the primary. Unnamed db:rollback raises in a multi-database environment, so you run db:rollback:primary.
solid answer
~40 sSince Rails 8.0 the generated production `database.yml` is multi-database: `primary` plus `cache`, `queue` and `cable` for Solid Cache, Solid Queue and Solid Cable, each non-primary entry with its own `migrations_paths` such as `db/queue_migrate`. For every named database Rails defines namespaced tasks: `db:migrate:primary`, `db:migrate:queue`, `db:rollback:primary`, `db:migrate:status:queue`, `db:create:cache` and so on. Unnamed `db:migrate` migrates every database of the environment, each tracked in **its own** `schema_migrations` table and dumped to its own schema file. Unnamed `db:rollback`, `db:migrate:redo`, `db:migrate:up` and `db:migrate:down` raise in a multi-database environment and list the namespaced variants, so on such a server you write `bin/rails db:rollback:primary STEP=2`. The generated development config has a single database, so the plain tasks work there and the error first appears on staging or production.
code
bash · 5 linesRAILS_ENV=staging bin/rails db:migrate # every database
RAILS_ENV=staging bin/rails db:migrate:primary # primary only
RAILS_ENV=staging bin/rails db:rollback STEP=2 # raises: multiple databases
RAILS_ENV=staging bin/rails db:rollback:primary STEP=2
RAILS_ENV=staging bin/rails db:migrate:status:queuego deeper
Know that a new Rails 8 app has several production databases and that tasks such as db:migrate:primary exist for each one.
Explain per-database migrations_paths, version tables and schema files, which unnamed tasks work, and which raise in a multi-database environment.
Write deploy and rollback runbooks with the namespaced tasks, and know which database a migration belongs to before it runs on a server.
Decide whether the Solid databases stay separate or fold into the primary, weighing isolation against simpler operations.
## What Rails 8.1 generates `rails new` writes a `config/database.yml` whose **development** and **test** sections each describe one database, while **production** is multi-database: ```yaml production: primary: <<: *default database: storage/production.sqlite3 cache: <<: *default database: storage/production_cache.sqlite3 migrations_paths: db/cache_migrate queue: <<: *default database: storage/production_queue.sqlite3 migrations_paths: db/queue_migrate cable: <<: *default database: storage/production_cable.sqlite3 migrations_paths: db/cable_migrate ``` The extra databases belong to Solid Cache, Solid Queue and Solid Cable. A staging environment copied from this config, as for the dental-practice app's staging server, is multi-database too. ## Each database is migrated on its own - **Migrations live per database.** The primary uses `db/migrate`; `queue` uses `db/queue_migrate`, and so on. - **Each database has its own `schema_migrations`** and `ar_internal_metadata`. The queue database's version rows are in the queue database. - **Each has its own schema file.** The primary dumps `db/schema.rb`; the others dump `db/<name>_schema.rb`, such as `db/queue_schema.rb`. - **Replicas are skipped.** An entry marked `replica: true`, or with `database_tasks: false`, gets no create, migrate or schema tasks. ## The task families For every named database, Rails defines namespaced variants of the common tasks: | Unnamed task | Namespaced variants | Unnamed form in a multi-database environment | |---|---|---| | `db:migrate` | `db:migrate:primary`, `db:migrate:queue`, ... | works: migrates every database | | `db:migrate:status` | `db:migrate:status:primary`, ... | works: prints a block per database | | `db:rollback` | `db:rollback:primary`, ... | **raises** | | `db:migrate:redo`, `:up`, `:down` | `db:migrate:redo:primary`, `db:migrate:down:queue`, ... | **raise** | | `db:create`, `db:drop`, `db:schema:load` | `db:create:cache`, `db:drop:queue`, ... | work across all | Unnamed `db:migrate` collects the pending versions of every database, sorts them, and runs each against the database it belongs to, so migrations across databases go in version order. The unnamed rollback-style tasks refuse because "the last migration" has no single meaning across four version tables. The error reads "You're using a multiple database application. To use `db:rollback` you must run the namespaced task" and lists `db:rollback:primary`, `db:rollback:cache` and the rest. ## Rolling back two migrations on staging ```bash RAILS_ENV=staging bin/rails db:migrate:status:primary RAILS_ENV=staging bin/rails db:rollback:primary STEP=2 ``` `STEP=2` now counts within the primary database only. The queue, cache and cable databases are untouched. ## A fresh server On a new production host, one `bin/rails db:prepare` handles all four databases: it creates each missing database, loads each one's schema file (`db/schema.rb` for the primary, `db/cache_schema.rb`, `db/queue_schema.rb` and `db/cable_schema.rb` for the others), runs whatever migrations are pending in each `migrations_paths`, and loads the seed file once, because by default only the primary's config allows seeds. Nothing about this needs a namespaced task. ## Why the error surprises people 1. Development uses one database, so `bin/rails db:rollback` works every day on a laptop. 2. The first time someone runs it against staging or production, the same command raises. 3. Scripts and runbooks written on a laptop therefore need the namespaced form before they meet a server. ## When the namespaced tasks exist Rails defines the `:primary`, `:queue` and other variants while loading its tasks, from the configurations of the **current** environment. If that environment has only one database, no namespaced tasks are defined at all, because there would be nothing to choose between. So: | Environment | `db:rollback` | `db:rollback:primary` | |---|---|---| | development (one database) | works | not defined | | staging or production (four databases) | raises, lists the variants | works | Calling a namespaced task where it is not defined fails with Rails' unrecognized-command error rather than doing anything, so a runbook's environment matters as much as its commands. Because the list comes from the configuration, adding a fifth database to staging's config adds a fifth family of tasks there, with no code change. ## Practical habits - Write server runbooks with the namespaced tasks (`db:rollback:primary`, `db:migrate:status:primary`). They exist only in an environment with more than one database, so the same command fails on a single-database laptop as an unrecognized command. - Use `db:migrate:status` without a name when you want to see all databases at once. - Remember that `db:prepare` and `db:migrate` act on every database of the environment, so a fresh server gets all four, each from its own schema file. - Generate migrations for a secondary database into its own `migrations_paths` (the migration generator takes `--database queue`), or they land in the primary's `db/migrate`.
- Where do queue database migrations go, and how are they tracked?In the directory named by the queue entry's `migrations_paths`, `db/queue_migrate` in the generated config. They are recorded in the queue database's own `schema_migrations` table, and the queue schema is dumped to `db/queue_schema.rb`, so the primary's history never mentions them.
- Why does bin/rails db:rollback work on a laptop but raise on staging?The generated development config has one database, so there is a single "last migration" to undo. Staging and production follow the multi-database production config, where unnamed `db:rollback` raises and asks for `db:rollback:primary` or another named variant.
- db:migrate touches only the primary database in a multi-database app
- All four databases share one schema_migrations table kept in the primary
- db:rollback STEP=2 rolls back two migrations in each of the four databases
- Queue migrations live in db/migrate alongside the primary's migrations
- A replica entry gets its own migrations run by db:migrate
Assumes Rails 8.1. Since Rails 8.0 the generated production database.yml declares primary, cache, queue and cable (Solid Cache, Solid Queue, Solid Cable), so production and staging are multi-database by default while development is not.