Configuration

Configure MigrationPilot with a YAML config file or package.json.

Config File Locations

MigrationPilot searches for config files in priority order, walking up from the current directory:

.migrationpilotrc.yml      # highest priority
.migrationpilotrc.yaml
migrationpilot.config.yml
migrationpilot.config.yaml
package.json               # "migrationpilot" key

Generate a Config File

Use the init command to generate a default configuration file:

migrationpilot init

Full Configuration Reference

Here is a complete configuration file with all available options:

# .migrationpilotrc.yml

# Extend a built-in preset: recommended, strict, ci, startup, enterprise
extends: "migrationpilot:recommended"

# Target PostgreSQL version (9-20)
pgVersion: 17

# Fail CI on severity level: critical, warning, never
failOn: critical

# Default migration file pattern
migrationPath: "migrations/**/*.sql"

# Per-rule configuration
rules:
  MP001: true                    # enable (default)
  MP037: false                   # disable a rule
  MP004:
    severity: warning            # downgrade from critical
  MP013:
    threshold: 5000              # custom threshold (default: 10000)
  MP014:
    threshold: 500000            # custom threshold (default: 1000000)

# Production context thresholds
thresholds:
  highTrafficQueries: 10000      # MP013: min query count
  largeTableRows: 1000000        # MP014: min row count
  redScore: 50                   # Risk score for RED
  yellowScore: 25                # Risk score for YELLOW

# Files to ignore (glob patterns)
ignore:
  - "migrations/seed_*.sql"
  - "migrations/test_*.sql"

# Org plan: these two apply only with an Org license key
# (--license-key or MIGRATIONPILOT_LICENSE_KEY). Without one,
# the run warns and skips them.
auditLog:
  enabled: true
  path: ./migrationpilot-audit.jsonl

policy:
  requiredRules: [MP001, MP004]   # run whatever rules:, --exclude or a comment says
  severityFloor: critical         # a critical rule can't be turned into a warning
  blockedPatterns: ["DROP TABLE", "TRUNCATE"]   # fail the run, whatever --fail-on says
  requireReviewPatterns: ["ALTER TYPE"]         # flagged for team review

Built-in Presets

MigrationPilot includes five presets you can extend. "recommended" uses default settings with failOn: critical. "strict" promotes all rules to critical severity and fails on warnings. "ci" is optimized for CI with failOn: critical and no ignore patterns. "startup" disables nitpicky rules for early-stage teams. "enterprise" enables maximum safety and turns on the audit log, which needs an Org plan license key.

# Use the strict preset
extends: "migrationpilot:strict"

# Override individual rules from the preset
rules:
  MP037: false   # disable in strict mode

Inline Disable Comments

Disable specific rules for individual statements with SQL comments. A rule your Org policy requires stays on whatever the comment says.

-- migrationpilot-disable MP001
CREATE INDEX idx_users_email ON users (email);

-- migrationpilot-disable MP001,MP004
ALTER TABLE orders ADD COLUMN status text;

Organization Policy (Org plan)

The policy block sets rules a team can't loosen from its own branch. With an Org license key, analyze, check, precommit and the GitHub Action apply it, and watch, plan, simulate and mutation-test keep the required rules on and hold the floor. Required rules run even when rules:, a preset, --exclude or a disable comment turns them off, and the run prints a note each time it overrides one. The severity floor stops a rule from being set below it, though a rule that ships as a warning stays a warning. A statement matching a blocked pattern fails the run with exit code 2, whatever --fail-on says. Patterns match whole words, ignore case and whitespace, and skip comments. Review patterns are reported but don't fail anything. With a policy block and no valid key, every run says the policy isn't applied, so a missing secret can't pass for a clean result. The --no-config flag skips the config file and the policy with it, so enforce from CI, where the config is reviewed like code. migrationpilot policy <file> lists everything the policy overrides in a file.

# .migrationpilotrc.yml
policy:
  requiredRules: [MP001, MP004]
  severityFloor: critical
  blockedPatterns: ["DROP TABLE", "TRUNCATE"]
  requireReviewPatterns: ["ALTER TYPE"]

# then, with the key in the environment:
#   export MIGRATIONPILOT_LICENSE_KEY="MP-v2-ORG-..."
#   migrationpilot check migrations/

package.json Configuration

Alternatively, add configuration to your package.json under the "migrationpilot" key:

{
  "migrationpilot": {
    "pgVersion": 16,
    "failOn": "warning",
    "rules": {
      "MP037": false
    }
  }
}

← Quick Start GitHub Action →