Flexible configuration for Ruby applications
Latest commit d5a3f97 Oct 29, 2016 @jnicklas jnicklas committed on GitHub Merge pull request #15 from soumyaray/readme-update-configuration
README.md: add Sinatra example
Failed to load latest commit information.
lib Fix non jvm compliant character Jan 7, 2016
spec Can cast values Oct 14, 2015
.gitignore Add stuff Jan 7, 2013
.rspec Add stuff Jan 7, 2013
LICENSE.txt Formalities Jan 7, 2013
README.md README.md: add Sinatra example Oct 28, 2016
Rakefile Add a default rake task for running the spec suite Apr 9, 2014
econfig.gemspec Requires Ruby ~> 2.0 May 26, 2014



Econfig is a gem which allows you to easily configure your Ruby applications in a multitude of ways.


Add this to your Gemfile:

gem "econfig"

If you're using Rails, you'll want to require the Rails extension:

gem "econfig", require: "econfig/rails"

Accessing config options

Extend your main application module with the Econfig shortcut.

In Rails, you'll want to add this in config/application.rb:

module MyApp
  extend Econfig::Shortcut

  class Application < Rails::Application

In a modular Sinatra application, extend your controller class and copy its settings to Econfig in app.rb:

require 'sinatra'
require 'econfig'

class MyApp < Sinatra::Base
  extend Econfig::Shortcut

  Econfig.env = settings.environment.to_s
  Econfig.root = settings.root


In either case, you can now you can access configuration like this:


If the key you accessed is not configured, Econfig will raise an error. To access optional configuration, which can be nil, use brackets:


Sometimes you might want to bypass the strictness requirement in econfig, for example if you're running the application as part of a build process. In that case you can set the environment variable ECONFIG_PERMISSIVE, and econfig will not raise errors on missing keys, instead returning nil.

Configuring options.

You can specify configuration through:

  1. ENV variables
  2. Redis
  3. Relational database
  4. YAML files
  5. OSX Keychain

This allows you to set up Econfig on most kinds of hosting solutions (EngineYard, Heroku, etc) without any additional effort, and to switch between them easily.

ENV variables

Just set an environment variable whose name is the name of the option being accessed uppercased.

For example:

AWS_ACCESS_KEY_ID=xyz rails server

You can now read it like this:

MyApp.config.aws_access_key_id # => "xyz"

This is especially convenient for Heroku.


Add a yaml file to config/app.yml. This should have a similar layout to config/database.yml:

  aws_access_key_id: "xyz"
  aws_secret_access_key: "xyz"
  aws_access_key_id: "xyz"
  aws_secret_access_key: "xyz"

Econfig also reads configuration from config/secret.yml which is the new standard for secret configuration parameters in Rails 4.1.

Relational database

This needs to be explicitly enabled. In config/application.rb add this code:

require "econfig/active_record"
Econfig.backends.insert_after :env, :db, Econfig::ActiveRecord.new

You probably want environment variables to take precendence over configuration from ActiveRecord, hence the insert_after. If you'd rather have ActiveRecord configuration take precendence you can use this instead:

require "econfig/active_record"
Econfig.backends.unshift :db, Econfig::ActiveRecord.new

You will also need to create a migration to create the necessary database tables:

rails generate econfig:migration
rake db:migrate


This needs to be explicitly enabled. In config/application.rb add this code:

require "econfig/redis"
redis = Redis.new(:host => "myredis.com")
Econfig.backends.insert_after :env, :redis, Econfig::Redis.new(redis)

If you wish to namespace your keys in Redis, you can use redis namespace.

OSX Keychain

For the OSX keychain backend, see econfig-keychain.

Setting values

You can set options by simply assigning them:

MyApp.config[:aws_access_key_id] = "xyz"

This will set the value in the default write backend, which by default is :memory. This means that by default, configuration which is set like this is not persisted in any way.

If you always want to assign values to a different backend, for example the database backend, you can set the default write backend like this:

Econfig.default_write_backend = :db

You can also explicitly supply the backend when setting a configuration value:

MyApp.config[:db, :aws_access_key_id] = "xyz"


MIT, see separate LICENSE.txt file