skip to content

Connections & Replicas

database.yml sets each environment's connection, merged with DATABASE_URL, and declares replicas and shards that models reach through connects_to. Interviewers ask how reads move to a replica safely.

part ofRuby on Railsread it →
on this pageshow

explore

questions

6

In a Rails 8.1 app, how does config/database.yml declare each environment's connection, and what do its ERB tags and &default anchor do?

level: juniorimportance: must knowfreq 58%

answer

  1. one top-level block per RAILS_ENV
  2. ERB renders first, YAML parses second
  3. &default anchor, <<: *default merge
  4. max_connections, the 8.1 name for pool
  5. production: primary, cache, queue, cable

basics

~20 s

config/database.yml holds one top-level block per environment, picked by RAILS_ENV. Rails renders the file as ERB before parsing the YAML, so ENV lookups fill in values, and a &default anchor merged with <<: *default shares the common keys.

solid answer

~40 s

Each top-level key is an environment (`development`, `test`, `production`), and Active Record connects with the block that matches `RAILS_ENV`. A block carries `adapter`, `database`, credentials and pool settings; in Rails 8.1 the pool ceiling is `max_connections:`, which replaced the older `pool:` name. Rails renders the whole file as ERB first, so `<%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>` or `<%= ENV["PAYROLL_DATABASE_PASSWORD"] %>` is plain text by the time YAML parses it. The `&default` anchor plus `<<: *default` copies shared keys into each environment, and any key written beside the merge overrides the copied one. By default a new 8.1 app's production block is three-tier: `primary`, `cache`, `queue` and `cable` entries, each its own database with its own `migrations_paths`, so Solid Cache, Solid Queue and Solid Cable keep their tables out of the app's database.

code

yaml · 27 lines
yaml
default: &default
  adapter: postgresql
  encoding: unicode
  max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>

development:
  <<: *default
  database: payroll_development

test:
  <<: *default
  database: payroll_test

production:
  primary: &primary_production
    <<: *default
    database: payroll_production
    username: payroll
    password: <%= ENV["PAYROLL_DATABASE_PASSWORD"] %>
  cache:
    <<: *primary_production
    database: payroll_production_cache
    migrations_paths: db/cache_migrate
  queue:
    <<: *primary_production
    database: payroll_production_queue
    migrations_paths: db/queue_migrate

go deeper

for a junior

Know that each environment has its own block, that RAILS_ENV picks it, and that ERB tags let you read passwords and thread counts from ENV.

for a middle

Explain the load order (ERB, then YAML, then shared:), how anchors and merge keys resolve, and why 8.1 says max_connections instead of pool.

for a senior

Read a three-tier production block confidently: which entry is the default, why cache, queue and cable are separate databases, and how a bad ERB value fails at boot.

for a principal

Weigh how much connection config lives in database.yml versus environment variables, so each deploy target overrides only what differs without forking the file.

