Un-marshaling environment variables to Go structs

Related tags

Configuration envcfg
Overview

envcfg Build Status

Un-marshaling environment variables to Go structs

Getting Started

Let's set a bunch of environment variables and then run your go app

#!/usr/bin/env bash
export DEBUG="false"
export DB_HOST="localhost"
export DB_PORT="8012"

./your_go_app 

Within your Go app do

import "github.com/tomazk/envcfg"

// declare a type that will hold your env variables
type Cfg struct {
	DEBUG   bool
	DB_PORT int
	DB_HOST string
}

func main() {
	var config Cfg
	envcfg.Unmarshal(&config)
	// config is now set to Config{DEBUG: false, DB_PORT: 8012, DB_HOST: "localhost"}
	
	// optional: clear env variables listed in the Cfg struct
	envcfg.ClearEnvVars(&config)
}

Installation

$ go get github.com/tomazk/envcfg

Motivation

As per 12 factor app manifesto configuration of an app should be stored in the environment since it varies between environments by nature. This convention is also dicated and popularized by emerging technologies like docker and cloud platforms.

Instead of having a bunch of os.Getenv("ENV_VAR") buried deep in your code when configuring clients and services, envcfg encourages you to:

  1. define a struct type that will hold your environment variables and serve as documentation which env variables must be configured
  2. use envcfg.Unmarshal to read your env variables and unmarhsal them to an object that now holds your configuration of an app
  3. use envcfg.ClearEnvVars to unset env variables, removing potential vulnerability of passing secrets to unsafe child processes or vendor libraries that assume you're not storing unsafe values in the environment

Documentation

envcfg.Unmarshal

func Unmarshal(v interface{}) error can recieve a reference to an object or even a reference to a pointer:

var val2 StructType
envcfg.Unmarshal(&val2)

var val1 *StructType 
envcfg.Unmarshal(&val1) // val1 will be initialized

Supported Struct Field Types

envcfg.Unmarshal supports int, string, bool and []int, []string, []bool types of fields wihin a struct. In addition, fields that satisfy the encoding.TextUnmarshaler interface are also supported. envcfg.Unmarshal will return nil if a valid struct was passed or return an error if not.

type StructType struct {
	INT           int
	BOOL          bool
	STRING        string
	SLICE_STRING  []string
	SLICE_BOOL    []bool
	SLICE_INT     []int
	CUSTOM_TYPE   MyType
}

type MyType struct{}
func (mt *MyType) UnmarshalText(text []byte) error {
	...
}

Validation

envcfg.Unmarshal also spares you from writing type validation code:

type StructType struct {
	SHOULD_BE_INT int
}

If you'll pass export SHOULD_BE_INT="some_string_value" to your application envcfg.Unmarshal will return an error.

Struct Tags for Custom Mapping of env Variables

You can also use struct field tags to map env variables to fields wihin a struct

export MY_ENV_VAR=1
type StructType struct {
	Field int `envcfg:"MY_ENV_VAR"`
}

Slices Support

envcfg.Unmarshal also supports []int, []string, []bool slices. Values of the slice are ordered in respect to env name suffix. See example below.

export CASSANDRA_HOST_1="192.168.0.20" # *_1 will come as the first element of the slice
export CASSANDRA_HOST_2="192.168.0.21"
export CASSANDRA_HOST_3="192.168.0.22"
type StructType struct {
	CASSANDRA_HOST []string
}
func main() {
	var config StructType
	envcfg.Unmarshal(&config)
	// config.CASSANDRA_HOST is now set to []string{"192.168.0.20", "192.168.0.21", "192.168.0.22"} 
}

envcfg.ClearEnvVars

func ClearEnvVars(v interface{}) error recieves a reference to the same struct you've passed to envcfg.Unmarshal and it will unset any environment variables listed in the struct. Except for those that you want to keep and are tagged with envcfgkeep:"" struct field tag. It will throw an error on unsupported types.

export SECRET_AWS_KEY="foobar" 
export PORT="8080" 
type StructType struct {
	SECRET_AWS_KEY string
	PORT           int    `envcfgkeep:""`
}
func main() {
	var config StructType
	envcfg.ClearEnvVars(&config)
	// it will unset SECRET_AWS_KEY but keep env variable PORT
}

Contributing

Send me a pull request and make sure tests pass on travis.

Tests

Package comes with an extensive test suite that's continuously run on travis against go versions: 1.3, 1.4, 1.5, 1.6, 1.7, 1.8 and the development tip.

$ go test github.com/tomazk/envcfg

Licence

See LICENCE file

