Why Migration Script Runner?
One-off scripts create chaos. MSR brings order by treating migrations as a first-class engineering concern.
One-off scripts don’t scale
One-off migration scripts 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.
1. Versioned Migrations
Migrations live as version-controlled files in your project repository.
2. State Tracking
MSR tracks which migrations have run and when, so you always know the current state.
3. Safe Execution
Run migrations with safety guarantees like dry runs, backups, and transaction control.
4. Repeatable Results
Achieve deterministic outcomes across all environments, from local dev to production.
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_JSON: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS_JSON }}
...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.
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) |
Open Source & Philosophy
MSR is built on a foundation of transparency, flexibility, and community.
Fair Source License
MSR is released under the MIT License with Commons Clause. It's free to use and modify, but not to resell as a competing product.
Open Governance
The project is open source and its development is led by its original author, with future plans for community involvement.
CLI-First, Library-Ready
Use the powerful CLI for quick, one-off tasks, or integrate MSR as a library for programmatic control in your applications.
Designed to be Embedded
MSR is not a framework that takes over your codebase. It’s a tool designed to be embedded and extended, not enforced.
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.