Migrata Docs

Appearance

Features ​

Schema Inspection ​

Inspect live PostgreSQL databases and extract all DDL into organized local SQL files. Captures tables, columns, indexes, constraints, enums, views, materialized views, functions, stored procedures, and partitions.

Schema Diffing ​

Compare any two schema sources and generate a detailed migration plan. Sources can be:

  • Live database connection strings
  • Local .sql files
  • Directories of .sql files
  • Remote URLs hosting SQL content
  • Inline SQL strings

Diff Risk Classification ​

Every planned migration is classified to help you quickly assess impact:

  • Safe: No data loss risk (adding a table, creating an index)
  • Warning: Potential risk (changing a column type)
  • Destructive: High risk (dropping a column, removing a table)

Warnings and destructive changes are summarized separately with counts.

Impact Analysis ​

See all downstream components that depend on entities being modified. Views, functions, and other objects that reference a changed table are listed alongside the query plan so you can assess blast radius.

Schema Overview ​

A summary table comparing source and target schemas side by side, showing entity counts for tables, partitions, indexes, constraints, functions, enums, views, and materialized views. Changed values are highlighted.

Multiple Display Formats ​

Three ways to view migration plans:

  • Stacked (default): each plan and diff shown in separate panels
  • Inline: plans and diffs in a compact two-column grid
  • Table: all plans, diffs, and impacted components in a single table

Safe Cast Migrations ​

The --safe-cast flag generates multi-step SQL for column type changes that prevent data loss. Instead of a single ALTER COLUMN that might fail or truncate data, it:

  1. Adds a new temporary column with the target type
  2. Copies and converts data from the old column
  3. Drops the old column
  4. Renames the new column to the original name
  5. Re-applies constraints and indexes

Advisory Locks ​

Prevents concurrent migration processes from running on the same database. Enabled by default, uses PostgreSQL pg_try_advisory_lock for non-blocking coordination. Can be disabled with --skip-lock.

Dev-Database Validation ​

Test schema changes against an ephemeral PostgreSQL container before applying to production. The --dev-image flag spins up a Docker container, applies the current schema, runs the migration, and reports any runtime errors.

Table Partition Support ​

Detects and compares PostgreSQL table partitions in the diff. Basic DDL operations (create, drop, rename) are automated. Changes involving data movement (bounds, strategy, parent) are detected and flagged with warnings for manual handling.

Interactive Prompt Handling ​

Certain schema changes require user input, such as choosing a replacement value when removing an enum member. The CLI prompts interactively for these decisions, then applies the change transactionally. For automated runs, use --answer to pre-supply responses.

Config-First Workflow ​

Define migration commands in reusable YAML or JSON files instead of CLI arguments. Chain multiple commands in a single file for batch operations.

Supports secret interpolation for sensitive values:

  • ${file:/path/to/secrets.json:vars.KEY} loads from a JSON or YAML file
  • ${env:MY_VARIABLE} loads from an environment variable

Glob Filtering ​

Use --include and --exclude with glob patterns to control which entities are inspected or diffed. For example, --include "public*" limits operations to the public schema.

Plan Persistence ​

Save generated migration plans to timestamped SQL files with -o and optionally add a custom postfix with -p / --postfix. Persisted plans can be reviewed, version-controlled, and applied later with the apply command.

Dry-Run Mode ​

The apply command supports --dry-run to preview all DDL statements that would be executed without making any changes.

CI/CD Ready ​

  • --answer pre-supplies responses to interactive planner prompts for fully non-interactive runs
  • --approve / --abort auto-approve or auto-abort plans
  • --no-styles disables console formatting for clean log output
  • --no-logs silences progress output
  • --silent suppresses SQL parsing errors