Envconfig populates struct field values based on environment variables or arbitrary lookup functions. It supports pre-setting mutations, which is useful for things like converting values to uppercase, trimming whitespace, or looking up secrets.
Note: Versions prior to v0.2 used a different import path. This README and examples are for v0.2+.
Define a struct with fields using the env
tag:
type MyConfig struct {
Port int `env:"PORT"`
Username string `env:"USERNAME"`
}
Set some environment variables:
export PORT=5555
export USERNAME=yoyo
Process it using envconfig:
package main
import (
"context"
"log"
"github.com/sethvargo/go-envconfig"
)
func main() {
ctx := context.Background()
var c MyConfig
if err := envconfig.Process(ctx, &c); err != nil {
log.Fatal(err)
}
// c.Port = 5555
// c.Username = "yoyo"
}
You can also use nested structs, just remember that any fields you want to process must be public:
type MyConfig struct {
Database *DatabaseConfig
}
type DatabaseConfig struct {
Port int `env:"PORT"`
Username string `env:"USERNAME"`
}
Use the env
struct tag to define configuration.
If overwrite is set, the value will be overwritten if there is an environment variable match regardless if the value is non-zero.
type MyStruct struct {
Port int `env:"PORT,overwrite"`
}
If a field is required, processing will error if the environment variable is unset.
type MyStruct struct {
Port int `env:"PORT,required"`
}
It is invalid to have a field as both required
and default
.
If an environment variable is not set, the field will be set to the default
value. Note that the environment variable must not be set (e.g. unset PORT
).
If the environment variable is the empty string, that counts as a "value" and
the default will not be used.
type MyStruct struct {
Port int `env:"PORT,default=5555"`
}
You can also set the default value to another field or value from the environment, for example:
type MyStruct struct {
DefaultPort int `env:"DEFAULT_PORT,default=5555"`
Port int `env:"OVERRIDE_PORT,default=$DEFAULT_PORT"`
}
The value for Port
will default to the value of DEFAULT_PORT
.
It is invalid to have a field as both required
and default
.
For shared, embedded structs, you can define a prefix to use when processing struct values for that embed.
type SharedConfig struct {
Port int `env:"PORT,default=5555"`
}
type Server1 struct {
// This processes Port from $FOO_PORT.
*SharedConfig `env:",prefix=FOO_"`
}
type Server2 struct {
// This processes Port from $BAR_PORT.
*SharedConfig `env:",prefix=BAR_"`
}
It is invalid to specify a prefix on non-struct fields.
In the environment, time.Duration
values are specified as a parsable Go
duration:
type MyStruct struct {
MyVar time.Duration `env:"MYVAR"`
}
export MYVAR="10m" # 10 * time.Minute
Types that implement TextUnmarshaler
or BinaryUnmarshaler
are processed as such.
Types that implement json.Unmarshaler
are processed as such.
Types that implement gob.Decoder
are processed as such.
Slices are specified as comma-separated values:
type MyStruct struct {
MyVar []string `env:"MYVAR"`
}
export MYVAR="a,b,c,d" # []string{"a", "b", "c", "d"}
Note that byte slices are special cased and interpreted as strings from the environment.
Maps are specified as comma-separated key:value pairs:
type MyStruct struct {
MyVar map[string]string `env:"MYVAR"`
}
export MYVAR="a:b,c:d" # map[string]string{"a":"b", "c":"d"}
Envconfig walks the entire struct, including nested structs, so deeply-nested fields are also supported.
If a nested struct is a pointer type, it will automatically be instantianted to
the non-nil value. To disable this behavior, use the tag noinit
. E.g.
type ParentCfg struct {
// Without `noinit` tag, `Child` would be set to `&ChildCfg{}` whether
// or not `FIELD` is set in the env var.
// With `noinit`, `Child` would stay nil if `FIELD` is not set in the env var.
Child *ChildCfg `env:",noinit"`
}
type ChildCfg struct {
Field string `env:"FIELD"`
}
The noinit
tag is only application for struct pointer fields. Put the tag on
non-struct-pointer will return an error.
You can also define your own decoder for structs (see below).
You can define a custom prefix using the PrefixLookuper
. This will lookup
values in the environment by prefixing the keys with the provided value:
type MyStruct struct {
MyVar string `env:"MYVAR"`
}
// Process variables, but look for the "APP_" prefix.
l := envconfig.PrefixLookuper("APP_", envconfig.OsLookuper())
if err := envconfig.ProcessWith(ctx, &c, l); err != nil {
panic(err)
}
export APP_MYVAR="foo"
All built-in types are supported except Func and Chan. If you need to define a
custom decoder, implement the Decoder
interface:
type MyStruct struct {
field string
}
func (v *MyStruct) EnvDecode(val string) error {
v.field = fmt.Sprintf("PREFIX-%s", val)
return nil
}
var _ envconfig.Decoder = (*MyStruct)(nil) // interface check
If you need to modify environment variable values before processing, you can
specify a custom Mutator
:
type Config struct {
Password `env:"PASSWORD"`
}
func resolveSecretFunc(ctx context.Context, key, value string) (string, error) {
if strings.HasPrefix(value, "secret://") {
return secretmanager.Resolve(ctx, value) // example
}
return value, nil
}
var config Config
envconfig.ProcessWith(ctx, &config, envconfig.OsLookuper(), resolveSecretFunc)
Relying on the environment in tests can be troublesome because environment variables are global, which makes it difficult to parallelize the tests. Envconfig supports extracting data from anything that returns a value:
lookuper := envconfig.MapLookuper(map[string]string{
"FOO": "bar",
"ZIP": "zap",
})
var config Config
envconfig.ProcessWith(ctx, &config, lookuper)
Now you can parallelize all your tests by providing a map for the lookup function. In fact, that's how the tests in this repo work, so check there for an example.
You can also combine multiple lookupers with MultiLookuper
. See the GoDoc for
more information and examples.
This library is conceptually similar to kelseyhightower/envconfig, with the following major behavioral differences:
-
Adds support for specifying a custom lookup function (such as a map), which is useful for testing.
-
Only populates fields if they contain zero or nil values if
overwrite
is unset. This means you can pre-initialize a struct and any pre-populated fields will not be overwritten during processing. -
Support for interpolation. The default value for a field can be the value of another field.
-
Support for arbitrary mutators that change/resolve data before type conversion.