GoMaskData Factory
Documentation

Environment Variables

Use environment variables in GoMask CLI configurations

Environment Variables Guide

Learn how to use environment variables in your GoMask CLI configurations for flexible, secure deployments.

Overview

Environment variables enable you to:

  • Keep credentials out of version control
  • Configure routines for different environments
  • Parameterize configurations at runtime

Variable Substitution Syntax

Use these patterns in YAML files:

Simple Substitution

settings:
  localization_region: ${REGION}
  localization_language: ${LANGUAGE}

With Default Value

settings:
  batch_size: ${BATCH_SIZE:-1000}    # Use 1000 if BATCH_SIZE not set
  seed: ${SEED:-12345}               # Use 12345 if SEED not set

Required Variable (Error if Missing)

routine:
  connector_id: ${CONNECTOR_ID:?Connector ID is required}

If CONNECTOR_ID is not set, validation fails with the error message.

Loading Environment Variables

From .env Files

Create a .env file:

# .env
DB_HOST=production.example.com
DB_PORT=5432
DB_NAME=mydb
DB_USER=admin
DB_PASSWORD=secret123

Load with CLI:

gomask validate routine.yaml --env-file .env
gomask run routine.yaml --env-file .env

Environment-Specific Files

routines/
├── data-routine.yaml
├── .env.development
├── .env.staging
└── .env.production

# Development
gomask run routine.yaml --env-file .env.development

# Staging
gomask run routine.yaml --env-file .env.staging

# Production
gomask run routine.yaml --env-file .env.production

From Shell Environment

Set variables in your shell:

export DB_HOST=localhost
export DB_PASSWORD=secret
gomask run routine.yaml

Priority Order

Variables are resolved in this order (highest priority first):

  1. Command-line --param flags
  2. .env file (via --env-file)
  3. Shell environment variables
  4. Default values (from :- syntax)

Common Patterns

Environment-Aware Configuration

routine:
  name: "Data Routine (${ENVIRONMENT:-Development})"
  type: synthetic
  connector_id: ${CONNECTOR_ID:-1}

settings:
  batch_size: ${BATCH_SIZE:-1000}
  localization_region: ${REGION:-US}

Conditional Table Names

tables:
  - table_name: ${TABLE_PREFIX:-}users
    schema_name: ${SCHEMA:-public}

Record Counts

tables:
  - table_name: users
    target_record_count: ${USER_COUNT:-1000}
  - table_name: orders
    target_record_count: ${ORDER_COUNT:-5000}

Complete Example

YAML Configuration

routine:
  name: "Test Data (${ENVIRONMENT:-Development})"
  type: synthetic
  connector_id: ${CONNECTOR_ID:?Connector ID required}

settings:
  batch_size: ${BATCH_SIZE:-500}
  seed: ${SEED:-12345}
  localization_region: ${REGION:-US}

tables:
  - table_name: users
    schema_name: ${SCHEMA:-public}
    target_record_count: ${USER_COUNT:-1000}
    columns:
      - column_name: email
        generation_function: generate_email
        generation_parameters:
          - name: domain
            value: ${EMAIL_DOMAIN:-example.com}

Development .env

# .env.development
DB_HOST=localhost
DB_PORT=5432
DB_NAME=dev_db
DB_USER=dev_user
DB_PASSWORD=dev_password
ENVIRONMENT=development
RECORD_COUNT=100
EMAIL_DOMAIN=dev.example.com

Production .env

# .env.production
DB_HOST=prod.database.example.com
DB_PORT=5432
DB_NAME=prod_db
DB_USER=prod_user
DB_PASSWORD=${PROD_DB_SECRET}  # Reference another env var
ENVIRONMENT=production
RECORD_COUNT=10000
EMAIL_DOMAIN=company.com

Usage

# Development
gomask run routine.yaml --env-file .env.development

# Production
gomask run routine.yaml --env-file .env.production

CLI Configuration Variables

These environment variables configure the CLI itself:

VariableDescriptionDefault
GOMASK_SECRETAPI authentication secret-
GOMASK_API_URLAPI endpoint URLhttps://cli.gomask.ai/api/v1
GOMASK_DEBUGEnable debug modefalse
export GOMASK_SECRET="your-api-secret"
export GOMASK_DEBUG="true"
gomask connectors list  # No gomask.toml needed

Security Best Practices

1. Never Commit Secrets

Add to .gitignore:

# GoMask credentials
gomask.toml
.env
.env.*
!.env.example

2. Use .env.example for Documentation

Create a template without real values:

# .env.example
DB_HOST=your-database-host
DB_PORT=5432
DB_NAME=your-database-name
DB_USER=your-username
DB_PASSWORD=your-password

3. Use Required Variables for Critical Values

routine:
  connector_id: ${CONNECTOR_ID:?Connector ID must be set}

4. Separate Credentials by Environment

.env.development  # Local dev credentials
.env.staging      # Staging credentials
.env.production   # Production credentials (never commit!)

5. Use Secret Managers in Production

For CI/CD, use platform secret managers:

# GitHub Actions
run: gomask run routine.yaml
env:
  DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

Validation

Validate with environment variables:

# Check for missing required variables
gomask validate routine.yaml --env-file .env

# See resolved values
gomask validate routine.yaml --env-file .env --show-config

Common Validation Errors

Missing Required Variable:

Error: Environment variable DB_PASSWORD is required but not set
  Message: Database password required

Solution: Set the variable or provide a default:

password: ${DB_PASSWORD:-default_password}

Combining with Runtime Parameters

Environment variables and runtime parameters work together:

tables:
  - table_name: users
    target_record_count: ${DEFAULT_RECORD_COUNT:-1000}

# Uses default from env var
gomask run routine.yaml --env-file .env

# Override at runtime
gomask run routine.yaml --env-file .env --param RECORD_COUNT=5000

Debugging

Show Resolved Configuration

gomask validate routine.yaml --env-file .env --show-config

Check Variable Resolution

# Enable debug mode
export GOMASK_DEBUG=true
gomask validate routine.yaml --env-file .env

Next Steps

← CI/CD Integration
Function Reference →