• Stars
    star
    241
  • Rank 167,609 (Top 4 %)
  • Language
    Go
  • License
    MIT License
  • Created over 9 years ago
  • Updated about 3 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Small library to read your configuration from environment variables

envconfig

CI Go Reference

envconfig is a library which allows you to parse your configuration from environment variables and fill an arbitrary struct.

See the example to understand how to use it, it's pretty simple.

Supported types

  • Almost all standard types plus time.Duration are supported by default.
  • Slices and arrays
  • Arbitrary structs
  • Custom types via the Unmarshaler interface.

How does it work

envconfig takes the hierarchy of your configuration struct and the names of the fields to create a environment variable key.

For example:

var conf struct {
    Name string
    Shard struct {
        Host string
        Port int
    }
}

This will check for those 3 keys:

  • NAME or name
  • SHARD_HOST, or shard_host
  • SHARD_PORT, or shard_port

Flexible key naming

envconfig supports having underscores in the key names where there is a word boundary. Now, that term is not super explicit, so let me show you an example:

var conf struct {
    Cassandra struct {
        SSLCert string
        SslKey string
    }
}

This will check all of the following keys:

  • CASSANDRA_SSL_CERT, CASSANDRA_SSLCERT, cassandra_ssl_cert, cassandra_sslcert
  • CASSANDRA_SSL_KEY, CASSANDRA_SSLKEY, cassandra_ssl_key, cassandra_sslkey

If that is not good enough, look just below.

Custom environment variable names

envconfig supports custom environment variable names:

var conf struct {
    Name string `envconfig:"myName"`
}

Default values

envconfig supports default values:

var conf struct {
    Name string `envconfig:"default=Vincent"`
}

Optional values

envconfig supports optional values:

var conf struct {
    Name string `envconfig:"optional"`
}

Skipping fields

envconfig supports skipping struct fields:

var conf struct {
    Internal string `envconfig:"-"`
}

Combining multiple options in one tag

You can of course combine multiple options:

var conf struct {
    Name string `envconfig:"default=Vincent,myName"`
}

Slices or arrays

With slices or arrays, the same naming is applied for the slice. To put multiple elements into the slice or array, you need to separate them with a , (will probably be configurable in the future, or at least have a way to escape)

For example:

var conf struct {
    Ports []int
}

This will check for the key PORTS:

  • if your variable is 9000 the slice will contain only 9000
  • if your variable is 9000,100 the slice will contain 9000 and 100

For slices of structs, it's a little more complicated. The same splitting of slice elements is done with a comma, however, each token must follow a specific format like this: {<first field>,<second field>,...}

For example:

var conf struct {
    Shards []struct {
        Name string
        Port int
    }
}

This will check for the key SHARDS. Example variable content: {foobar,9000},{barbaz,20000}

This will result in two struct defined in the Shards slice.

If you want to set default value for slice or array, you have to use ; as separator, instead of ,:

var conf struct {
    Ports []int `envconfig:"default=9000;100"`
}

Same for slices of structs:

var conf struct {
    Shards []struct {
        Name string
        Port int
    } `envconfig:"default={foobar;localhost:2929};{barbaz;localhost:2828}"`
}

Development state

I consider envconfig to be pretty much done.

It has been used extensively at Batch for more than 5 years now without much problems, with no need for new features either.

So, while I will keep maintaining this library (fixing bugs, making it compatible with new versions of Go and so on) for the foreseeable future, I don't plan on adding new features.

But I'm open to discussion so if you have a need for a particular feature we can discuss it.

More Repositories

1

zig-sqlite

zig-sqlite is a small wrapper around sqlite's C API, making it easier to use with Zig.
C
367
star
2

tree-sitter-templ

JavaScript
76
star
3

go-metrics-influxdb

This is a reporter for the go-metrics library which will post the metrics to InfluxDB
Go
69
star
4

zig-prometheus

Prometheus/VictoriaMetrics client library for Zig
Zig
49
star
5

ansible-role-java

Ansible role to install the Oracle JDK/JRE
48
star
6

zig-io_uring-http-server

Zig
42
star
7

rdbtools

A Redis RDB parser
Go
24
star
8

userdir

Go package to get user directories
Go
15
star
9

logfmt

Library and tools to work with logfmt (see https://brandur.org/logfmt)
Go
12
star
10

naspm

Simple power management for my NAS.
Go
10
star
11

zig-cassandra

Cassandra CQL client
Zig
6
star
12

zig-sqlite-vtab-demo

Demo of building virtual tables for SQLite using `zig-sqlite`
Zig
4
star
13

zig-sqlite-demo

Basic demo of zig-sqlite
Zig
4
star
14

koff

koff is a small tool to get information about Kafka offsets.
Go
4
star
15

kcm

Create, launch and remove local Kafka clusters for development and testing
Go
4
star
16

jsonutil

collection of types implementing json.Marshaler and json.Unmarshaler
Go
4
star
17

zig-async_io_uring

Zig
4
star
18

zik

Music library explorer
Zig
2
star
19

hutil

set of helpers to work with net/http
Go
2
star
20

ansible-restic

Role to deploy restic using systemd services and timers
Jinja
1
star
21

beancount-importers

Beancount importer for Fortuneo CSV exports
Python
1
star
22

bip39-java

Partial implementation of BIP-0039 for Java
Java
1
star
23

cassandra-partition-calculator

Calculate the size of a Cassandra partition
Go
1
star
24

flagutil

Collection of custom types implementing flag.Value
Go
1
star
25

zig-hyperscan

Zig
1
star
26

vmscraper

Prometheus scraper which exclusively exports to Victoria Metrics
Go
1
star
27

zig-sqlite-builder

Zig
1
star
28

gitjuggling

Rust
1
star