app_config
app_config copied to clipboard
Simple Ruby framework-agnostic application configuration.
AppConfig
![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)
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
- Mongo
- MySQL
- Postgres
- SQLite
- YAML
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.