README
¶
Dotenv 
Dotenv is a minimal Go Library for reading .env configuration files.
Dotenv reads config in the following order. Each item takes precedence over the item below it:
- env
- key-value config cache/store (loaded from the .env file or set explicitly)
- default (when using structures)
The config cache store is set on first read operation.
BenchmarkDotenv_Load-12 57186 19774 ns/op 17477 B/op 89 allocs/op
BenchmarkDotenv_instance/Get-12 30091465 39.93 ns/op 0 B/op 0 allocs/op
BenchmarkDotenv_instance/Get_NotExist-12 24608632 48.31 ns/op 0 B/op 0 allocs/op
BenchmarkDotenv_instance/Set-12 52317692 23.51 ns/op 0 B/op 0 allocs/op
BenchmarkDotenv_global/Get-12 25803398 46.73 ns/op 0 B/op 0 allocs/op
BenchmarkDotenv_global/Get_NotExist-12 20868642 59.51 ns/op 0 B/op 0 allocs/op
BenchmarkDotenv_global/Set-12 37934266 32.20 ns/op 0 B/op 0 allocs/op
Installation
go get -u github.com/profclems/go-dotenv
Usage
Assuming you have a .env file in the current directory with the following values
S3_BUCKET=yours3bucket
SECRET_KEY=yoursecretKey
PRIORITY_LEVEL=2
Then in your Go application, you can do something like this:
package main
import (
"log"
"github.com/profclems/go-dotenv"
)
func main() {
// .env - It will search for the .env file in the current directory and load it.
// You can explicitly set config file with dotenv.SetConfigFile("path/to/file.env")
err := dotenv.Load()
if err != nil {
log.Fatalf("Error loading .env file: %v", err)
}
s3Bucket := dotenv.GetString("S3_BUCKET")
secretKey := dotenv.GetString("SECRET_KEY")
priorityLevel := dotenv.GetInt("PRIORITY_LEVEL")
// now do something with s3 or whatever
}
Comments and exports are supported:
# This is a comment
S3_BUCKET=yours3bucket
SECRET_KEY=yoursecretKey # This is also a comment
export PRIORITY_LEVEL=2
All the above examples use the global DotEnv instance. You can instantiate a new Dotenv instance:
cfg := dotenv.New()
cfg.SetConfigFile("path/to/.env")
err := cfg.Load()
if err != nil {
log.Fatalf("Error loading .env file: %v", err)
}
val := cfg.GetString("SOME_ENV")
Getting Values From DotEnv
The following functions and methods exist to get a value depending the Type:
Get(key string) : anyGetString(key string) : stringGetBool(key string) : boolGetFloat64(key string) : float64GetInt(key string) : intGetIntSlice(key string) : []intGetStringSlice(key string) : []stringGetTime(key string) : time.TimeGetDuration(key string) : time.DurationisSet(key string) : boolLookUp(key string) : (any, bool)Set(key string, value any)
Contributing
Contributions are most welcome! It could be a new feature, bug fix, refactoring or even reporting an issue.
- Fork it
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Added some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request
License
Copyright © Clement Sam
This package is open-sourced software licensed under the MIT license.
Documentation
¶
Index ¶
- Constants
- func AllowEmptyEnv(allowEmptyEnvVars bool)
- func Get(key string) any
- func GetBool(key string) bool
- func GetDuration(key string) time.Duration
- func GetFloat64(key string) float64
- func GetInt(key string) int
- func GetInt32(key string) int32
- func GetInt64(key string) int64
- func GetIntSlice(key string) []int
- func GetPrefix() string
- func GetSizeInBytes(key string) uint
- func GetString(key string) string
- func GetStringSlice(key string) []string
- func GetTime(key string) time.Time
- func GetUint(key string) uint
- func GetUint32(key string) uint32
- func GetUint64(key string) uint64
- func IsSet(key string) bool
- func Load() error
- func LoadWithDecoder(decoder Decoder) error
- func LookUp(key string) (any, bool)
- func ReplaceDefault(env *DotEnv) func()
- func Save() errordeprecated
- func Set(key string, value any)
- func SetConfigFile(configFile string)
- func SetPrefix(prefix string)
- func UnMarshal(v any) error
- func Write(key string, value any) error
- func WriteFile(filename string, data []byte, perm os.FileMode) error
- type Decoder
- type DefaultDecoder
- type DotEnv
- func (e *DotEnv) AllowEmptyEnvVars(allowEmptyEnvVars bool)
- func (e *DotEnv) Get(key string) any
- func (e *DotEnv) GetBool(key string) bool
- func (e *DotEnv) GetDuration(key string) time.Duration
- func (e *DotEnv) GetFloat64(key string) float64
- func (e *DotEnv) GetInt(key string) int
- func (e *DotEnv) GetInt32(key string) int32
- func (e *DotEnv) GetInt64(key string) int64
- func (e *DotEnv) GetIntSlice(key string) []int
- func (e *DotEnv) GetPrefix() string
- func (e *DotEnv) GetSizeInBytes(key string) uint
- func (e *DotEnv) GetString(key string) string
- func (e *DotEnv) GetStringSlice(key string) []string
- func (e *DotEnv) GetTime(key string) time.Time
- func (e *DotEnv) GetUint(key string) uint
- func (e *DotEnv) GetUint32(key string) uint32
- func (e *DotEnv) GetUint64(key string) uint64
- func (e *DotEnv) IsSet(key string) bool
- func (e *DotEnv) Load() error
- func (e *DotEnv) LoadWithDecoder(decoder Decoder) error
- func (e *DotEnv) LookUp(key string) (any, bool)
- func (e *DotEnv) Save() errordeprecated
- func (e *DotEnv) Set(key string, value any)
- func (e *DotEnv) SetConfigFile(configFile string)
- func (e *DotEnv) SetPrefix(prefix string)
- func (e *DotEnv) Unmarshal(v any) (err error)
- func (e *DotEnv) Write(key string, value any) error
Constants ¶
const (
// DefaultConfigFile is the default name of the configuration file.
DefaultConfigFile = ".env"
)
Variables ¶
This section is empty.
Functions ¶
func AllowEmptyEnv ¶
func AllowEmptyEnv(allowEmptyEnvVars bool)
AllowEmptyEnv tells Dotenv to consider set, but empty environment variables as valid values instead of falling back to config value. This is set to true by default.
func Get ¶
Get can retrieve any value given the key to use. Get is case-insensitive for a key. Dotenv will check in the following order: configOverride cache, env, key/value store, config file
Get returns an interface. For a specific value use one of the Get___ methods e.g. GetBool(key) for a boolean value
func GetDuration ¶
GetDuration returns the value associated with the key as a duration.
func GetFloat64 ¶
GetFloat64 returns the value associated with the key as a float64.
func GetIntSlice ¶
GetIntSlice returns the value associated with the key as a slice of int values.
func GetPrefix ¶
func GetPrefix() string
GetPrefix returns the prefix that ENVIRONMENT variables will use which is set with SetPrefix.
func GetSizeInBytes ¶
GetSizeInBytes returns the size of the value associated with the given key in bytes.
func GetStringSlice ¶
GetStringSlice returns the value associated with the key as a slice of strings.
func IsSet ¶
IsSet checks to see if the key has been set in any of the env var, config cache or config file. IsSet is case-insensitive for a key.
func Load ¶ added in v1.0.0
func Load() error
Load finds and read the config file. returns os.ErrNotExist if config file does not exist. This loads the .env file from the current directory by default, use SetConfigFile to set a custom path before calling this.
func LoadWithDecoder ¶ added in v1.0.0
LoadWithDecoder finds and read the config file using the provided decoder. returns os.ErrNotExist if config file does not exist. This loads the .env file from the current directory by default, use SetConfigFile to set a custom path before calling this.
func LookUp ¶
LookUp retrieves the value of the configuration named by the key. If the variable is set (which may be empty) is returned and the boolean is true. Otherwise the returned value will be empty and the boolean will be false.
func ReplaceDefault ¶ added in v1.1.0
func ReplaceDefault(env *DotEnv) func()
ReplaceDefault replaces the default DotEnv instance with a new one and returns a function to restore the previous instance. This is useful for customizing the default DotEnv instance. It's safe for concurrent use.
func Set ¶
Set sets or update env variable This will be used instead of following the normal precedence when getting the value
func SetConfigFile ¶
func SetConfigFile(configFile string)
SetConfigFile explicitly defines the path, name and extension of the config file. Dotenv will use this and not check .env from the current directory.
func SetPrefix ¶
func SetPrefix(prefix string)
SetPrefix defines a prefix that ENVIRONMENT variables will use. E.g. if your prefix is "pro", the env registry will look for env variables that start with "PRO_".
func UnMarshal ¶ added in v1.0.0
UnMarshal unmarshals the config file into a struct. Recognizes the following struct tags:
- env:"KEY" to specify the key name to look up in the config file
- default:"value" to specify a default value if the key is not found
Types ¶
type DefaultDecoder ¶ added in v1.0.0
type DefaultDecoder struct {
// contains filtered or unexported fields
}
DefaultDecoder is the default decoder used by the library.
type DotEnv ¶
type DotEnv struct {
// contains filtered or unexported fields
}
DotEnv is a prioritized .env 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. env. variables 2. key/value cache/store (loaded from config file or set explicitly with Set()) 3. defaults(when using structures)
For example, if values from the following sources were loaded:
Defaults USER=default ENDPOINT=https://localhost Config USER=root SECRET=secretFromConfig Environment SECRET=secretFromEnv
The resulting config will have the following values:
SECRET=secretFromEnv USER=root ENDPOINT=https://localhost
DotEnv is safe for concurrent Get___() and Set() operations by multiple goroutines.
func GetDotEnv ¶
func GetDotEnv() *DotEnv
GetDotEnv returns the global DotEnv instance which can reconfigured with ReplaceDefault. It's safe for concurrent use.
func New ¶ added in v1.0.0
func New() *DotEnv
New returns an initialized DotEnv instance. This does not load the config file. You call Load() to do that.
Source Files
Directories