View Source Provider (provider v0.1.0)
Retrieval of configuration settings from external sources, such as OS env vars.
This module is an alternative to app env for retrieval of configuration settings. It allows you to properly consolidate system settings, define per-env defaults, add strong typing, and compile time guarantees.
Basic example
defmodule MySystem.Config do
use Provider,
source: Provider.SystemEnv,
params: [
{:db_host, dev: "localhost"},
{:db_name, dev: "my_db_dev", test: "my_db_test"},
{:db_pool_size, type: :integer, default: 10},
# ...
]
end
This will generate the following functions in the module:
fetch_all
- retrieves values of all parametersvalidate!
- validates that all parameters are correctly provideddb_host
,db_name
,db_pool_size
, ... - getter of each declared parameter
Describing params
Each param is described in the shape of {param_name, param_spec}
, where param_name
is an
atom, and param_spec
is a keyword list. Providing only param_name
(without a tuple), is the
same as {param_name, []}
.
The following keys can be used in the param_spec
:
:type
- Param type (seetype/0
). Defaults to:string
.:default
- Default value used if the param is not provided. Defaults tonil
(no default).:dev
- Default value in:dev
and:test
mix env. Defaults tonil
(no default).:test
- Default value in:test
mix env. Defaults tonil
(no default).
Default options are considered in the following order:
:test
(if mix env is:test
):dev
(if mix env is either:dev
or:test
):default
For example, if :test
and :default
options are given, the :test
value will be used as a
default in :test
env, while :default
will be used in all other envs.
When you invoke the generated functions, values will be retrieved from the external storage (e.g. OS env). If some value is not available, a default value will be used (if provided). The values are then casted according to the parameter type.
Each default can be a constant, but it can also be an expression, which is evaluated at runtime. For example:
defmodule MySystem.Config do
use Provider,
source: Provider.SystemEnv,
params: [
# db_name/0 will be invoked when you try to retrieve this parameter (or all parameters)
{:db_name, dev: db_name()},
# ...
]
defp db_name(), do: #...
end
It's worth noting that Provider
performs compile-time purging of needless defaults. When you
compile the code in :prod
, :dev
and :test
defaults will not be included in the binaries.
Consequently, any private function invoked only in dev/test will also not be invoked, and you'll
get a compiler warning when compiling the code in prod. To eliminate such warnings, you can
conditionally define the function only in required mix env, by moving the function definition
under an if Mix.env() ==
conditional.
Generating template
The config module will contain the template/0
function which generates the configuration
template. To print the template to stdout, you can invoke:
MIX_ENV=prod mix compile
MIX_ENV=prod mix run --no-start -e 'IO.puts(MySystem.Config.template())'
Lower level API
The basic retrieval functionality is available via functions of this module, such as
fetch_all/2
, or fetch_one/2
. These functions are a lower level plumbing API which is less
convenient to use, but more flexible. Most of the time the use
-based interface will serve you
better, but if you have more specific needs which are not covered by that, you can reach for
these functions.
Summary
Functions
Retrieves all params according to the given specification.
Retrieves a single parameter.
Retrieves a single param, raising if the value is not available.
Types
@type data() :: %{required(param_name()) => value()}
@type param_name() :: atom()
@type params() :: %{required(param_name()) => param_spec()}
@type source() :: module()
@type type() :: :string | :integer | :float | :boolean
Functions
Retrieves all params according to the given specification.
@spec fetch_one(source(), param_name(), param_spec()) :: {:ok, value()} | {:error, [String.t()]}
Retrieves a single parameter.
@spec fetch_one!(source(), param_name(), param_spec()) :: value()
Retrieves a single param, raising if the value is not available.