Dotenvy behaviour (Dotenvy v0.3.0) View Source

Dotenvy is an Elixir implementation of the original dotenv Ruby gem.

It is designed to help the development of applications following the principles of the 12-factor app and its recommendation to store configuration in the environment.

Unlike other configuration helpers, Dotenvy enforces no convention for the naming of your files: .env is a common choice, you may name your configuration files whatever you wish.

See the strategies for examples of various use cases.

Link to this section Summary

Functions

Reads the given system environment variable and converts its value to the given type.

Reads a system environment variable and converts its output or returns a default value. Use of env!/2 is usually recommended over env!/3 because it creates a stronger contract with the environment (i.e. your app literally will not start if required env variables are missing) but there are times where supplying default values is desirable, and the env!/3 function is appropriate for those situations.

Like Bash's source command, this loads the given file(s) and sets the corresponding system environment variables using a side effect function (&System.put_env/1 by default).

As source/2, but returns map on success or raises on error.

Callbacks

A parser implementation should receive the contents read from a file, a map of vars (with string keys, as would come from System.get_env/0), and a keyword list of opts.

Link to this section Functions

Link to this function

env(variable, type \\ :string, default \\ nil)

View Source
This function is deprecated. Use `Dotenvy.env!/3` instead.

Specs

env(variable :: binary(), type :: atom(), default :: any()) ::
  any() | no_return()
Link to this function

env!(variable, type \\ :string)

View Source

Specs

env!(variable :: binary(), type :: atom()) :: any() | no_return()

Reads the given system environment variable and converts its value to the given type.

Internally, this behaves like System.fetch_env!/1: it will raise if a variable is not set or if empty values are encounted when non-empty values are required.

The conversion is delegated to Dotenvy.Transformer.to!/2 -- see its documentation for a list of supported types.

Examples

iex> env!("PORT", :integer)
5432
iex> env!("ENABLED", :boolean)
true
Link to this function

env!(variable, type, default)

View Source (since 0.3.0)

Specs

env!(variable :: binary(), type :: atom(), default :: any()) ::
  any() | no_return()

Reads a system environment variable and converts its output or returns a default value. Use of env!/2 is usually recommended over env!/3 because it creates a stronger contract with the environment (i.e. your app literally will not start if required env variables are missing) but there are times where supplying default values is desirable, and the env!/3 function is appropriate for those situations.

If the given system environment variable is set, its value is converted to the given type. The provided default value is only used when the system environment variable is not set; the default value is returned as-is, without conversion. This allows greater control of the output.

Although this relies on System.fetch_env/1, it may still raise an error if an unsupported type is provided or if non-empty values are required because the conversion is delegated to Dotenvy.Transformer.to!/2 -- see its documentation for a list of supported types.

Examples

iex> env!("PORT", :integer, 5432)
5433
iex> env!("NOT_SET", :boolean, %{not: "converted"})
%{not: "converted"}
iex> System.put_env("HOST", "")
iex> env!("HOST", :string!, "localhost")
** (Dotenvy.Transformer.Error) non-empty value required
Link to this function

source(files, opts \\ [])

View Source

Specs

source(files :: binary() | [binary()], opts :: keyword()) ::
  {:ok, %{optional(String.t()) => String.t()}} | {:error, any()}

Like Bash's source command, this loads the given file(s) and sets the corresponding system environment variables using a side effect function (&System.put_env/1 by default).

Files are processed in the order they are given. Values parsed from one file may override values parsed from previous files: the last file parsed has final say. The :overwrite? option determines how the parsed values will be merged with the existing system values.

Options

  • :overwrite? boolean indicating whether or not values parsed from provided .env files should overwrite existing system environment variables. It is recommended to keep this false: setting it to true would prevent you from setting variables on the command line, e.g. LOG_LEVEL=debug iex -S mix Default: false

  • :parser module that implements Dotenvy.parse/3 callback. Default: Dotenvy.Parser

  • :require_files specifies which of the given files (if any) must be present. When true, all the listed files must exist. When false, none of the listed files must exist. When some of the files are required and some are optional, provide a list specifying which files are required. If a file listed here is not included in the function's files argument, it is ignored. Default: false

  • :side_effect an arity 1 function called after the successful parsing of each of the given files. The default is &System.put_env/1, which will have the effect of setting system environment variables based on the results of the file parsing.

  • :vars a map with string keys representing the starting pool of variables. Default: output of System.get_env/0.

Examples

iex> Dotenvy.source(".env")
{:ok, %{
  "PWD" => "/users/home",
  "DATABASE_URL" => "postgres://postgres:postgres@localhost/myapp",
  # ...etc...
  }
}

# If you only want to return the parsed contents of the listed files
# ignoring system environment variables altogether
iex> Dotenvy.source(["file1", "file2"], side_effect: false, vars: %{})
Link to this function

source!(files, opts \\ [])

View Source

Specs

source!(files :: binary() | [binary()], opts :: keyword()) ::
  %{optional(String.t()) => String.t()} | no_return()

As source/2, but returns map on success or raises on error.

Link to this section Callbacks

Link to this callback

parse(contents, vars, opts)

View Source

Specs

parse(contents :: binary(), vars :: map(), opts :: keyword()) ::
  {:ok, map()} | {:error, any()}

A parser implementation should receive the contents read from a file, a map of vars (with string keys, as would come from System.get_env/0), and a keyword list of opts.

This callback is provided to help facilitate testing. See Dotenvy.Parser for the default implementation.