Skip to content

Latest commit

 

History

History
247 lines (170 loc) · 6.25 KB

README.md

File metadata and controls

247 lines (170 loc) · 6.25 KB
Raw

AppConfig Build Status Donate

An easy to use, customizable library to easily store and retrieve application configuration; basically anything in 'key/value' pairs.

AppConfig requires at least Ruby 1.9.

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: '[email protected]')
# ..or..
AppConfig.setup! do |config|
  config.admin_email = '[email protected]'
end

AppConfig.admin_email  # => '[email protected]'

AppConfig also supports many different 'storage methods', such as YAML and MongoDB, allowing you to tailor AppConfig to many different use cases. For example, storing your configuration in the same database as your development/production environment.

YAML

Given this YAML file:

---
admin_email: '[email protected]'
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  # => '[email protected]'
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.

The 'mongo' gem is required in order to use Mongo storage.

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

AppConfig.setup!(mongo: mongo_opts)

AppConfig.admin_email  # => '[email protected]'

# Override an existing value and save to the database:
AppConfig.admin_email = '[email protected]'
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.

The 'pg' gem is required in order to use Postgres storage.

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 '[email protected]'::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  # => '[email protected]'

# Override an existing value and save to the database:
AppConfig.admin_email = '[email protected]'
AppConfig.save!

MySQL

Using MySQL is similar to Postgres, including the required primary key named id. All other columns are used as configuration keys.

The 'mysql2' gem is required in order to use MySQL storage.

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

Given this schema:

CREATE TABLE app_config (
 id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
 admin_email VARCHAR(255) DEFAULT "[email protected]",
 api_key VARCHAR(255) DEFAULT "SOME_API_KEY",
 true_option BOOLEAN DEFAULT true,
 false_option BOOLEAN DEFAULT false
);

Setup AppConfig:

# These are the defaults:
mysql_opts = {
  host: 'localhost',
  port: 3306,
  database: 'app_config',
  table: 'app_config',
  username: nil,
  password: nil,
}

AppConfig.setup!(mysql: mysql_opts)

AppConfig.admin_email  # => '[email protected]'

# Update an existing value and save changes:
AppConfig.admin_email = '[email protected]'
AppConfig.save!

SQLite

SQLite storage works the same as the other SQL storage methods, including the mandatory primary key id column.

The 'sqlite3' gem is required in order to use SQLite storage.

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

# These are the defaults:
sqlite_opts = {
  database: File.join(Dir.home, '.app_config.sqlite3'),
  table: 'app_config',
}

AppConfig.setup!(sqlite: sqlite_opts)

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

Environment Mode

The YAML storage method provides an :env option where you can organize the config like Rails database.yml:

# Rails.root/config/app_config.yml
development:
  title: 'Development Mode'

production:
  title: 'Production Mode'

Pass a string or symbol to the :env option.

# Rails.root/config/initializers/app_config.rb
AppConfig.setup!({
  yaml: "#{Rails.root}/config/app_config.yml",
  env: Rails.env
})

# Uses the given environment section of the config.
AppConfig.title  # => 'Production Mode'

Deprecation Note

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

See the wiki for current usage instructions.