config

README

Config

Golang Configuration tool that support YAML, JSON, TOML, Shell Environment (Supports Go 1.10+)

Usage

var Config = struct {
	APPName string `default:"app name"`

	DB struct {
		Name     string
		User     string `default:"root"`
		Password string `required:"true" env:"DBPassword"`
		Port     uint   `default:"3306"`
	}

	Contacts []struct {
		Name  string
		Email string `required:"true"`
	}
}{}

func main() {
	config.Load(&Config, "config.yml")
	fmt.Printf("config: %#v", Config)
}

With configuration file config.yml:

appname: test

db:
    name:     test
    user:     test
    password: test
    port:     1234

contacts:
- name: i test
  email: test@test.com

Debug Mode & Verbose Mode

Debug/Verbose mode is helpful when debuging your application, debug mode will let you know how config loaded your configurations, like from which file, shell env, verbose mode will tell you even more, like those shell environments config tried to load.

// Enable debug mode or set env `CONFIG_DEBUG_MODE` to true when running your application
config.New(&config.Config{Debug: true}).Load(&Config, "config.json")

// Enable verbose mode or set env `CONFIG_VERBOSE_MODE` to true when running your application
config.New(&config.Config{Verbose: true}).Load(&Config, "config.json")

Auto Reload Mode

Config can auto reload configuration based on time

// auto reload configuration every second
config.New(&config.Config{AutoReload: true}).Load(&Config, "config.json")

// auto reload configuration every minute
config.New(&config.Config{AutoReload: true, AutoReloadInterval: time.Minute}).Load(&Config, "config.json")

Auto Reload Callback

config.New(&config.Config{AutoReload: true, AutoReloadCallback: func(config interface{}) {
    fmt.Printf("%v changed", config)
}}).Load(&Config, "config.json")

Advanced Usage

• Load mutiple configurations

// Earlier configurations have higher priority
config.Load(&Config, "application.yml", "database.json")

• Return error on unmatched keys

Return an error on finding keys in the config file that do not match any fields in the config struct. In the example below, an error will be returned if config.toml contains keys that do not match any fields in the ConfigStruct struct. If ErrorOnUnmatchedKeys is not set, it defaults to false.

Note that for json files, setting ErrorOnUnmatchedKeys to true will have an effect only if using go 1.10 or later.

err := config.New(&config.Config{ErrorOnUnmatchedKeys: true}).Load(&ConfigStruct, "config.toml")

• Load configuration by environment

Use CONFIG_ENV to set environment, if CONFIG_ENV not set, environment will be development by default, and it will be test when running tests with go test

// config.go
config.Load(&Config, "config.json")

$ go run config.go
// Will load `config.json`, `config.development.json` if it exists
// `config.development.json` will overwrite `config.json`'s configuration
// You could use this to share same configuration across different environments

$ CONFIG_ENV=production go run config.go
// Will load `config.json`, `config.production.json` if it exists
// `config.production.json` will overwrite `config.json`'s configuration

$ go test
// Will load `config.json`, `config.test.json` if it exists
// `config.test.json` will overwrite `config.json`'s configuration

$ CONFIG_ENV=production go test
// Will load `config.json`, `config.production.json` if it exists
// `config.production.json` will overwrite `config.json`'s configuration

// Set environment by config
config.New(&config.Config{Environment: "production"}).Load(&Config, "config.json")

• Example Configuration

// config.go
config.Load(&Config, "config.yml")

$ go run config.go
// Will load `config.example.yml` automatically if `config.yml` not found and print warning message

• Load From Shell Environment

$ CONFIG_APPNAME="hello world" CONFIG_DB_NAME="hello world" go run config.go
// Load configuration from shell environment, it's name is {{prefix}}_FieldName

// You could overwrite the prefix with environment CONFIG_ENV_PREFIX, for example:
$ CONFIG_ENV_PREFIX="WEB" WEB_APPNAME="hello world" WEB_DB_NAME="hello world" go run config.go

// Set prefix by config
config.New(&config.Config{ENVPrefix: "WEB"}).Load(&Config, "config.json")

• Anonymous Struct

Add the anonymous:"true" tag to an anonymous, embedded struct to NOT include the struct name in the environment variable of any contained fields. For example:

type Details struct {
	Description string
}

type Config struct {
	Details `anonymous:"true"`
}

With the anonymous:"true" tag specified, the environment variable for the Description field is CONFIG_DESCRIPTION. Without the anonymous:"true"tag specified, then environment variable would include the embedded struct name and be CONFIG_DETAILS_DESCRIPTION.

• With flags

func main() {
	config := flag.String("file", "config.yml", "configuration file")
	flag.StringVar(&Config.APPName, "name", "", "app name")
	flag.StringVar(&Config.DB.Name, "db-name", "", "database name")
	flag.StringVar(&Config.DB.User, "db-user", "root", "database user")
	flag.Parse()

	os.Setenv("CONFIG_ENV_PREFIX", "-")
	config.Load(&Config, *config)
	// config.Load(&Config) // only load configurations from shell env & flag
}

Credit

Originally forked from configor

Documentation

Index

• func ENV() string
• func GetStringTomlKeys(list []toml.Key) []string
• type Config
  • func Load(cfg interface{}, files ...string) (*Config, error)
  • func New(cfg *Settings) *Config
  • func (c *Config) GetEnvironment() string
  • func (c *Config) GetErrorOnUnmatchedKeys() bool
  • func (c *Config) Load(cfg interface{}, files ...string) (err error)
• type Settings
• type UnmatchedTomlKeysError
  • func (e *UnmatchedTomlKeysError) Error() string

Functions

func ENV

func ENV() string

ENV return environment

func GetStringTomlKeys

func GetStringTomlKeys(list []toml.Key) []string

GetStringTomlKeys returns a string array of the names of the keys that are passed in as args

Types

type Config

type Config struct {
	*Settings
	// contains filtered or unexported fields
}

func Load

func Load(cfg interface{}, files ...string) (*Config, error)

Load will unmarshal configurations to struct from files that you provide

func New

func New(cfg *Settings) *Config

New initialize a Config

func (*Config) GetEnvironment

func (c *Config) GetEnvironment() string

GetEnvironment get environment

func (*Config) GetErrorOnUnmatchedKeys

func (c *Config) GetErrorOnUnmatchedKeys() bool

GetErrorOnUnmatchedKeys returns a boolean indicating if an error should be thrown if there are keys in the cfg file that do not correspond to the cfg struct

func (*Config) Load

func (c *Config) Load(cfg interface{}, files ...string) (err error)

Load will unmarshal configurations to struct from files that you provide

type Settings

type Settings struct {
	Environment        string
	ENVPrefix          string
	Debug              bool
	Verbose            bool
	Silent             bool
	AutoReload         bool
	AutoReloadInterval time.Duration
	AutoReloadCallback func(cfg interface{})

	// In case of json files, this field will be used only when compiled with
	// go 1.10 or later.
	// This field will be ignored when compiled with go versions lower than 1.10.
	ErrorOnUnmatchedKeys bool
}

type UnmatchedTomlKeysError

type UnmatchedTomlKeysError struct {
	Keys []toml.Key
}

UnmatchedTomlKeysError errors are returned by the Load function when ErrorOnUnmatchedKeys is set to true and there are unmatched keys in the input toml cfg file. The string returned by Error() contains the names of the missing keys.

func (*UnmatchedTomlKeysError) Error

func (e *UnmatchedTomlKeysError) Error() string