AppConfig

Simple Ruby framework-agnostic application configuration.

View project onGitHub

Usage

Usage is simple. Just pass either a hash of options, or a block, to AppConfig.setup!.

In it's simplest form, you can use it like so:

AppConfig.setup!(admin_email: 'admin@example.com')
# ..or..
AppConfig.setup! do |config|
  config.admin_email = 'admin@example.com'
end

AppConfig.admin_email  # => 'admin@example.com'

You may also specify the storage method along with options specific to that storage method. Check the wiki for more usage examples.

YAML

Given this YAML file:

---
admin_email: 'admin@example.com'
api_name:    'Supr Webz 2.0'
api_key:     'SUPERAWESOMESERVICE'

Use it like so:

AppConfig.setup!(yaml: '/path/to/app_config.yml')

# Later on...
AppConfig.admin_email  # => 'admin@example.com'
AppConfig.api_name     # => 'Supr Webz 2.0'
AppConfig.api_key      # => 'SUPERAWESOMESERVICE'

Mongo

You can pass a :mongo options hash to AppConfig.setup! which should contain configuration values for a Mongo database. Check the AppConfig::Storage::Mongo::DEFAULTS constant for the default Mongo connection options.

# These are the defaults.
mongo_opts = {
  host:       'localhost',
  database:   'app_config',
  collection: 'app_config'
}

AppConfig.setup!(mongo: mongo_opts)

AppConfig.admin_email  # => 'admin@example.com'

# Override an existing value and save to the database:
AppConfig.admin_email = 'other_admin@example.com'
AppConfig.save!

The values are read/saved (by default) to the app_config database and app_config collection. These defaults can be overridden, however, which might lend well to versioned configurations; collection names such as app_config_v1, app_config_v2, etc.

AppConfig.setup!(mongo: { collection: 'app_config_v2' })

PostgreSQL

Using PostgreSQL is similar to a Mongo setup. The only current requirement is that the table have a primary key named id. All other columns are used as configuration keys.

Note: The database and schema must exist prior to calling AppConfig.setup!.

Given this schema:

CREATE TABLE app_config (
  id bigserial NOT NULL PRIMARY KEY,
  admin_email character varying(255) DEFAULT 'admin@example.com'::character varying,
  api_key character varying(255) DEFAULT 'SOME_API_KEY'::character varying
);

Setup AppConfig:

# These are the defaults.
postgres_opts = {
  host:     'localhost',
  port:     5432,
  dbname:   'app_config',
  table:    'app_config',

  # If these are nil (or omitted), the PostgreSQL defaults will be used.
  user:     nil,
  password: nil,
}

AppConfig.setup!(postgres: postgres_opts)

AppConfig.admin_email  # => 'admin@example.com'

# Override an existing value and save to the database:
AppConfig.admin_email = 'another_admin@example.com'
AppConfig.save!

Using Storage Defaults

All storage options accept true as a value, which uses the default options for that storage.

For example, to use the Mongo defaults:

AppConfig.setup!(mongo: true)

Storage Defaults

Deprecation Note

Version 2.x is not backwards compatible with the 1.x branch.

See the wiki for current usage instructions.