Core Configuration Variables

Environment variables for basic MSR configuration including migration file discovery, tracking, and execution.

Table of Contents

  1. Overview
  2. Variables
    1. MSR_FOLDER
    2. MSR_TABLE_NAME
    3. MSR_BEFORE_MIGRATE_NAME
    4. MSR_DRY_RUN
    5. MSR_DISPLAY_LIMIT
    6. MSR_SHOW_BANNER
    7. MSR_LOG_LEVEL
    8. MSR_RECURSIVE
    9. MSR_FILE_PATTERNS
    10. MSR_CONFIG_FILE
  3. Complete Example
  4. Source Code

Overview

Core environment variables control the fundamental behavior of Migration Script Runner:

  • Where to find migration files
  • How to track schema versions
  • Migration execution modes
  • File discovery patterns

Variables

MSR_FOLDER

Migration files directory

  • Type: string
  • Default: ./migrations
  • Example: ./database/migrations, /app/migrations

Specifies the directory containing migration files. Can be relative or absolute path.

export MSR_FOLDER=./database/migrations

Programmatic Equivalent:

config.folder = './database/migrations';

See Also:

MSR_TABLE_NAME

Schema version tracking table name

  • Type: string
  • Default: schema_version
  • Example: migration_history, db_migrations

Name of the database table used to track executed migrations and schema versions.

export MSR_TABLE_NAME=migration_history

Programmatic Equivalent:

config.tableName = 'migration_history';

See Also:

MSR_BEFORE_MIGRATE_NAME

Setup function name

  • Type: string
  • Default: beforeMigrate
  • Example: setup, init, prepare

Name of the optional setup function that runs once before migrations execute.

export MSR_BEFORE_MIGRATE_NAME=setup

Programmatic Equivalent:

config.beforeMigrateName = 'setup';

Usage in Migration:

export async function setup(db: IDB): Promise<void> {
  // One-time setup logic
  await db.query('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"');
}

export async function up(db: IDB): Promise<void> {
  // Migration logic
}

See Also:

MSR_DRY_RUN

Test migrations without committing

  • Type: boolean
  • Default: false
  • Example: true, false

When enabled, migrations run in transactions but are rolled back instead of committed. Perfect for testing migrations safely.

export MSR_DRY_RUN=true

Programmatic Equivalent:

config.dryRun = true;

Use Cases:

  • Test migrations before production deployment
  • Verify migration scripts in CI/CD
  • Debug migration issues without affecting database

See Also:

MSR_DISPLAY_LIMIT

Limit displayed migrations

  • Type: number
  • Default: 0 (show all)
  • Example: 10, 20, 50

Maximum number of migrations to display in output. Use 0 to show all migrations.

export MSR_DISPLAY_LIMIT=20

Programmatic Equivalent:

config.displayLimit = 20;

See Also:

MSR_SHOW_BANNER

Display banner with version information

  • Type: boolean
  • Default: true
  • Example: true, false

Controls whether the application banner (ASCII art with version and handler information) is displayed at startup.

# Show banner (default)
export MSR_SHOW_BANNER=true

# Hide banner for cleaner output
export MSR_SHOW_BANNER=false

Programmatic Equivalent:

config.showBanner = false;

Use Cases:

  • true (default): Discoverable version and handler info for new users
  • false: Cleaner console output in CI/CD pipelines or when embedding MSR

When to Disable:

  • CI/CD environments where logs need to be concise
  • When embedding MSR as a library in other tools
  • Docker containers with centralized logging
  • Automated testing scenarios

See Also:

MSR_LOG_LEVEL

Log output verbosity level

  • Type: 'error' | 'warn' | 'info' | 'debug'
  • Default: 'info'
  • Example: error, warn, info, debug

Controls the verbosity of log output during migration execution. Each level includes all higher priority levels.

# Production: Only errors (highest priority)
export MSR_LOG_LEVEL=error

# Warnings and errors
export MSR_LOG_LEVEL=warn

# Normal operation (default): info, warnings, and errors
export MSR_LOG_LEVEL=info

# Debugging: All logs including detailed debug information
export MSR_LOG_LEVEL=debug

Programmatic Equivalent:

config.logLevel = 'debug';

Log Level Hierarchy:

Level Shows Use Case
error Errors only Production environments - critical issues only
warn Warnings + Errors Production with monitoring - catch potential issues
info Info + Warnings + Errors Default - standard operation visibility
debug All logs Development/troubleshooting - detailed execution flow

