RemoteConfig is optional, see the remote package.
var RemoteConfig remoteConfigFactory
SupportedExts are universally supported extensions.
var SupportedExts = []string{"json", "toml", "yaml", "yml", "properties", "props", "prop", "hcl", "tfvars", "dotenv", "env", "ini"}
SupportedRemoteProviders are universally supported remote providers.
var SupportedRemoteProviders = []string{"etcd", "etcd3", "consul", "firestore", "nats"}
func AddConfigPath(in string)
AddConfigPath adds a path for Viper to search for the config file in. Can be called multiple times to define multiple search paths.
func AddRemoteProvider(provider, endpoint, path string) error
AddRemoteProvider adds a remote configuration source. Remote Providers are searched in the order they are added. provider is a string value: "etcd", "etcd3", "consul", "firestore" or "nats" are currently supported. endpoint is the url. etcd requires http://ip:port, consul requires ip:port, nats requires nats://ip:port path is the path in the k/v store to retrieve configuration To retrieve a config file called myapp.json from /configs/myapp.json you should set path to /configs and set config name (SetConfigName()) to "myapp".
func AddSecureRemoteProvider(provider, endpoint, path, secretkeyring string) error
AddSecureRemoteProvider adds a remote configuration source. Secure Remote Providers are searched in the order they are added. provider is a string value: "etcd", "etcd3", "consul", "firestore" or "nats" are currently supported. endpoint is the url. etcd requires http://ip:port consul requires ip:port secretkeyring is the filepath to your openpgp secret keyring. e.g. /etc/secrets/myring.gpg path is the path in the k/v store to retrieve configuration To retrieve a config file called myapp.json from /configs/myapp.json you should set path to /configs and set config name (SetConfigName()) to "myapp". Secure Remote Providers are implemented with github.com/bketelsen/crypt.
func AllKeys() []string
AllKeys returns all keys holding a value, regardless of where they are set. Nested keys are returned with a v.keyDelim separator.
func AllSettings() map[string]any
AllSettings merges all settings and returns them as a map[string]any.
func AllowEmptyEnv(allowEmptyEnv bool)
AllowEmptyEnv tells Viper to consider set, but empty environment variables as valid values instead of falling back. For backward compatibility reasons this is false by default.
func AutomaticEnv()
AutomaticEnv makes Viper check if environment variables match any of the existing keys (config, default or flags). If matching env vars are found, they are loaded into Viper.
func BindEnv(input ...string) error
BindEnv binds a Viper key to a ENV variable. ENV variables are case sensitive. If only a key is provided, it will use the env key matching the key, uppercased. If more arguments are provided, they will represent the env variable names that should bind to this key and will be taken in the specified order. EnvPrefix will be used when set when env name is not provided.
func BindFlagValue(key string, flag FlagValue) error
BindFlagValue binds a specific key to a FlagValue.
func BindFlagValues(flags FlagValueSet) error
BindFlagValues binds a full FlagValue set to the configuration, using each flag's long name as the config key.
func BindPFlag(key string, flag *pflag.Flag) error
BindPFlag binds a specific key to a pflag (as used by cobra). Example (where serverCmd is a Cobra instance):
serverCmd.Flags().Int("port", 1138, "Port to run Application server on")
Viper.BindPFlag("port", serverCmd.Flags().Lookup("port"))
func BindPFlags(flags *pflag.FlagSet) error
BindPFlags binds a full flag set to the configuration, using each flag's long name as the config key.
func ConfigFileUsed() string
ConfigFileUsed returns the file used to populate the config registry.
func Debug()
Debug prints all configuration registries for debugging purposes.
func DebugTo(w io.Writer)
func Get(key string) any
Get can retrieve any value given the key to use. Get is case-insensitive for a key. Get has the behavior of returning the value associated with the first place from where it is set. Viper will check in the following order: override, flag, env, config file, key/value store, default
Get returns an interface. For a specific value use one of the Get____ methods.
func GetBool(key string) bool
GetBool returns the value associated with the key as a boolean.
func GetDuration(key string) time.Duration
GetDuration returns the value associated with the key as a duration.
func GetEnvPrefix() string
func GetFloat64(key string) float64
GetFloat64 returns the value associated with the key as a float64.
func GetInt(key string) int
GetInt returns the value associated with the key as an integer.
func GetInt32(key string) int32
GetInt32 returns the value associated with the key as an integer.
func GetInt64(key string) int64
GetInt64 returns the value associated with the key as an integer.
func GetIntSlice(key string) []int
GetIntSlice returns the value associated with the key as a slice of int values.
func GetSizeInBytes(key string) uint
GetSizeInBytes returns the size of the value associated with the given key in bytes.
func GetString(key string) string
GetString returns the value associated with the key as a string.
func GetStringMap(key string) map[string]any
GetStringMap returns the value associated with the key as a map of interfaces.
func GetStringMapString(key string) map[string]string
GetStringMapString returns the value associated with the key as a map of strings.
func GetStringMapStringSlice(key string) map[string][]string
GetStringMapStringSlice returns the value associated with the key as a map to a slice of strings.
func GetStringSlice(key string) []string
GetStringSlice returns the value associated with the key as a slice of strings.
func GetTime(key string) time.Time
GetTime returns the value associated with the key as time.
func GetUint(key string) uint
GetUint returns the value associated with the key as an unsigned integer.
func GetUint16(key string) uint16
GetUint16 returns the value associated with the key as an unsigned integer.
func GetUint32(key string) uint32
GetUint32 returns the value associated with the key as an unsigned integer.
func GetUint64(key string) uint64
GetUint64 returns the value associated with the key as an unsigned integer.
func InConfig(key string) bool
InConfig checks to see if the given key (or an alias) is in the config file.
func IsSet(key string) bool
IsSet checks to see if the key has been set in any of the data locations. IsSet is case-insensitive for a key.
func MergeConfig(in io.Reader) error
MergeConfig merges a new configuration with an existing config.
func MergeConfigMap(cfg map[string]any) error
MergeConfigMap merges the configuration from the map given with an existing config. Note that the map given may be modified.
func MergeInConfig() error
MergeInConfig merges a new configuration with an existing config.
func MustBindEnv(input ...string)
MustBindEnv wraps BindEnv in a panic. If there is an error binding an environment variable, MustBindEnv will panic.
func OnConfigChange(run func(in fsnotify.Event))
OnConfigChange sets the event handler that is called when a config file changes.
func ReadConfig(in io.Reader) error
ReadConfig will read a configuration file, setting existing keys to nil if the key does not exist in the file.
func ReadInConfig() error
ReadInConfig will discover and load the configuration file from disk and key/value stores, searching in one of the defined paths.
func ReadRemoteConfig() error
ReadRemoteConfig attempts to get configuration from a remote source and read it in the remote configuration registry.
func RegisterAlias(alias, key string)
RegisterAlias creates an alias that provides another accessor for the same key. This enables one to change a name without breaking the application.
func Reset()
Reset is intended for testing, will reset all to default settings. In the public interface for the viper package so applications can use it in their testing as well.
func SafeWriteConfig() error
SafeWriteConfig writes current configuration to file only if the file does not exist.
func SafeWriteConfigAs(filename string) error
SafeWriteConfigAs writes current configuration to a given filename if it does not exist.
func Set(key string, value any)
Set sets the value for the key in the override register. Set is case-insensitive for a key. Will be used instead of values obtained via flags, config file, ENV, default, or key/value store.
func SetConfigFile(in string)
SetConfigFile explicitly defines the path, name and extension of the config file. Viper will use this and not check any of the config paths.
func SetConfigName(in string)
SetConfigName sets name for the config file. Does not include extension.
func SetConfigPermissions(perm os.FileMode)
SetConfigPermissions sets the permissions for the config file.
func SetConfigType(in string)
SetConfigType sets the type of the configuration returned by the remote source, e.g. "json".
func SetDefault(key string, value any)
SetDefault sets the default value for this key. SetDefault is case-insensitive for a key. Default only used when no value is provided by the user via flag, config or ENV.
func SetEnvKeyReplacer(r *strings.Replacer)
SetEnvKeyReplacer sets the strings.Replacer on the viper object Useful for mapping an environmental variable to a key that does not match it.
func SetEnvPrefix(in string)
SetEnvPrefix defines a prefix that ENVIRONMENT variables will use. E.g. if your prefix is "spf", the env registry will look for env variables that start with "SPF_".
func SetFs(fs afero.Fs)
SetFs sets the filesystem to use to read configuration.
func SetTypeByDefaultValue(enable bool)
SetTypeByDefaultValue enables or disables the inference of a key value's type when the Get function is used based upon a key's default value as opposed to the value returned based on the normal fetch logic.
For example, if a key has a default value of []string{} and the same key is set via an environment variable to "a b c", a call to the Get function would return a string slice for the key if the key's type is inferred by the default value and the Get function would return:
[]string {"a", "b", "c"}
Otherwise the Get function would return:
"a b c"
func Unmarshal(rawVal any, opts ...DecoderConfigOption) error
Unmarshal unmarshals the config into a Struct. Make sure that the tags on the fields of the structure are properly set.
func UnmarshalExact(rawVal any, opts ...DecoderConfigOption) error
UnmarshalExact unmarshals the config into a Struct, erroring if a field is nonexistent in the destination struct.
func UnmarshalKey(key string, rawVal any, opts ...DecoderConfigOption) error
UnmarshalKey takes a single key and unmarshals it into a Struct.
func WatchConfig()
WatchConfig starts watching a config file for changes.
func WatchRemoteConfig() error
func WriteConfig() error
WriteConfig writes the current configuration to a file.
func WriteConfigAs(filename string) error
WriteConfigAs writes current configuration to a given filename.
ConfigFileAlreadyExistsError denotes failure to write new configuration file.
type ConfigFileAlreadyExistsError string
func (faee ConfigFileAlreadyExistsError) Error() string
Error returns the formatted error when configuration already exists.
ConfigFileNotFoundError denotes failing to find configuration file.
type ConfigFileNotFoundError struct {
// contains filtered or unexported fields
}
func (fnfe ConfigFileNotFoundError) Error() string
Error returns the formatted configuration error.
ConfigMarshalError happens when failing to marshal the configuration.
type ConfigMarshalError struct {
// contains filtered or unexported fields
}
func (e ConfigMarshalError) Error() string
Error returns the formatted configuration error.
ConfigParseError denotes failing to parse configuration file.
type ConfigParseError struct {
// contains filtered or unexported fields
}
func (pe ConfigParseError) Error() string
Error returns the formatted configuration error.
func (pe ConfigParseError) Unwrap() error
Unwrap returns the wrapped error.
A DecoderConfigOption can be passed to viper.Unmarshal to configure mapstructure.DecoderConfig options.
type DecoderConfigOption func(*mapstructure.DecoderConfig)
func DecodeHook(hook mapstructure.DecodeHookFunc) DecoderConfigOption
DecodeHook returns a DecoderConfigOption which overrides the default DecoderConfig.DecodeHook value, the default is:
mapstructure.ComposeDecodeHookFunc(
mapstructure.StringToTimeDurationHookFunc(),
mapstructure.StringToSliceHookFunc(","),
)
FlagValue is an interface that users can implement to bind different flags to viper.
type FlagValue interface {
HasChanged() bool
Name() string
ValueString() string
ValueType() string
}
FlagValueSet is an interface that users can implement to bind a set of flags to viper.
type FlagValueSet interface {
VisitAll(fn func(FlagValue))
}
Logger is a unified interface for various logging use cases and practices, including:
Deprecated: use `log/slog` instead.
type Logger interface {
// Trace logs a Trace event.
//
// Even more fine-grained information than Debug events.
// Loggers not supporting this level should fall back to Debug.
Trace(msg string, keyvals ...any)
// Debug logs a Debug event.
//
// A verbose series of information events.
// They are useful when debugging the system.
Debug(msg string, keyvals ...any)
// Info logs an Info event.
//
// General information about what's happening inside the system.
Info(msg string, keyvals ...any)
// Warn logs a Warn(ing) event.
//
// Non-critical events that should be looked at.
Warn(msg string, keyvals ...any)
// Error logs an Error event.
//
// Critical events that require immediate attention.
// Loggers commonly provide Fatal and Panic levels above Error level,
// but exiting and panicking is out of scope for a logging library.
Error(msg string, keyvals ...any)
}
Option configures Viper using the functional options paradigm popularized by Rob Pike and Dave Cheney. If you're unfamiliar with this style, see https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html and https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis.
type Option interface {
// contains filtered or unexported methods
}
func EnvKeyReplacer(r StringReplacer) Option
EnvKeyReplacer sets a replacer used for mapping environment variables to internal keys.
func IniLoadOptions(in ini.LoadOptions) Option
IniLoadOptions sets the load options for ini parsing.
func KeyDelimiter(d string) Option
KeyDelimiter sets the delimiter used for determining key parts. By default it's value is ".".
func WithLogger(l *slog.Logger) Option
WithLogger sets a custom logger.
RemoteConfigError denotes encountering an error while trying to pull the configuration from the remote provider.
type RemoteConfigError string
func (rce RemoteConfigError) Error() string
Error returns the formatted remote provider error.
RemoteProvider stores the configuration necessary to connect to a remote key/value store. Optional secretKeyring to unencrypt encrypted values can be provided.
type RemoteProvider interface {
Provider() string
Endpoint() string
Path() string
SecretKeyring() string
}
type RemoteResponse struct {
Value []byte
Error error
}
StringReplacer applies a set of replacements to a string.
type StringReplacer interface {
// Replace returns a copy of s with all replacements performed.
Replace(s string) string
}
UnsupportedConfigError denotes encountering an unsupported configuration filetype.
type UnsupportedConfigError string
func (str UnsupportedConfigError) Error() string
Error returns the formatted configuration error.
UnsupportedRemoteProviderError denotes encountering an unsupported remote provider. Currently only etcd and Consul are supported.
type UnsupportedRemoteProviderError string
func (str UnsupportedRemoteProviderError) Error() string
Error returns the formatted remote provider error.
Viper is a prioritized configuration registry. It maintains a set of configuration sources, fetches values to populate those, and provides them according to the source's priority. The priority of the sources is the following: 1. overrides 2. flags 3. env. variables 4. config file 5. key/value store 6. defaults
For example, if values from the following sources were loaded:
Defaults : {
"secret": "",
"user": "default",
"endpoint": "https://localhost"
}
Config : {
"user": "root"
"secret": "defaultsecret"
}
Env : {
"secret": "somesecretkey"
}
The resulting config will have the following values:
{
"secret": "somesecretkey",
"user": "root",
"endpoint": "https://localhost"
}
Note: Vipers are not safe for concurrent Get() and Set() operations.
type Viper struct {
// contains filtered or unexported fields
}
func GetViper() *Viper
GetViper gets the global Viper instance.
func New() *Viper
New returns an initialized Viper instance.
func NewWithOptions(opts ...Option) *Viper
NewWithOptions creates a new Viper instance.
func Sub(key string) *Viper
Sub returns new Viper instance representing a sub tree of this instance. Sub is case-insensitive for a key.
func (v *Viper) AddConfigPath(in string)
func (v *Viper) AddRemoteProvider(provider, endpoint, path string) error
func (v *Viper) AddSecureRemoteProvider(provider, endpoint, path, secretkeyring string) error
func (v *Viper) AllKeys() []string
func (v *Viper) AllSettings() map[string]any
func (v *Viper) AllowEmptyEnv(allowEmptyEnv bool)
func (v *Viper) AutomaticEnv()
func (v *Viper) BindEnv(input ...string) error
func (v *Viper) BindFlagValue(key string, flag FlagValue) error
func (v *Viper) BindFlagValues(flags FlagValueSet) (err error)
func (v *Viper) BindPFlag(key string, flag *pflag.Flag) error
func (v *Viper) BindPFlags(flags *pflag.FlagSet) error
func (v *Viper) ConfigFileUsed() string
func (v *Viper) Debug()
func (v *Viper) DebugTo(w io.Writer)
func (v *Viper) Get(key string) any
func (v *Viper) GetBool(key string) bool
func (v *Viper) GetDuration(key string) time.Duration
func (v *Viper) GetEnvPrefix() string
func (v *Viper) GetFloat64(key string) float64
func (v *Viper) GetInt(key string) int
func (v *Viper) GetInt32(key string) int32
func (v *Viper) GetInt64(key string) int64
func (v *Viper) GetIntSlice(key string) []int
func (v *Viper) GetSizeInBytes(key string) uint
func (v *Viper) GetString(key string) string
func (v *Viper) GetStringMap(key string) map[string]any
func (v *Viper) GetStringMapString(key string) map[string]string
func (v *Viper) GetStringMapStringSlice(key string) map[string][]string
func (v *Viper) GetStringSlice(key string) []string
func (v *Viper) GetTime(key string) time.Time
func (v *Viper) GetUint(key string) uint
func (v *Viper) GetUint16(key string) uint16
func (v *Viper) GetUint32(key string) uint32
func (v *Viper) GetUint64(key string) uint64
func (v *Viper) InConfig(key string) bool
func (v *Viper) IsSet(key string) bool
func (v *Viper) MergeConfig(in io.Reader) error
func (v *Viper) MergeConfigMap(cfg map[string]any) error
func (v *Viper) MergeInConfig() error
func (v *Viper) MustBindEnv(input ...string)
func (v *Viper) OnConfigChange(run func(in fsnotify.Event))
OnConfigChange sets the event handler that is called when a config file changes.
func (v *Viper) ReadConfig(in io.Reader) error
func (v *Viper) ReadInConfig() error
func (v *Viper) ReadRemoteConfig() error
func (v *Viper) RegisterAlias(alias, key string)
func (v *Viper) SafeWriteConfig() error
func (v *Viper) SafeWriteConfigAs(filename string) error
func (v *Viper) Set(key string, value any)
func (v *Viper) SetConfigFile(in string)
func (v *Viper) SetConfigName(in string)
func (v *Viper) SetConfigPermissions(perm os.FileMode)
func (v *Viper) SetConfigType(in string)
func (v *Viper) SetDefault(key string, value any)
func (v *Viper) SetEnvKeyReplacer(r *strings.Replacer)
func (v *Viper) SetEnvPrefix(in string)
func (v *Viper) SetFs(fs afero.Fs)
func (v *Viper) SetTypeByDefaultValue(enable bool)
func (v *Viper) Sub(key string) *Viper
func (v *Viper) Unmarshal(rawVal any, opts ...DecoderConfigOption) error
func (v *Viper) UnmarshalExact(rawVal any, opts ...DecoderConfigOption) error
func (v *Viper) UnmarshalKey(key string, rawVal any, opts ...DecoderConfigOption) error
func (v *Viper) WatchConfig()
WatchConfig starts watching a config file for changes.
func (v *Viper) WatchRemoteConfig() error
func (v *Viper) WatchRemoteConfigOnChannel() error
func (v *Viper) WriteConfig() error
func (v *Viper) WriteConfigAs(filename string) error