## What the file is for `config/database.yml` tells **Active Record** how to connect. Rails loads it at boot, picks the block whose top-level key matches the current environment (`RAILS_ENV`, which defaults to `development`), and opens connection pools from it. Other environments' blocks sit in the same file and are simply not used by that process for its own connections, which is why one file can describe a laptop's SQLite database and a production PostgreSQL cluster side by side. A block is a mapping of connection keys. The ones you meet in every app: - `adapter`: which driver Active Record loads (`postgresql`, `mysql2`, `trilogy`, `sqlite3`). - `database`: the database name, or for SQLite a file path such as `storage/development.sqlite3`. - `username`, `password`, `host`, `port`: where and as whom to connect. - `encoding`: the PostgreSQL template writes `unicode`. - `max_connections`: the most connections one process's pool may open. Rails 8.1 renamed it from `pool`, and the generated file reads it from `RAILS_MAX_THREADS` with a fallback of 5. - `migrations_paths`: where migrations for a non-primary database live. ## How Rails reads it: ERB first, then YAML The load order matters, because it explains most of the surprises: 1. Rails finds `config/database.yml` through `paths["config/database"]`. 2. `ActiveSupport::ConfigurationFile` renders the file as **ERB** when it contains `<%`, so every `<%= ... %>` tag is replaced by its output as raw text. 3. The rendered text is parsed as **YAML**, with anchors and aliases allowed. 4. A top-level `shared:` key, if you wrote one, is removed and reverse-merged into every environment, so the environment's own keys win. 5. Active Record turns each entry into a database configuration object and, for the current environment, merges in URL environment variables such as `DATABASE_URL`. Because ERB output is pasted in as text, a value that contains YAML-significant characters can break the parse or change the value's type. Rails then fails at boot with "YAML syntax error occurred while parsing" and the path of the file. ## Anchors and merge keys YAML anchors keep the file short. `default: &default` names a mapping, and `<<: *default` inside another mapping copies its keys in. Keys written explicitly next to the merge **override** the copied ones, so this works as expected: ```yaml default: &default adapter: postgresql max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %> production: <<: *default max_connections: 10 # wins over the anchored value ``` The generated PostgreSQL file uses a second anchor, `&primary_production`, so the `cache`, `queue` and `cable` entries inherit the primary's username and password and change only `database` and `migrations_paths`. ## Two-tier and three-tier blocks | Shape | What it looks like | What Rails builds | |---|---|---| | **Two-tier** | `development:` holding `adapter`, `database`, ... | one configuration named `primary` | | **Three-tier** | `production:` holding `primary:`, `cache:`, `queue:`, `cable:` | one named configuration per entry | In a three-tier block, the entry called `primary` is the default connection; without one, Rails uses the first entry. A new Rails 8.1 app writes a three-tier production block (unless you pass `--skip-solid`): **Solid Cache**, **Solid Queue** and **Solid Cable** store their data in database tables, and each gets its own database (`payroll_production_cache`, `payroll_production_queue`, `payroll_production_cable` for PostgreSQL, or files under `storage/` for SQLite) and its own `migrations_paths` (`db/cache_migrate`, `db/queue_migrate`, `db/cable_migrate`). Each library's own config file points at its entry by name. Development and test stay two-tier in the generated file. ## Mistakes interviewers listen for - Treating the file as static YAML and loading secrets in an initializer instead of with an ERB `ENV` lookup. - Writing `pool:` in a new 8.1 file. Rails 8.1 still reads `pool:` as a fallback, but setting both `pool` and `max_connections` to different values raises an "Ambiguous configuration" error at boot. - Expecting the anchored `default` to beat a key written in the environment block. It is the other way round. - Committing a production password as a literal instead of reading it from the environment or credentials. - Assuming a fresh app keeps cache and jobs in Redis: in 8.1 they are the `cache` and `queue` database entries. ## Checking what Rails actually loaded Reasoning about anchors, ERB and environment variables in your head is error-prone, so ask the running app. In `bin/rails console`, `ActiveRecord::Base.configurations.configs_for(env_name: "production")` lists every entry Rails built for that environment, each with its `name` and `configuration_hash`, and `ActiveRecord::Base.connection_db_config` shows the one the current model connection uses. Comparing that hash with the file is the quickest way to spot an override you did not expect, such as a merged `DATABASE_URL` or a `shared:` key leaking in.

  • What does a top-level shared: key in database.yml do?
    Rails removes `shared:` after parsing and reverse-merges it into every environment, so keys an environment sets itself win. In three-tier blocks, if `shared:` is keyed by entry name (`shared: { primary: {...} }`) each entry gets its matching part; otherwise every entry gets the whole hash. It removes repetition without anchors.
  • Why does a new Rails 8.1 app's production block list cache, queue and cable entries?
    Rails 8 ships Solid Cache, Solid Queue and Solid Cable, which keep cache entries, jobs and cable messages in database tables. The generator gives each its own database entry with its own `migrations_paths` (`db/cache_migrate`, `db/queue_migrate`, `db/cable_migrate`), so that load and schema stay apart from `primary`. Each library's config names its entry, and `--skip-solid` writes a single production block instead.

  • database.yml is plain YAML, so ENV values must be injected from an initializer.
  • A new Rails 8.1 database.yml sets the pool ceiling with the pool: key.
  • Keys pulled in by <<: *default override keys written in the environment block.
  • A fresh Rails 8.1 app has one production database and keeps cache and jobs in Redis.
  • ERB tags in database.yml are evaluated per value after YAML parsing, so quoting never matters.

Assumes Rails 8.1: the generated file writes max_connections: (pool: before 8.1) and a three-tier production block for the Solid libraries (since 8.0).

open as a page

In a Rails payroll service, how do replica: true, connects_to and connected_to(role: :reading) send report queries to a read replica safely?

level: seniorimportance: must knowfreq 40%

basics

~20 s

Mark the replica entry replica: true, map roles in the abstract class with connects_to database: { writing: :primary, reading: :primary_replica }, and wrap report code in ActiveRecord::Base.connected_to(role: :reading). Inside, queries use the replica pool and any write raises ActiveRecord::ReadOnlyError.

open as a page

In Rails, when DATABASE_URL is set and config/database.yml also defines that environment, which values win and how are they merged?

level: middleimportance: should knowfreq 40%

basics

~20 s

Rails merges DATABASE_URL on top of the current environment's primary entry: the URL's adapter, host, port, credentials and database replace the YAML values, YAML keys the URL leaves out (such as max_connections) survive, and query parameters become extra keys.

open as a page

In Rails 8.1, what do max_connections and checkout_timeout in database.yml control, and when does ActiveRecord::ConnectionTimeoutError appear?

level: middleimportance: should knowfreq 42%

basics

~20 s

max_connections caps how many connections one process's pool may open (default 5), and checkout_timeout is how many seconds a thread waits for a free one (default 5). When every connection is busy past that wait, Active Record raises ActiveRecord::ConnectionTimeoutError.

open as a page

With Rails' automatic role switching (config.active_record.database_selector = { delay: 2.seconds }), how does each request end up on the primary or the replica?

level: seniorimportance: should knowfreq 30%

basics

~20 s

The DatabaseSelector middleware treats GET and HEAD as reads. Other verbs write to the primary and stamp a last-write time in the session; a read uses the replica unless that session wrote within the delay, then the primary, with writes blocked.

open as a page

In Rails, how do connects_to shards: and connected_to(shard:) route an abstract class's models to horizontal shards, and what does the ShardSelector middleware add?

level: seniorimportance: nice to knowfreq 18%

basics

~20 s

Each shard gets its own database.yml entries, and an abstract class maps them with connects_to shards: { shard_one: { writing:, reading: }, ... }. Code picks one with connected_to(role:, shard:) { }, and ShardSelector does it per request from config.active_record.shard_resolver, locking the choice by default.

open as a page