Configuring Rails Applications ↑

This guide covers the configuration and initialization features available to Rails applications.

After reading this guide, you will know:

Locations for Initialization Code ↑

Rails offers four standard spots to place initialization code:

Running Code Before Rails ↑

In the rare event that your application needs to run some code before Rails itself is loaded, put it above the call to require 'rails/all' in config/application.rb.

Configuring Rails Components ↑

In general, the work of configuring Rails means configuring the components of Rails, as well as configuring Rails itself. The configuration file config/application.rb and environment-specific configuration files (such as config/environments/production.rb) allow you to specify the various settings that you want to pass down to all of the components.

For example, the default config/application.rb file includes this setting:

config.filter_parameters += [:password]

This is a setting for Rails itself. If you want to pass settings to individual Rails components, you can do so via the same config object in config/application.rb:

config.active_record.schema_format = :ruby

Rails will use that particular setting to configure Active Record.

Rails General Configuration ↑

These configuration methods are to be called on a Rails::Railtie object, such as a subclass of Rails::Engine or Rails::Application.

Configuring Assets ↑

Configuring Generators ↑

Rails allows you to alter what generators are used with the config.generators method. This method takes a block:

config.generators do |g|
  g.orm :active_record
  g.test_framework :test_unit
end

The full set of methods that can be used in this block are as follows:

Configuring Middleware ↑

Every Rails application comes with a standard set of middleware which it uses in this order in the development environment:

Besides these usual middleware, you can add your own by using the config.middleware.use method:

config.middleware.use Magical::Unicorns

This will put the Magical::Unicorns middleware on the end of the stack. You can use insert_before if you wish to add a middleware before another.

config.middleware.insert_before ActionDispatch::Head, Magical::Unicorns

There's also insert_after which will insert a middleware after another:

config.middleware.insert_after ActionDispatch::Head, Magical::Unicorns

Middlewares can also be completely swapped out and replaced with others:

config.middleware.swap ActionController::Failsafe, Lifo::Failsafe

They can also be removed from the stack completely:

config.middleware.delete "Rack::MethodOverride"

Configuring i18n ↑

Configuring Active Record ↑

config.active_record includes a variety of configuration options:

The MySQL adapter adds one additional configuration option:

The schema dumper adds one additional configuration option:

Configuring Action Controller ↑

config.action_controller includes a number of configuration settings:

Configuring Action Dispatch ↑

Configuring Action View ↑

config.action_view includes a small number of configuration settings:

Configuring Action Mailer ↑

There are a number of settings available on config.action_mailer:

Configuring Active Support ↑

There are a few configuration options available in Active Support:

Configuring a Database ↑

Just about every Rails application will interact with a database. The database to use is specified in a configuration file called config/database.yml. If you open this file in a new Rails application, you'll see a default database configured to use SQLite3. The file contains sections for three different environments in which Rails can run by default:

TIP: You don't have to update the database configurations manually. If you look at the options of the application generator, you will see that one of the options is named --database. This option allows you to choose an adapter from a list of the most used relational databases. You can even run the generator repeatedly: cd .. && rails new blog --database=mysql. When you confirm the overwriting of the config/database.yml file, your application will be configured for MySQL instead of SQLite. Detailed examples of the common database connections are below.

Configuring an SQLite3 Database ↑

Rails comes with built-in support for SQLite3, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using an SQLite database when creating a new project, but you can always change it later.

Here's the section of the default configuration file (config/database.yml) with connection information for the development environment:

development:
  adapter: sqlite3
  database: db/development.sqlite3
  pool: 5
  timeout: 5000

NOTE: Rails uses an SQLite3 database for data storage by default because it is a zero configuration database that just works. Rails also supports MySQL and PostgreSQL “out of the box”, and has plugins for many database systems. If you are using a database in a production environment Rails most likely has an adapter for it.

Configuring a MySQL Database ↑

If you choose to use MySQL instead of the shipped SQLite3 database, your config/database.yml will look a little different. Here's the development section:

development:
  adapter: mysql2
  encoding: utf8
  database: blog_development
  pool: 5
  username: root
  password:
  socket: /tmp/mysql.sock

If your development computer's MySQL installation includes a root user with an empty password, this configuration should work for you. Otherwise, change the username and password in the development section as appropriate.

Configuring a PostgreSQL Database ↑

If you choose to use PostgreSQL, your config/database.yml will be customized to use PostgreSQL databases:

development:
  adapter: postgresql
  encoding: unicode
  database: blog_development
  pool: 5
  username: blog
  password:

Prepared Statements can be disabled thus:

production:
  adapter: postgresql
  prepared_statements: false

Configuring an SQLite3 Database for JRuby Platform ↑

