From Chaos to Control
MSR replaces messy, ad-hoc scripts with a structured, repeatable, and safe migration process.
Unmanaged Migrations
One-off scripts lead to fragile, inconsistent environments.
One-off scripts don’t scale
They are hard to track, re-run, and share, leading to inconsistent environments.Rollbacks are fragile
Without a clear, reversible path, reverting changes is manual, risky, and error-prone.Tools are platform-specific
Teams often need separate tools and workflows for SQL, NoSQL, and other data stores.
How MSR Works
A simple, four-step process to bring structure and safety to your database changes.
Versioned Migrations
Migrations live as version-controlled files in your project repository.
State Tracking
MSR tracks which migrations have run and when, so you always know the current state.
Safe Execution
Run migrations with safety guarantees like dry runs, backups, built-in validations, and transaction control.
Repeatable Results
Achieve deterministic outcomes across all environments, from local dev to production.
Powerful, Flexible, and Safe
MSR provides a comprehensive toolset for managing your database schema evolution with confidence.
Deterministic Execution
Ensure migrations run predictably and in order, every single time, across all your environments.
Advanced Rollback Strategies
Safely reverse changes with automatic backups and multi-strategy rollbacks, protecting your data.
Granular Transaction Control
Manage how transactions are applied—per migration, in batches, or not at all—for ultimate control.
Automated Validation
Catch errors before they happen with built-in and custom validators for syntax, structure, and conventions.
Platform Independence
Designed to work with any database or framework, providing a consistent workflow for your entire stack.
Deep Extensibility
Extend MSR with custom handlers, validators, loggers, and lifecycle hooks to fit your exact needs.
Effortless to Use
MSR is designed for a seamless developer experience with a powerful CLI and flexible configuration. While these examples use msr-firebase, the base commands are the same for all MSR Core implementations.
⚡ Quick Installation
$ npm install @migration-script-runner/firebase🚀 Powerful & Compact CLI
Run all your migrations from the command line with simple, intuitive commands.
# Migrations
$ msr-firebase migrate # Run all pending
$ msr-firebase migrate 202501010003 # Migrate to version
$ msr-firebase down # Rollback last
$ msr-firebase list # Show status
# Firebase-specific
$ msr-firebase firebase:nodes # List nodes
$ msr-firebase lock:status # Check locks⚡ Zero-Config
Configure with environment variables or a `.env` file and you're ready to go.
# Configure via environment variables or .env file
DATABASE_URL=https://my-project.firebaseio.com
GOOGLE_APPLICATION_CREDENTIALS=./service-account.json
# Then just run
$ msr-firebase migrate⚙️ Automate in CI/CD
Integrate migrations into any CI/CD pipeline, such as GitHub Actions, for consistent and automated deployments.
...
- name: Run Migrations
run: npx msr-firebase migrate
env:
DATABASE_URL: ${{ secrets.DATABASE_URL }}
GOOGLE_APPLICATION_CREDENTIALS: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
...Platforms & Ecosystem
MSR is designed as a platform-agnostic core with a growing ecosystem of database-specific implementations.
MSR Core
The framework-agnostic engine that powers MSR. Manages state, execution, validation, and extensibility.
Firebase
Official implementation for Firebase, using Firestore for state management and locking.
SQL Databases
Support for popular SQL databases like PostgreSQL and MySQL is currently under active development.
Serverless Migrations Made Easy
Leverage the power of Firebase with an official MSR implementation designed for Firestore.
Migration Locking
Production ready
Perfect for Kubernetes, Docker, and multi-instance deployments. Prevents race conditions with automatic lock expiration and force-release commands.
Backup & Restore
Automatic protection
Automatic backups before migrations with flexible restore options. Protect your data with multiple backup modes and point-in-time recovery.
Firebase Native
Optimized for Firebase
Built specifically for Firebase Realtime Database with support for single-node transactions, path prefixing, and full Firebase Admin SDK features.
Type-Safe Migrations
Full TypeScript support
First-class TypeScript support with full type definitions. Write migrations with confidence using generic type parameters and interfaces.
Emulator Support
Test before deploy
Test migrations locally with Firebase Emulator before deploying to production. Complete integration test support with isolated environments.
CLI & Library
Use your way
Use as a command-line tool for quick migrations or integrate programmatically into your Node.js application. Same powerful features, your choice.
Advanced Features
A detailed look at the tools MSR provides to handle any migration scenario.
Migration Execution
- Multi-Format Migrations (TS, JS, SQL)
- Up/Down Methods for Reversible Migrations
- Batch Execution with Progress Tracking
- Target Version Migration (Up or Down)
- Selective Execution with File Patterns
Safety & Rollback
- Dry Run Mode for Safe Testing
- Automatic Database Backups
- Multiple Rollback Strategies (BACKUP, DOWN, BOTH, NONE)
- Checksum Validation to Detect Unauthorized Changes
- Pre-Migration Validation to Catch Issues Early
Transaction Management
- Configurable Transaction Modes (PER_MIGRATION, PER_BATCH, NONE)
- Full Control Over SQL Isolation Levels
- Automatic Retry Logic with Exponential Backoff
- Smart Detection of Transient Errors (e.g., Deadlocks)
- Callback-Based Transactions for NoSQL Databases
Validation & Quality
- Built-in Validators for Structure, Syntax, and Conventions
- Custom Validators to Extend Validation Rules
- Strict Mode to Treat Warnings as Errors in CI/CD
- Duplicate Timestamp/Version Detection
- Down Method Policies to Enforce Reversibility
Monitoring & Logging
- Built-in Metrics Collectors (Console, JSON, CSV)
- Detailed JSON/Text Execution Summaries
- Multiple Logger Support (Console, File, Silent, Custom)
- Log Level Control for Verbosity
- Lifecycle Hooks for Monitoring and Extension
Configuration & Extensibility
- Environment Variable Support (MSR_*)
- .env File Support (.env, .env.production, etc.)
- Custom Database Handlers for Any Database
- Custom Loaders, Validators, Loggers, and Renderers
- CLI Factory to Create Custom Command-Line Interfaces
How MSR Compares
MSR is designed for simplicity and flexibility, especially for serverless and NoSQL environments.
| Feature | MSR | Flyway | Liquibase |
|---|---|---|---|
| Primary Focus | Any (SQL, NoSQL, Programmatic) | SQL | SQL (with some NoSQL support) |
| Language | TS / JS / SQL | SQL | XML / YAML / JSON / SQL |
| NoSQL Support | Yes (Official & Custom) | No (Community extensions only) | Yes (MongoDB, Couchbase) |
| Transaction Control | Per-migration, Per-batch, None | Per-migration | Per-changeset |
| Data Migrations | Programmatic TS/JS | Raw SQL | CSV, SQL, Programmatic (Java) |
| Rollback Strategy | `down`, backup, both | `undo` scripts | Rollback commands, `rollback` tag |
| Dry Run | Yes (transaction-based) | Yes (SQL output) | Yes (SQL output) |
| Extensibility | High (custom handlers, hooks) | Moderate (Java plugins) | High (Java extensions) |
| Simplicity | High (zero-config) | High (convention-based) | Moderate (configuration-heavy) |
Why MSR Exists
MSR was born from a real-world need for a better migration tool.
In 2017, while building a mobile app with Firebase, a small team needed to backup and restore production data multiple times a week. Manual processes meant constant risk of corrupting critical data before the app even launched. The solution? A JavaScript tool that automated migrations with automatic backups and intelligent rollback.
Six years and many projects later, that prototype became MSR - completely rewritten in TypeScript with a database-agnostic architecture. The core insight: migration tools should be as flexible as your stack. Whether you're migrating Firebase collections or PostgreSQL tables, using SQL files or TypeScript logic, MSR adapts to your needs instead of forcing you into rigid patterns.
Today, MSR powers migrations across multiple database platforms with features traditional tools don't offer: built-in backup/restore, polyglot migrations (SQL + TypeScript + JavaScript), custom validators, transaction control, and deep customization. It's designed for real-world scenarios where you need both the simplicity of SQL migrations and the power of programmatic logic.
Open Source & Philosophy
MSR is built on a foundation of transparency, flexibility, and community.
Fair Source, Not Just Open Source
MSR is free to use, modify, and distribute under the MIT + Commons Clause. This “fair source” license protects the project by preventing it from being sold as a competing service, ensuring it remains a sustainable community-driven tool.
Open Governance
The project is transparently developed on GitHub and led by its original author. We believe in building a tool that serves its users, not corporate interests, with plans for greater community involvement in the future.
CLI-First, Library-Ready
MSR is designed with a powerful command-line interface for immediate productivity. For more complex needs, it can be seamlessly integrated as a library into any Node.js application, giving you full programmatic control.
Designed to be Embedded
MSR is not a restrictive framework that takes over your codebase. It’s a focused tool designed to be embedded and extended. It enhances your workflow without dictating it, leaving you in control.
Ready to Get Started?
Explore the documentation for our core package and the Firebase implementation to begin your journey with MSR.
MSR Core
The core library provides the fundamental building blocks for script management, execution, and state tracking. It's designed to be framework-agnostic.
MSR Firebase
An official implementation for Firebase that uses Firestore for state management, perfect for serverless environments.