config

README

Config

Samber EDIT => Removed PARENT__CHILD nested environment variables + Add ignore tag

Manage your application config as a typesafe struct in as little as two function calls.

type MyConfig struct {
	DatabaseUrl string `config:"DATABASE_URL"`
	FeatureFlag bool   `config:"FEATURE_FLAG"`
	Port        int // tags are optional. PORT is assumed
	...
}

var c MyConfig
config.FromEnv().To(&c)

How It Works

Its just simple, pure stdlib.

• A field's type determines what strconv function is called.

• All string conversion rules are as defined in the strconv package

• If chaining multiple data sources, data sets are merged. Later values override previous values.

  config.From("dev.config").FromEnv().To(&c)
  

• Unset values remain as their native zero value

• Env vars map to struct fields case insensitively

  • NOTE: Also true when using struct tags.

Why you should use this

• Its the cloud-native way to manage config. See 12 Factor Apps
• Simple:
  • only 2 lines to configure.
• Composeable:
  • Merge local files and environment variables for effortless local development.
• small:
  • only stdlib
  • < 180 LoC

Design Philosophy

Opinionated and narrow in scope. This library is only meant to do config binding. Feel free to use it on its own, or alongside other libraries.

• Only structs at the entry point. This keeps the API surface small.

• Slices are space delimited. This matches how environment variables and commandline args are handled by the go cmd.

• No slices of structs. The extra complexity isn't warranted for such a niche usecase.

• No maps. The only feature of maps not handled by structs for this usecase is dynamic keys.

• No pointer members. If you really need one, just take the address of parts of your struct.

Documentation

Overview

Package config provides typesafe, cloud native configuration binding from environment variables or files to structs.

Configuration can be done in as little as two lines:

var c MyConfig
config.FromEnv().To(&c)

A field's type determines what https://golang.org/pkg/strconv/ function is called.

All string conversion rules are as defined in the https://golang.org/pkg/strconv/ package.

If chaining multiple data sources, data sets are merged.

Later values override previous values.

config.From("dev.config").FromEnv().To(&c)

Unset values remain as their native zero value: https://tour.golang.org/basics/12.

Env vars map to struct fields case insensitively. NOTE: Also true when using struct tags.

Example

package main

import (
	"fmt"
	"os"

	"github.com/samber/config"
)

type MySubConfig struct {
	IPWhitelist []string      `config:"SUBCONFIG_IPWHITELIST"`
	Ignore      func() string `config:",ignore"`
}

type MyConfig struct {
	DatabaseURL string `config:"DATABASE_URL"`
	Port        int
	FeatureFlag bool `config:"FEATURE_FLAG"`
	SubConfig   MySubConfig
	Json        map[string]interface{} `config:"CONFIG_JSON"`
}

func main() {
	os.Clearenv()
	os.Setenv("DATABASE_URL", "db://")
	os.Setenv("PORT", "1234")
	os.Setenv("FEATURE_FLAG", "true") // also accepts t, f, 0, 1 etc. see strconv package.
	// Double underscore for sub structs. Space separation for slices.
	os.Setenv("SUBCONFIG_IPWHITELIST", "0.0.0.0 1.1.1.1 2.2.2.2")
	os.Setenv("CONFIG_JSON", `{"foo": "bar"}`)

	var c MyConfig
	config.FromEnv().To(&c)

	fmt.Println(c.DatabaseURL)
	fmt.Println(c.Port)
	fmt.Println(c.FeatureFlag)
	fmt.Println(c.SubConfig.IPWhitelist, len(c.SubConfig.IPWhitelist))
	fmt.Println(c.Json)
	fmt.Println(c.Json["foo"])

}

Output:

db://
1234
true
[0.0.0.0 1.1.1.1 2.2.2.2] 3
map[foo:bar]
bar

Example (FromFileWithOverride)

package main

import (
	"fmt"
	"io/ioutil"
	"os"
	"strings"

	"github.com/samber/config"
)

type MySubConfig struct {
	IPWhitelist []string      `config:"SUBCONFIG_IPWHITELIST"`
	Ignore      func() string `config:",ignore"`
}

type MyConfig struct {
	DatabaseURL string `config:"DATABASE_URL"`
	Port        int
	FeatureFlag bool `config:"FEATURE_FLAG"`
	SubConfig   MySubConfig
	Json        map[string]interface{} `config:"CONFIG_JSON"`
}

func main() {
	tempFile, _ := ioutil.TempFile("", "temp")
	tempFile.Write([]byte(strings.Join([]string{"PORT=1234", "FEATURE_FLAG=true"}, "\n")))
	tempFile.Close()

	os.Clearenv()
	os.Setenv("DATABASE_URL", "db://")
	os.Setenv("PORT", "5678")

	var c MyConfig
	config.From(tempFile.Name()).FromEnv().To(&c)

	// db:// was only set in ENV
	fmt.Println(c.DatabaseURL)
	// 1234 was overridden by 5678
	fmt.Println(c.Port)
	// FeatureFlag was was only set in file
	fmt.Println(c.FeatureFlag)

}

Output:

db://
5678
true

Example (StructTags)

package main

import (
	"fmt"
	"os"

	"github.com/samber/config"
)

func main() {
	type MyConfig struct {
		// NOTE: even when using tags, lookup is still case insensitive.
		// dAtABase_urL would still work.
		DatabaseURL string `config:"DATABASE_URL"`
	}

	os.Clearenv()
	os.Setenv("DATABASE_URL", "db://")

	var c MyConfig
	config.FromEnv().To(&c)

	fmt.Println(c.DatabaseURL)

}

Output:

db://

Index

• type Builder
  • func From(file string) *Builder
  • func FromEnv() *Builder
  • func (c *Builder) From(file string) *Builder
  • func (c *Builder) FromEnv() *Builder
  • func (c *Builder) To(target interface{})

Examples

• Package
• Package (FromFileWithOverride)
• Package (StructTags)

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder contains the current configuration state.

func From

func From(file string) *Builder

From returns a new Builder, populated with the values from file. It panics if unable to open the file.

func FromEnv

func FromEnv() *Builder

FromEnv returns a new Builder, populated with environment variables

func (*Builder) From

func (c *Builder) From(file string) *Builder

From merges new values from file into the current config state, returning the Builder. It panics if unable to open the file.

func (*Builder) FromEnv

func (c *Builder) FromEnv() *Builder

FromEnv merges new values from the environment into the current config state, returning the Builder.

func (*Builder) To

func (c *Builder) To(target interface{})

To accepts a struct pointer, and populates it with the current config state. Supported fields:

• all int, uint, float variants
• bool, struct, string
• slice of any of the above, except for []struct{}

It panics under the following circumstances:

• target is not a struct pointer
• struct contains unsupported fields (pointers, maps, slice of structs, channels, arrays, funcs, interfaces, complex)