Variables¶

Store sensitive information like passwords and API keys without hardcoding them in your configuration files. Use environment variables, .env files, or configuration overrides to change settings dynamically.

Environment Variables¶

Vulcan accesses environment variables during configuration. Store secrets outside configuration files and change settings based on who's running Vulcan.

Using .env Files¶

Vulcan automatically loads environment variables from a .env file in your project directory:

# .env file
SNOWFLAKE_PW=my_secret_password
S3_BUCKET=s3://my-data-bucket/warehouse
DATABASE_URL=postgresql://user:pass@localhost/db

# Override Vulcan configuration values
VULCAN__DEFAULT_GATEWAY=production
VULCAN__MODEL_DEFAULTS__DIALECT=snowflake

Custom .env File Location¶

Specify a custom path using the --dotenv CLI flag:

vulcan --dotenv /path/to/custom/.env plan

Or set the VULCAN_DOTENV_PATH environment variable:

export VULCAN_DOTENV_PATH=/path/to/custom/.custom_env
vulcan plan

Accessing Variables in Configuration¶

1
2
3
4
5
6
7

gateways:
  my_gateway:
    connection:
      type: snowflake
      user: admin
      password: "{{ env_var('SNOWFLAKE_PW') }}"
      account: my_account

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import os
from vulcan.core.config import Config, GatewayConfig, SnowflakeConnectionConfig

config = Config(
    gateways={
        "my_gateway": GatewayConfig(
            connection=SnowflakeConnectionConfig(
                user="admin",
                password=os.environ['SNOWFLAKE_PW'],
                account="my_account",
            ),
        ),
    }
)

Configuration Overrides¶

Environment variables have the highest precedence. They override configuration file values if they follow the VULCAN__ naming convention.

Override Naming Structure¶

Use double underscores __ to navigate the configuration hierarchy:

VULCAN__<ROOT_KEY>__<NESTED_KEY>__<FIELD>=value

Example: Override a gateway connection password:

1
2
3
4
5
6

# config.yaml
gateways:
  my_gateway:
    connection:
      type: snowflake
      password: dummy_pw  # This will be overridden

# Override with environment variable
export VULCAN__GATEWAYS__MY_GATEWAY__CONNECTION__PASSWORD="real_pw"

Dynamic Configuration¶

User-based Target Environment¶

Use the {{ user() }} function to dynamically set configuration based on the current user:

# Each user gets their own dev environment
default_target_environment: dev_{{ user() }}

1
2
3
4
5
6

import getpass
from vulcan.core.config import Config

config = Config(
    default_target_environment=f"dev_{getpass.getuser()}",
)

This allows running vulcan plan instead of vulcan plan dev_username.