Use Cases:

  • error: Production deployments where only failures need attention
  • warn: Production with alerting on warnings and errors
  • info (default): Development and staging for visibility into migrations
  • debug: Troubleshooting migration issues or developing new features

Example Output by Level:

// With logLevel='error': Only critical failures shown
logger.error('Migration failed: V001_create_users.ts'); // ✅ Shown
logger.warn('Table already exists, skipping');         // ❌ Hidden
logger.info('Executing migration V001...');            // ❌ Hidden
logger.debug('Query: CREATE TABLE users...');          // ❌ Hidden

// With logLevel='info': Normal operation visibility
logger.error('Migration failed: V001_create_users.ts'); // ✅ Shown
logger.warn('Table already exists, skipping');         // ✅ Shown
logger.info('Executing migration V001...');            // ✅ Shown
logger.debug('Query: CREATE TABLE users...');          // ❌ Hidden

Invalid Values:

If an invalid log level is provided, MSR will display a warning and use the default 'info' level:

export MSR_LOG_LEVEL=verbose  # Invalid - will warn and use 'info'
# Warning: Invalid MSR_LOG_LEVEL value: 'verbose'. Valid values are: error, warn, info, debug. Using default 'info'.

See Also:

MSR_RECURSIVE

Scan subdirectories recursively

  • Type: boolean
  • Default: true
  • Example: true, false

Controls whether MSR scans subdirectories for migration files or only the top-level folder.

# Scan subdirectories (default)
export MSR_RECURSIVE=true

# Only scan top-level folder
export MSR_RECURSIVE=false

Programmatic Equivalent:

config.recursive = true;

Use Cases:

  • true (default): Organize migrations in subdirectories by module/feature
  • false: Flat structure with all migrations in one folder

Directory Structure Example:

migrations/
  ├── users/
  │   ├── V001_create_users.ts
  │   └── V002_add_email_index.ts
  ├── products/
  │   └── V003_create_products.ts
  └── orders/
      └── V004_create_orders.ts

See Also:

MSR_FILE_PATTERNS

Migration filename patterns

  • Type: string[] (JSON array of regex patterns)
  • Default: ["/^V(\\d{12})_/"]
  • Example: ["/^V(\\d+)_/", "/^M(\\d+)_/"]

Regular expression patterns for discovering migration files. Patterns must capture version number in first group.

# Single pattern (default)
export MSR_FILE_PATTERNS='["/^V(\\d{12})_/"]'

# Multiple patterns
export MSR_FILE_PATTERNS='["/^V(\\d+)_/", "/^M(\\d+)_/"]'

Programmatic Equivalent:

config.filePatterns = [/^V(\d+)_/, /^M(\d+)_/];

Pattern Requirements:

  • Must be valid JavaScript regex
  • First capturing group (\d+) must extract version number
  • Patterns are tested against filename only, not full path

Example Patterns:

Pattern Matches Version Captured
/^V(\d{12})_/ V202401151030_create_users.ts 202401151030
/^V(\d+)_/ V001_create_users.ts 001
/^(\d+)_/ 001_create_users.ts 001
/^M_(\d+)_/ M_001_migration.ts 001

See Also:

MSR_CONFIG_FILE

Path to configuration file

  • Type: string
  • Default: Auto-detected (msr.config.js, msr.config.json)
  • Example: ./config/msr.config.js, /app/msr-config.json

Override automatic config file detection with explicit path.

export MSR_CONFIG_FILE=./config/custom-msr.config.js

Programmatic Equivalent:

const config = ConfigLoader.loadFromFile('./config/custom-msr.config.js');

Auto-Detection Order:

  1. msr.config.js in current directory
  2. msr.config.json in current directory
  3. No config file (use defaults)

See Also:

Complete Example

Production-ready core configuration:

# Migration discovery
export MSR_FOLDER=/app/database/migrations
export MSR_RECURSIVE=true
export MSR_FILE_PATTERNS='["/^V(\\d{12})_/"]'

# Schema tracking
export MSR_TABLE_NAME=migration_history
export MSR_BEFORE_MIGRATE_NAME=beforeMigrate

# Display settings
export MSR_DISPLAY_LIMIT=20
export MSR_SHOW_BANNER=true
export MSR_LOG_LEVEL=info  # or: error, warn, debug

# Testing (CI/CD only)
export MSR_DRY_RUN=${CI:-false}

Source Code

TypeScript enum definition: src/model/env/CoreEnvVars.ts