View Source Provider (provider v0.2.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:

  • load! - validates that all parameters are correctly provided and stores them in the cache
  • db_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 (see type/0). Defaults to :string.
  • :default - Default value used if the param is not provided. Defaults to nil (no default).
  • :dev - Default value in :dev and :test mix env. Defaults to nil (no default).
  • :test - Default value in :test mix env. Defaults to nil (no default).

Default options are considered in the following order:

  1. :test (if mix env is :test)
  2. :dev (if mix env is either :dev or :test)
  3. :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.

Types

@type data() :: %{required(param_name()) => value()}
@type param_name() :: atom()
@type param_spec() :: %{type: type(), default: value()}
@type params() :: %{required(param_name()) => param_spec()}
@type source() :: module()
@type type() :: :string | :integer | :float | :boolean
@type value() :: String.t() | number() | boolean() | nil

Functions

Link to this function

fetch_all(source, params)

View Source
@spec fetch_all(source(), params()) :: {:ok, data()} | {:error, [String.t()]}

Retrieves all params according to the given specification.