Thread-safe configuration management for Go with support for TOML files, environment variables, command-line arguments, and defaults with configurable precedence.

Installation

go get github.com/LixenWraith/config

Quick Start

package main

import (
    "log"
	
    "github.com/lixenwraith/config"
)

type AppConfig struct {
    Server struct {
        Host string `toml:"host"`
        Port int    `toml:"port"`
    } `toml:"server"`
    Database struct {
        URL      string `toml:"url"`
        MaxConns int    `toml:"max_conns"`
    } `toml:"database"`
    Debug bool `toml:"debug"`
}

func main() {
    // Define defaults
    defaults := AppConfig{}
    defaults.Server.Host = "localhost"
    defaults.Server.Port = 8080
    defaults.Database.URL = "postgres://localhost/myapp"
    defaults.Database.MaxConns = 10

    // Initialize with environment prefix and config file
    cfg, err := config.Quick(defaults, "MYAPP_", "config.toml")
    if err != nil {
        log.Fatal(err)
    }

    // Access values
    host, _ := cfg.String("server.host")
    port, _ := cfg.Int64("server.port")
    dbURL, _ := cfg.String("database.url")
    debug, _ := cfg.Bool("debug")

    log.Printf("Server: %s:%d, DB: %s, Debug: %v", host, port, dbURL, debug)
}

config.toml:

[server]
host = "production.example.com"
port = 9090

[database]
url = "postgres://prod-db/myapp"
max_conns = 50

debug = false

Usage:

# Override with environment variables
export MYAPP_SERVER_PORT=8443
export MYAPP_DEBUG=true

# Override with CLI arguments  
./myapp --server.port=9999 --debug

Key Features

Multiple Sources: Defaults → File → Environment → CLI (configurable order)
Type Safety: Automatic conversion with detailed error messages
Thread-Safe: Concurrent reads with protected writes
Builder Pattern: Fluent interface for advanced configuration
Source Tracking: See which source provided each value
Zero Dependencies: Only stdlib + minimal parsers

Common Patterns

Custom Precedence

cfg, _ := config.NewBuilder().
    WithDefaults(defaults).
    WithSources(
        config.SourceEnv,     // Env vars highest priority
        config.SourceFile,
        config.SourceCLI,
        config.SourceDefault,
    ).
    Build()

Environment Variable Mapping

// Custom env var names
opts := config.LoadOptions{
    EnvTransform: func(path string) string {
        switch path {
        case "server.port": return "PORT"
        case "database.url": return "DATABASE_URL"
        default: return ""
        }
    },
}
cfg.LoadWithOptions("config.toml", os.Args[1:], opts)

Validation

// Register and validate required fields
cfg.RegisterRequired("api.key", "")
cfg.RegisterRequired("database.url", "")

if err := cfg.Validate("api.key", "database.url"); err != nil {
    log.Fatal("Missing required config: ", err)
}

Source Inspection

// See all sources for a value
sources := cfg.GetSources("server.port")
for source, value := range sources {
    fmt.Printf("%s: %v\n", source, value)
}

// Get value from specific source
envPort, exists := cfg.GetSource("server.port", config.SourceEnv)

Struct Scanning

var serverConfig struct {
    Host string `toml:"host"`
    Port int    `toml:"port"`
}
cfg.Scan("server", &serverConfig)

Environment Whitelist

// Only load specific env vars
cfg, _ := config.NewBuilder().
    WithDefaults(defaults).
    WithEnvPrefix("MYAPP_").
    WithEnvWhitelist("api.key", "database.password").
    Build()

API Reference

Core Methods

Quick(defaults, envPrefix, configFile) - Quick initialization
Register(path, defaultValue) - Register configuration path
Get/String/Int64/Bool/Float64(path) - Type-safe accessors
Set(path, value) - Update configuration
Validate(paths...) - Ensure required values are set

Advanced Methods

NewBuilder() - Create custom configuration
GetSource(path, source) - Get value from specific source
GetSources(path) - Get all source values
Scan(basePath, target) - Unmarshal into struct
Clone() - Deep copy configuration
Debug() - Show all values and sources

License

BSD-3-Clause