Mix.Config

Module for defining, reading and merging app configurations.

Most commonly, this module is used to define your own configuration:

use Mix.Config

config :plug,
  key1: "value1",
  key2: "value2"

import_config "#{Mix.env}.exs"

All config/* macros, including import_config/1, are used to help define such configuration files.

Furthermore, this module provides functions like read!/1, merge/2 and friends which help manipulate configurations in general.

Configuration set using Mix.Config will set the application environment, so that Application.get_env/3 and other Application functions can be used at run or compile time to retrieve or change the configuration.

For example, the :key1 value from the application :plug (see example above) can be retrieved with:

"value1" = Application.fetch_env!(:plug, :key1)

Summary

Functions

config(app, opts)

Configures the given application

config(app, key, opts)

Configures the given key for the given application

eval!(file, imported_paths \\ [])

Evaluates the given configuration file

import_config(path_or_wildcard)

Imports configuration from the given file or files

merge(config1, config2)

Merges two configurations

persist(config)

Persists the given configuration by modifying the configured applications environment

Functions

config(app, opts)

Configures the given application.

Keyword lists are always deep merged.

Examples

The given opts are merged into the existing configuration for the given app. Conflicting keys are overridden by the ones specified in opts. For example, the declaration below:

config :lager,
  log_level: :warn,
  mode: :truncate

config :lager,
  log_level: :info,
  threshold: 1024

Will have a final configuration of:

[log_level: :info, mode: :truncate, threshold: 1024]

This final configuration can be retrieved at run or compile time:

Application.get_all_env(:lager)

config(app, key, opts)

Configures the given key for the given application.

Keyword lists are always deep merged.

Examples

The given opts are merged into the existing values for key in the given app. Conflicting keys are overridden by the ones specified in opts. For example, given the two configurations below:

config :ecto, Repo,
  log_level: :warn,
  adapter: Ecto.Adapters.Postgres

config :ecto, Repo,
  log_level: :info,
  pool_size: 10

the final value of the configuration for the Repo key in the :ecto application will be:

[log_level: :info, pool_size: 10, adapter: Ecto.Adapters.Postgres]

This final value can be retrieved at runtime or compile time with:

Application.get_env(:ecto, Repo)

eval!(file, imported_paths \\ [])

Evaluates the given configuration file.

It accepts a list of imported_paths that should raise if attempted to be imported again (to avoid recursive imports).

It returns a tuple with the configuration and the imported paths.

import_config(path_or_wildcard) (macro)

Imports configuration from the given file or files.

If path_or_wildcard is a wildcard, then all the files matching that wildcard will be imported; if no file matches the wildcard, no errors are raised. If path_or_wildcard is not a wildcard but a path to a single file, then that file is imported; in case the file doesn’t exist, an error is raised.

If path/wildcard is a relative path/wildcard, it will be expanded relatively to the directory the current configuration file is in.

Examples

This is often used to emulate configuration across environments:

import_config "#{Mix.env}.exs"

Or to import files from children in umbrella projects:

import_config "../apps/*/config/config.exs"

merge(config1, config2)

Merges two configurations.

The configuration of each application is merged together with the values in the second one having higher preference than the first in case of conflicts.

Examples

iex> Mix.Config.merge([app: [k: :v1]], [app: [k: :v2]])
[app: [k: :v2]]

iex> Mix.Config.merge([app1: []], [app2: []])
[app1: [], app2: []]

persist(config)

Persists the given configuration by modifying the configured applications environment.

config should be a list of {app, app_config} tuples or a %{app => app_config} map where app are the applications to be configured and app_config are the configuration (as key-value pairs) for each of those applications.

Returns the configured applications.

Examples

Mix.Config.persist(logger: [level: :error], my_app: [my_config: 1])
#=> [:logger, :my_app]