GoMaskData Factory
Documentation

gomask run

Execute a routine from YAML configuration

gomask run

Execute a routine from YAML configuration.

Synopsis

gomask run YAML_FILE [OPTIONS]

Description

The run command executes a routine defined in a YAML configuration file. It:

  1. Validates the YAML configuration
  2. Imports/updates the routine in GoMask
  3. Triggers routine execution
  4. Optionally monitors progress in real-time

This is the primary command for running data generation or masking operations.

Arguments

ArgumentRequiredDescription
YAML_FILEYesPath to the YAML configuration file

Options

OptionTypeDefaultDescription
--watch, -wflagfalseWatch execution progress in real-time with live updates
--param, -p KEY=VALUEstringnoneOverride runtime parameters (can be specified multiple times)
--env-file PATHpathnonePath to a .env file for variable substitution
--dry-runflagfalseShow execution plan without actually running
--timeout SECONDSinteger3600Maximum execution time in seconds (1 hour default)

Examples

Basic Execution

gomask run routine.yaml

Output:

Validating routine.yaml...
✓ Validation passed

Starting execution...
✓ Execution started

Execution ID: exec-789
Status: running

Use --watch to monitor progress, or check status with:
  gomask executions show exec-789

Watch Progress in Real-Time

gomask run routine.yaml --watch

Output:

Validating routine.yaml...
✓ Validation passed

Starting execution...
✓ Execution started (ID: exec-789)

Progress:
┌─────────────────┬──────────┬─────────┬──────────┐
│ Table           │ Records  │ Status  │ Progress │
├─────────────────┼──────────┼─────────┼──────────┤
│ users           │ 500/500  │ ✓ done  │ ████████ │
│ orders          │ 342/1000 │ running │ ███░░░░░ │
│ products        │ 0/200    │ pending │ ░░░░░░░░ │
│ order_items     │ 0/2500   │ pending │ ░░░░░░░░ │
└─────────────────┴──────────┴─────────┴──────────┘

Elapsed: 00:01:23  |  ETA: 00:02:45

Override Parameters

gomask run routine.yaml --param record_count=5000 --param start_date=2024-01-01

Multiple Parameter Overrides

gomask run routine.yaml \
  -p RECORD_COUNT=100 \
  -p ENVIRONMENT=staging \
  -p SEED=12345

Dry Run (Preview)

gomask run routine.yaml --dry-run

Output:

DRY RUN - No changes will be made

Execution Plan:
───────────────
Routine: Customer Data Generator
Type: synthetic

Tables (execution order):
  1. users (500 records)
     - 12 columns configured
     - Hierarchy level: 0

  2. orders (1000 records)
     - 8 columns configured
     - Hierarchy level: 1
     - References: users.id

  3. products (200 records)
     - 15 columns configured
     - Hierarchy level: 0

  4. order_items (2500 records)
     - 6 columns configured
     - Hierarchy level: 2
     - References: orders.id, products.id

Estimated records: 4,200 total

With Environment Variables

gomask run routine.yaml --env-file production.env --watch

Set Execution Timeout

gomask run routine.yaml --timeout 7200 --watch  # 2 hour timeout

Execution Lifecycle

┌─────────┐    ┌──────────┐    ┌─────────┐    ┌───────────┐
│ pending │ -> │ starting │ -> │ running │ -> │ completed │
└─────────┘    └──────────┘    └─────────┘    └───────────┘
                                   │
                                   v
                              ┌─────────┐
                              │ failed  │
                              └─────────┘

Status Descriptions

StatusDescription
pendingExecution queued, waiting to start
startingInitializing execution environment
runningActively generating/masking data
completedSuccessfully finished
failedError occurred during execution
cancelledManually cancelled by user

Watch Mode Features

When using --watch:

  • Live progress: Table-by-table progress updates
  • ETA calculation: Estimated time to completion
  • Error display: Immediate error notification
  • Auto-refresh: Updates every 2 seconds
  • Exit on completion: Returns when execution finishes

Press Ctrl+C to stop watching (execution continues in background).

Runtime Parameters

Override parameters defined in the YAML's settings.runtime_parameter_definitions section:

settings:
  runtime_parameter_definitions:
    - key: "param_record_count"
      name: "record_count"
      type: integer
      defaultValue: 1000
      description: "Number of records per table"

    - key: "param_start_date"
      name: "start_date"
      type: string
      defaultValue: "2024-01-01"
      description: "Start date for date ranges"

Override at runtime:

gomask run routine.yaml -p record_count=5000 -p start_date=2023-01-01

Exit Codes

CodeDescription
0Execution completed successfully
1Execution failed or error occurred
130Interrupted by user (Ctrl+C during --watch)

Common Errors

Validation Failed

Error: Validation failed
  - Unknown function 'fake_emal' at tables[0].columns[2]

Solution: Fix the YAML configuration and retry.

Execution Timeout

Error: Execution timed out after 3600 seconds

Solutions:

  • Increase timeout with --timeout
  • Reduce record counts
  • Split into multiple routines

Connector Error

Error: Failed to connect to database
  Connection refused: localhost:5432

Solutions:

  • Verify database is running
  • Check connector configuration
  • Test with gomask connectors test

Best Practices

  1. Always use --watch for first runs: See immediate feedback on errors
  2. Start with small counts: Test with low record counts first
  3. Use dry-run: Preview execution plan before running
  4. Monitor long runs: Use gomask executions logs for detailed logging
  5. Set appropriate timeouts: Adjust based on data volume

Checking Execution Status

If you don't use --watch, check status later:

# Show execution status
gomask executions show exec-789

# View logs
gomask executions logs exec-789

# Follow logs in real-time
gomask executions logs exec-789 --follow

See Also

← export
connectors →