dotenv

README

dotenv

The dotenv package manages the configuration of a Go application through environment variables, similar to the Ruby dotenv library. It provides helper functions to pull typed values from environment variables, configure default values, and support environmental overrides during development through a .env file.

Getting values

The dotenv package supports most of the basic Go data types. Use one of the Get calls to pull in the value from the system environment variables (os.LookupEnv), or use the registered default value (see below).

Here's some samples:

maxConns := dotenv.GetInt("MAX_CONNS")
timeout := dotenv.GetDuration("HTTP_TIMEOUT")
hostname := dotenv.GetString("HOSTNAME")
useTLS := dotenv.GetBool("ENABLE_TLS")

Note: recommend using constants for environment variable names!

See the Godocs for all available Get functions.

These functions are safe to call in multithreaded code, i.e. goroutines.

Default values

It's frequently useful to have default values for application settings. For example, most people can just use the default maximun number of database connections, or HTTP timeout values. The dotenv package allows you to register these defaults, and if the environment variable hasn't been set, a call to a Get function will return these defaults.

Here's some example registration calls:

func init() {
    dotenv.Register("VERBOSITY", -1, "Set the debug logging verbosity")
    dotenv.Register("DB_DRIVER", "postgres", "Name of the database driver")
    dotenv.Register("DB_URI", "postgres://postgres@localhost/mydb?sslmode=disable", "Database connection URI")
}

Provide the environment variable to look for, it's default value, and a description of this setting.

You can also use this to display help information to users. In your startup command, if a required setting is missing or incorrect, or maybe the user starts things with a --help CLI parameter, you may call the Help() function to display the registered settings, their default values, types, and description.

The .env file

The dotenv package also supports a .env file. This file can exist in either the project directory (or wherever you start the application), or the user's $HOME directory. The dotenv pacakge looks for these files and overrides any environment variables or defaults when they exist in one of these files.

The .env file just looks like any .bashrc or similar environment configuration file:

# Logging
VERBOSITY=3

# Database settings
DB_URI=postgres://postgres@localhost/mydb?sslmode=disable
DB_MIN=2
DB_MAX=6

It's best to add .env to the .gitignore file in your project, so a local developer's environment variables--particularly usernames and passwords--don't accidentally get pushed into source control.

Note: there's no way for dotenv to distinguish between an environment variable that's been set in a .bashrc or through an export in your terminal session, and one that's been set on the command line, e.g. VERBOSITY=2 ./myapp. Thus, any setting in the .env file will override environment settings. If you want to customize the setting from the command line, make sure to comment it out or remove it from the .env file.

Documentation

Overview

Package dotenv manages the configuration of the application through a .env file and environment variables.

The developer creates a .env file locally (and doesn't commit it to source control) with information about database connections, logging verbosity, and other settings he or she would like to override during development, and these settings will be loaded into environment variables when the application starts.

In production, the container or virtual machine OS environment variables may be configured per deployment to override any settings relevant to that specific environment. This leaves any containers free of configuration files and easily configured externally, as most container solutions provide configuration through environment variables.

Index

• Constants
• Variables
• func Default(key string) (descriptor, bool)
• func GetBool(key string) bool
• func GetDuration(key string) time.Duration
• func GetFloat64(key string) float64
• func GetInt(key string) int
• func GetInt64(key string) int64
• func GetString(key string) string
• func GetStringSlice(key string) []string
• func Help()
• func Load() error
• func Register(key string, defaultValue interface{}, description string)

Constants

const (
	StringType = iota
	StringSliceType
	IntType
	Float64Type
	BoolType
	DurationType
)

Variables

var (
	// ErrBadUserFile returned when the .env file in the user's home directory is invalid.
	ErrBadUserFile = errors.New("unable to parse $HOME/.env file")

	// ErrBadLocalFile returned when the local .env file (in the same directory as the app) is
	// invalid.
	ErrBadLocalFile = errors.New("unable to parse .env file")
)

Functions

func Default

func Default(key string) (descriptor, bool)

Default returns the default setting set by the Register call. Thread-safe.

func GetBool

func GetBool(key string) bool

GetBool returns the environment variable as a boolean value. If the environment variable doesn't exist, returns the default value if present, otherwise returns false.

func GetDuration

func GetDuration(key string) time.Duration

GetDuration returns the environment variable as an time.Duration value. If the environment variable doesn't exist, returns the default value if present, otherwise returns 0.

func GetFloat64

func GetFloat64(key string) float64

GetFloat64 returns the environment variable as an float64 value. If the environment variable doesn't exist, returns the default value if present, otherwise returns 0.

func GetInt

func GetInt(key string) int

GetInt returns the environment variable as an integer value. If the environment variable doesn't exist or is not an integer, returns the default value if present, otherwise returns 0.

func GetInt64

func GetInt64(key string) int64

GetInt64 returns the environment variable as an int64 value. If the environment variable doesn't exist or is not an int64, returns the default value if present, otherwise returns 0.

func GetString

func GetString(key string) string

GetString returns the environment variable as a string value. If the environment variable doesn't exist, returns the default value if present, otherwise a blank string.

func GetStringSlice

func GetStringSlice(key string) []string

GetStringSlice returns the environment variable as a string slice value. If the environment variable doesn't exist, returns the default value if present, otherwise a nil value. Expects a environment variable value to be a comma-separated list of values.

func Help

func Help()

Help displays details about registered default variables. May be called via a `--help` command-line parameter, or if some setting is invalid. Produces colorized output to stdout.

func Load

func Load() error

Load the environment settings from:

* the .env file in the startup directory * the .env file in the user's home directory

like they are environment variables. Any existing environment variables are overwritten.

func Register

func Register(key string, defaultValue interface{}, description string)

Register registers a default value for an environment variable. When getting the value for that environment variable, if a value isn't set, the default is returned.