Initialize config structure from environment variables in Rust without boilerplate.
[dependencies]
envconfig = "0.10.0"
Let's say you application relies on the following environment variables:
DB_HOST
DB_PORT
And you want to initialize Config
structure like this one:
struct Config {
db_host: String,
db_port: u16,
}
You can achieve this with the following code without boilerplate:
use envconfig::Envconfig;
#[derive(Envconfig)]
pub struct Config {
#[envconfig(from = "DB_HOST")]
pub db_host: String,
#[envconfig(from = "DB_PORT", default = "5432")]
pub db_port: u16,
}
fn main() {
// Assuming the following environment variables are set
std::env::set_var("DB_HOST", "127.0.0.1");
// Initialize config from environment variables or terminate the process.
let config = Config::init_from_env().unwrap();
assert_eq!(config.db_host, "127.0.0.1");
assert_eq!(config.db_port, 5432);
}
Configs can be nested. Just add #[envconfig(nested = true)]
to nested field.
#[derive(Envconfig)]
pub struct DbConfig {
#[envconfig(from = "DB_HOST")]
pub host: String,
#[envconfig(from = "DB_PORT", default = "5432")]
pub port: u16,
}
#[derive(Envconfig)]
pub struct Config {
#[envconfig(nested = true)] // <---
db: DbConfig,
#[envconfig(from = "HOSTNAME")]
hostname: String,
}
Under the hood envconfig relies on FromStr
trait.
If you want to use a custom type as a field for config, you have to implement FromStr
trait for your custom type.
Let's say we want to extend DbConfig
with driver
field, which is DbDriver
enum that represents either Postgresql
or Mysql
:
pub enum DbDriver {
Postgresql,
Mysql,
}
impl std::str::FromStr for DbDriver {
type Err = String;
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s.trim().to_lowercase().as_ref() {
"postgres" => Ok(DbDriver::Postgresql),
"mysql" => Ok(DbDriver::Mysql),
_ => Err(format!("Unknown DB driver: {s}"))
}
}
}
#[derive(Envconfig)]
pub struct DbConfig {
// ...
#[envconfig(from = "DB_DRIVER")]
pub driver: DbDriver,
}
If this seems too cumbersome, consider using other crates like strum to derive FromStr
automatically.
use strum::EnumString;
#[derive(EnumString)]
pub enum DbDriver {
Postgresql,
Mysql,
}
When writing tests you should avoid using environment variables. Cargo runs Rust tests in parallel by default which means you can end up with race conditions in your tests if two or more are fighting over an environment variable.
To solve this you can initialise your struct
from a HashMap<String, String>
in your tests. The HashMap
should
match what you expect the real environment variables to be; for example DB_HOST
environment variable becomes a
DB_HOST
key in your HashMap
.
use envconfig::Envconfig;
#[derive(Envconfig)]
pub struct Config {
#[envconfig(from = "DB_HOST")]
pub db_host: String,
#[envconfig(from = "DB_PORT", default = "5432")]
pub db_port: u16,
}
#[test]
fn test_config_can_be_loaded_from_hashmap() {
// Create a HashMap that looks like your environment
let mut hashmap = HashMap::new();
hashmap.insert("DB_HOST".to_string(), "127.0.0.1".to_string());
// Initialize config from a HashMap to avoid test race conditions
let config = Config::init_from_hashmap(&hashmap).unwrap();
assert_eq!(config.db_host, "127.0.0.1");
assert_eq!(config.db_port, 5432);
}
Tests do some manipulation with environment variables, so to prevent flaky tests they have to be executed in a single thread:
cargo test -- --test-threads=1