If you choose to use SQLite3 and are using JRuby, your config/database.yml will look a little different. Here's the development section:

development:
  adapter: jdbcsqlite3
  database: db/development.sqlite3

Configuring a MySQL Database for JRuby Platform ↑

If you choose to use MySQL and are using JRuby, your config/database.yml will look a little different. Here's the development section:

development:
  adapter: jdbcmysql
  database: blog_development
  username: root
  password:

Configuring a PostgreSQL Database for JRuby Platform ↑

If you choose to use PostgreSQL and are using JRuby, your config/database.yml will look a little different. Here's the development section:

development:
  adapter: jdbcpostgresql
  encoding: unicode
  database: blog_development
  username: blog
  password:

Change the username and password in the development section as appropriate.

Creating Rails Environments ↑

By default Rails ships with three environments: “development”, “test”, and “production”. While these are sufficient for most use cases, there are circumstances when you want more environments.

Imagine you have a server which mirrors the production environment but is only used for testing. Such a server is commonly called a “staging server”. To define an environment called “staging” for this server just by create a file called config/environments/staging.rb. Please use the contents of any existing file in config/environments as a starting point and make the necessary changes from there.

That environment is no different than the default ones, start a server with rails server -e staging, a console with rails console staging, Rails.env.staging? works, etc.

Rails Environment Settings ↑

Some parts of Rails can also be configured externally by supplying environment variables. The following environment variables are recognized by various parts of Rails:

Using Initializer Files ↑

After loading the framework and any gems in your application, Rails turns to loading initializers. An initializer is any Ruby file stored under config/initializers in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and gems are loaded, such as options to configure settings for these parts.

NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the initializers folder on down.

TIP: If you have any ordering dependency in your initializers, you can control the load order through naming. Initializer files are loaded in alphabetical order by their path. For example, 01_critical.rb will be loaded before 02_normal.rb.

Initialization events ↑

Rails has 5 initialization events which can be hooked into (listed in the order that they are run):

To define an event for these hooks, use the block syntax within a Rails::Application, Rails::Railtie or Rails::Engine subclass:

module YourApp
  class Application < Rails::Application
    config.before_initialize do
      # initialization code goes here
    end
  end
end

Alternatively, you can also do it through the config method on the Rails.application object:

Rails.application.config.before_initialize do
  # initialization code goes here
end

WARNING: Some parts of your application, notably routing, are not yet set up at the point where the after_initialize block is called.

Rails::Railtie#initializer ↑

Rails has several initializers that run on startup that are all defined by using the initializer method from Rails::Railtie. Here's an example of the initialize_whiny_nils initializer from Active Support:

initializer "active_support.initialize_whiny_nils" do |app|
  require 'active_support/whiny_nil' if app.config.whiny_nils
end

The initializer method takes three arguments with the first being the name for the initializer and the second being an options hash (not shown here) and the third being a block. The :before key in the options hash can be specified to specify which initializer this new initializer must run before, and the :after key will specify which initializer to run this initializer after.

Initializers defined using the initializer method will be ran in the order they are defined in, with the exception of ones that use the :before or :after methods.

WARNING: You may put your initializer before or after any other initializer in the chain, as long as it is logical. Say you have 4 initializers called “one” through “four” (defined in that order) and you define “four” to go before “four” but after “three”, that just isn't logical and Rails will not be able to determine your initializer order.

The block argument of the initializer method is the instance of the application itself, and so we can access the configuration on it by using the config method as done in the example.

Because Rails::Application inherits from Rails::Railtie (indirectly), you can use the initializer method in config/application.rb to define initializers for the application.

Initializers ↑

Below is a comprehensive list of all the initializers found in Rails in the order that they are defined (and therefore run in, unless otherwise stated).

Database pooling ↑

Active Record database connections are managed by ActiveRecord::ConnectionAdapters::ConnectionPool which ensures that a connection pool synchronizes the amount of thread access to a limited number of database connections. This limit defaults to 5 and can be configured in database.yml.

development:
  adapter: sqlite3
  database: db/development.sqlite3
  pool: 5
  timeout: 5000

Since the connection pooling is handled inside of Active Record by default, all application servers (Thin, mongrel, Unicorn etc.) should behave the same. Initially, the database connection pool is empty and it will create additional connections as the demand for them increases, until it reaches the connection pool limit.

Any one request will check out a connection the first time it requires access to the database, after which it will check the connection back in, at the end of the request, meaning that the additional connection slot will be available again for the next request in the queue.

NOTE. If you have enabled Rails.threadsafe! mode then there could be a chance that several threads may be accessing multiple connections simultaneously. So depending on your current request load, you could very well have multiple threads contending for a limited amount of connections.