Issues
  • add support for fields that satisfy encoding.TextUnmarshaler

    add support for fields that satisfy encoding.TextUnmarshaler

    This adds support for fields that satisfy TextUnmarshaler interface. This allows defining custom data structures, example here https://github.com/BurntSushi/toml#using-the-encodingtextunmarshaler-interface

    opened by nsaje 3
  • Add flag to Unmarshal func to return error for undefined variables in environment

    Add flag to Unmarshal func to return error for undefined variables in environment

    I really like the library. However, I have a use case that requires the unmarshaling to fail if the variables are not present in the environment. I added that flag and updated the unit tests and documentation.

    opened by gortloveslinux 3
  • .env file for default configuration

    .env file for default configuration

    Hey, I really like the approach not to use os.Getenv() everywhere but to Unmarshal to a struct! Great idea.

    I'm just missing the .env file support. Is there a reason I'm not aware of, that it's not there? It wouldn't be that hard to add .env support, right?

    Thanks!

    opened by metalmatze 2
  • Fix typographical error(s)

    Fix typographical error(s)

    @tomazk, I've corrected a typographical error in the documentation of the envcfg project. Specifically, I've changed continous to continuous. You should be able to merge this pull request automatically. However, if this was intentional or if you enjoy living in linguistic squalor, please let me know and create an issue on my home repository.

    opened by orthographic-pedant 1
Simple lib to parse environment variables to structs

env Simple lib to parse envs to structs in Go. Example A very basic example: package main import ( "fmt" "time" // if using go modules "github.c

Carlos Alexandro Becker 2.6k Aug 7, 2022
Small library to read your configuration from environment variables

envconfig envconfig is a library which allows you to parse your configuration from environment variables and fill an arbitrary struct. See the example

Vincent Rischmann 222 May 18, 2022
Go helpers to manage environment variables

Envh This library is made up of two parts : Env object : it wraps your environments variables in an object and provides convenient helpers. Env tree o

Anthony HAMON 95 Apr 14, 2022
goconfig uses a struct as input and populates the fields of this struct with parameters from command line, environment variables and configuration file.

goconfig goconfig uses a struct as input and populates the fields of this struct with parameters from command line, environment variables and configur

Go Sidekick 0 May 30, 2022
A Go port of Ruby's dotenv library (Loads environment variables from `.env`.)

GoDotEnv A Go (golang) port of the Ruby dotenv project (which loads env vars from a .env file) From the original Library: Storing configuration in the

John Barton 5.2k Jul 30, 2022
🛠 A configuration library for Go that parses environment variables, JSON files, and reloads automatically on SIGHUP

config A small configuration library for Go that parses environment variables, JSON files, and reloads automatically on SIGHUP. Example func main() {

Josh Betz 212 Jul 22, 2022
Golang library for managing configuration data from environment variables

envconfig import "github.com/kelseyhightower/envconfig" Documentation See godoc Usage Set some environment variables: export MYAPP_DEBUG=false export

Kelsey Hightower 4.2k Aug 3, 2022
A Go library for parsing struct tags from environment variables.

Envconfig Envconfig populates struct field values based on environment variables or arbitrary lookup functions. It supports pre-setting mutations, whi

Seth Vargo 655 Aug 4, 2022
Environment variables substitution for Go

envsubst Environment variables substitution for Go. see docs below Installation: From binaries Latest stable envsubst prebuilt binaries for 64-bit Lin

Ariel Mashraki 519 Jul 29, 2022
Quickly read variables from environment files

go-quick-env Quickly read variables from environment files The best way to import environment variables to your code, is by using .env files. This lib

Panos Petropoulos 3 May 11, 2021
Read files into environment variables and execute command

read-file-to-env -- Read files into environment variables and execute command Example use: read-file-to-env -one-line=HOST=/etc/hostname sh -c 'echo h

Tv 2 Nov 12, 2021
A mapper of ENVironment variables to Structure for Go

envs a mapper of ENVironment variables to a Structure for Go. This library maps the environment variables to the struct according to the fields' types

moznion 3 Dec 3, 2021
Golang library for reading properties from configuration files in JSON and YAML format or from environment variables.

go-config Golang library for reading properties from configuration files in JSON and YAML format or from environment variables. Usage Create config in

null 3 Feb 22, 2022
Environment variables configuration package for Go microservices.

gocfg Environment variables configuration package for Go microservices. It helps validate environment variable values and set default values if needed

Sergey Prokhorov 0 Dec 30, 2021
formicidate is a small tool for Go application can update the value of environment variables in a .env file with code

formicidae Update .env files in Go with code. What is fomicidae? formicidate is a small tool for Go application. You can update the value of environme

akuma 0 Jan 23, 2022
Lightweight package that makes easier and safer to deal with environment variables.

Envisage A lightweight package that makes easier and safer to deal with environment variables. Example Try it on On GoPlay https://goplay.tools/snippe

GOLang Sugar 4 Apr 11, 2022
Tmpl - A tool to apply variables from cli, env, JSON/TOML/YAML files to templates

tmpl allows to apply variables from JSON/TOML/YAML files, environment variables or CLI arguments to template files using Golang text/template and functions from the Sprig project.

krako 1 May 30, 2022
Library for setting values to structs' fields from env, flags, files or default tag

Configuration is a library for injecting values recursively into structs - a convenient way of setting up a configuration object. Available features:

Bogdan Daragan 73 Jul 25, 2022
✨Clean and minimalistic environment configuration reader for Golang

Clean Env Minimalistic configuration reader Overview This is a simple configuration reading tool. It just does the following: reads and parses configu

Ilya Kaznacheev 686 Aug 8, 2022