Understanding config/database.yml in Ruby on Rails

June 11, 2025

The config/database.yml file is a core part of any Ruby on Rails application. It defines how Rails connects to the database in various environments (development, test, production), and it’s often the first touchpoint when configuring an application’s data layer. Let’s explore how this configuration file works, from basic setups to more advanced, multi-database configurations.

Basic Configuration

A standard database.yml includes three environments:

default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  username: <%= ENV["DB_USERNAME"] %>
  password: <%= ENV["DB_PASSWORD"] %>
  host: <%= ENV["DB_HOST"] || "localhost" %>

development:
  <<: *default
  database: myapp_development

test:
  <<: *default
  database: myapp_test

production:
  <<: *default
  database: myapp_production
  username: <%= ENV["MYAPP_DB_USERNAME"] %>
  password: <%= ENV["MYAPP_DB_PASSWORD"] %>
  host: <%= ENV["MYAPP_DB_HOST"] %> 

This structure promotes reusability by defining shared settings under default, which are then referenced in each environment using YAML anchors (<<: *default). Credentials and environment-specific values should always be handled via environment variables to maintain security and portability.

Complex Configuration

Rails supports advanced configurations when the application demands more control or performance tuning. Here are some examples:

Statement Timeouts and Custom Settings

production:
  <<: *default
  database: myapp_production
  variables:
    statement_timeout: 5000 

PostgreSQL Schema Search Path

development:
  <<: *default
  database: myapp_development
  schema_search_path: 'tenant1,public' 

Custom YAML Logic with ERB

test:
  <<: *default
  database: <%= "myapp_#{Rails.env}" %> 

YAML’s flexibility, combined with ERB, allows developers to keep the configuration DRY and context-aware.

Multiple Databases

With the introduction of multiple database support in Rails 6+, it’s now possible to connect to and manage more than one database within the same application.

Example Configuration

development:
  primary:
    <<: *default
    database: myapp_development

  reporting:
    <<: *default
    database: myapp_reporting 

Connecting in Models

class ReportingRecord < ApplicationRecord
  connects_to database: { writing: :reporting }
end 

This approach is particularly useful for separating concerns—such as keeping analytics or reporting workloads separate from transactional data.

Additionally, Rails supports read/write splitting with replicas. This can be configured like so:

Read/Write Splitting Example

production:
  primary:
    <<: *default
    database: myapp_production

  primary_replica:
    <<: *default
    database: myapp_production_replica
    replica: true 

Using a Replica in Code

ActiveRecord::Base.connected_to(role: :reading) do
  User.find(1) # Read from replica
end 

This level of flexibility makes database.yml a powerful tool for scaling and structuring Rails applications in complex environments.

Integrating Non-Relational Databases

While config/database.yml is tailored for ActiveRecord and relational databases such as PostgreSQL and MySQL, Rails applications can still integrate with non-relational (NoSQL) databases through separate configuration methods.

MongoDB with Mongoid

To use MongoDB, the mongoid gem provides a seamless integration that doesn’t rely on database.yml. Instead, you generate a mongoid.yml file:

rails g mongoid:config

A basic mongoid.yml file will handle connections similarly but with MongoDB semantics. Models will include Mongoid::Document instead of inheriting from ApplicationRecord:

class Product
  include Mongoid::Document
  field :name, type: String
  field :price, type: Float
end

Redis and Other NoSQL Solutions

Other NoSQL options like Redis are usually integrated using client libraries, configured in initializers or environment variables. These are commonly used for caching, queues (e.g., Sidekiq), or temporary data storage rather than primary persistence.

redis = Redis.new(url: ENV['REDIS_URL'])
redis.set("key", "value")
puts redis.get("key")

Although these technologies are not managed through database.yml, they can play vital roles in the overall architecture of a Rails application.

By understanding the capabilities of config/database.yml, Rails developers can make smarter decisions about data architecture, improve performance, and prepare their applications for scalability. Whether you’re building a simple blog or a multi-service system, this configuration file remains central to your Rails application’s stability and growth.