required_env Reference

The required_env field on connections declares which environment variables are required for that connection. It provides three capabilities: pre-flight validation, .env auto-loading, and variable injection into connection.params.

Schema

Property

Type

Default

Description

required_env

list[string]

null

List of environment variable names required by this connection

The field is accepted on all connection types: api, custom, db, csv, and veza_api.

connections:
  my_api:
    connection_type: custom
    custom_module: modules.myapp
    required_env:                    # optional list of env var names
      - MY_API_KEY
      - MY_API_SECRET
    params:
      base_url: https://api.example.com

Behavior

1. Validation

Before each run, oaa-runner validates that every variable in required_env is present in the environment. VEZA_URL and VEZA_API_KEY are always implicitly required — they are checked even if required_env is not set.

If any required variable is missing, the run fails immediately with an error naming the variable and the connection that declared it. Variable names appear in error messages; variable values are never logged.

Validation runs in two places:

  • oaa app validate — Step 2 of the validation output

  • oaa app run — Registered as a @preflight check before data is fetched

2. Auto-loading .env

When required_env is present, oaa-runner loads the .env file from the same directory as the config.yaml file. This happens before validation, so variables defined in .env satisfy the check.

The .env path is resolved relative to the config file directory, not the current working directory.

3. Injection into connection.params

After .env is loaded and validation passes, the values of all variables listed in required_env are injected into the connection’s params dict. This means integration code can access secrets directly:

def fetch(connection=None, source=None, **kwargs):
    api_key = connection.params['MY_API_KEY']

Without required_env, integration code must call params_or_env() or os.getenv():

from oaa.modules.params_or_env import params_or_env
api_key = params_or_env(connection, source, 'MY_API_KEY')

Existing params values are preserved. When the same key exists in both params and the environment, the environment value takes precedence.

What It Does NOT Do

  • required_env does not set default values — if a variable is unset, the run fails

  • required_env does not replace !env for DB connections — both mechanisms coexist

  • required_env does not log or print variable values — only names appear in errors

  • Empty strings count as “set” — only completely unset variables fail validation

Implicit Variables

These variables are always required (checked even without required_env):

Variable

Purpose

VEZA_URL

Base URL of the Veza instance

VEZA_API_KEY

API key for Veza authentication

They do not need to be listed in required_env.

See Also