safe-migrate

safe-migrate is an advanced Continuous Integration/Continuous Deployment (CI/CD) infrastructure tool designed to mitigate the risks associated with PostgreSQL database migrations. By intelligently analyzing and simulating SQL schema changes before they reach production, safe-migrate helps prevent catastrophic locking issues in live environments.

Key Features

• Risk Assessment: safe-migrate identifies potentially hazardous migrations early in the process. It parses SQL, simulates the changes, and validates the outcome against a synchronized snapshot of the database, ensuring that migrations do not lead to unwanted locks or downtimes.
• Comprehensive Checks: The tool covers a wide range of migration hazards, including:
  • Blocking locks, table rewrites, constraints, and indexes
  • Destructive alterations, schema drift, and migration ordering conflicts
  • Privilege-sensitive changes and potential operational failures
  • Compliance with best practices, including suggestions for concurrent index creation to minimize lock time

Supported PostgreSQL Versions

safe-migrate is compatible with PostgreSQL versions 14 to 18, providing broad coverage for various project requirements.

Quick Start Commands

Set up and run safe-migrate effortlessly with the following commands:

export DATABASE_URL='postgres://readonly_user@localhost:5432/app'
safe-migrate sync
safe-migrate lint-chain --dir migrations

This will initiate syncing and perform checks on your migration files.

Integration with GitHub Actions

By creating a safe-migrate-baseline environment in GitHub, users can automate monitoring and initialization tasks. This includes generating a trusted baseline for migration assessments, necessary for maintaining database integrity in CI workflows.

Result Interpretation

safe-migrate provides categorized results based on the severity of the findings. Each conclusion contributes to a better understanding of the migration's impact:

Configuration and Customization

Users can customize their settings in a safe-migrate.toml file to better suit their project requirements. This includes rules for handling specific migration scenarios, thresholds for operation safety, and more.

Example Rust Integration

For those interested in integrating safe-migrate within Rust applications, the API allows for seamless analysis with existing baseline data:

use safe_migrate::api::{self, Baseline, Config};
use std::path::Path;

let config = Config::load_from_file(Path::new("safe-migrate.toml"))?;
let baseline = Baseline::load_optional(Path::new(".safe-migrate.cache"), &config)?;
let outcome = api::analyze(
    &config,
    "2026-09-05_add_index.sql",
    "CREATE INDEX ...",
    &baseline,
)?;

if outcome.should_halt() {
    eprintln!("{}", outcome.markdown());
}

Conclusion

safe-migrate stands out as a crucial tool for developers and database administrators looking to ensure a smooth migration process within PostgreSQL. By eliminating the risks of catastrophic locks and fostering an environment of careful analysis, it empowers teams to deploy changes with confidence.