Firebase Migration Script Runner

Firebase Realtime Database implementation for Migration Script Runner (MSR Core). Provides version-controlled database migrations with built-in backup, rollback, and distributed locking for production deployments.

⚠️ UNSTABLE VERSION WARNING

Version v0.2.0 is currently unstable and not recommended for production use. The project is under active development and may receive significant updates. Please use with caution and test thoroughly before deploying to production environments.

What's New in v0.2.0

🎉 Major upgrade with production-ready features:

• 🔒 Migration Locking - Prevent concurrent migrations in Kubernetes, Docker, and multi-instance deployments
• ⬆️ MSR Core v0.8.1 - Latest core with bug fixes, handler access API, and improved locking lifecycle
• 🔧 Type-Safe API - Full TypeScript support with generic type parameters
• 🖥️ Lock Management CLI - Commands for monitoring and managing migration locks
• 📚 Comprehensive Documentation - 300+ line locking guide with deployment examples
• 🧪 Production Tested - Battle-tested in distributed environments

Upgrading from v0.1.x? See the Migration Guide.

Table of Contents

• What's New in v0.2.0
• Features
• Installation
• Quick Start
• Key Features
• Documentation

Features

• 🔄 Version-Controlled Migrations: Track and apply database changes systematically
• 🔒 Distributed Locking: Prevent concurrent migrations in Kubernetes, Docker, and multi-instance deployments
• 💾 Automatic Backups: Built-in backup and restore functionality
• ↩️ Rollback Support: Safely revert migrations with down() functions or backups
• ✅ Checksum Validation: Detect modified migration files
• 🎯 Firebase-Specific: Optimized for Firebase Realtime Database with atomic transactions
• 🛠️ CLI & Programmatic: Use via command-line or integrate into your application
• 🧪 Emulator Support: Test migrations locally with Firebase Emulator
• 📊 Migration Status: Track applied, pending, and failed migrations
• 🔐 Production-Ready: Battle-tested locking for distributed environments

Installation

npm install @migration-script-runner/firebase

Or with yarn:

yarn add @migration-script-runner/firebase

Quick Start

# Install
npm install @migration-script-runner/firebase

# Run migrations with inline credentials
npx msr-firebase migrate \
  --database-url https://your-project.firebaseio.com \
  --credentials ./serviceAccountKey.json

# Or use environment variables
export DATABASE_URL=https://your-project.firebaseio.com
export GOOGLE_APPLICATION_CREDENTIALS=./serviceAccountKey.json
npx msr-firebase migrate

👉 View Full Getting Started Guide for complete setup instructions, migration examples, and configuration options.

Key Features

🔒 Migration Locking for Distributed Environments

Perfect for Kubernetes, Docker Swarm, and auto-scaling deployments:

// msr.config.js
module.exports = {
  locking: {
    enabled: true,
    timeout: 600000  // 10 minutes
  }
};

Benefits:

• Prevents race conditions in multi-pod deployments
• Automatic lock expiration and cleanup
• Force-release stuck locks with CLI commands
• Works seamlessly across distributed instances

CLI Commands:

# Check lock status
msr-firebase lock:status

# Force-release stuck lock
msr-firebase lock:release --force

See Migration Locking Guide for details.

💾 Backup & Restore

Automatic backups before migrations:

# Create backup
msr-firebase backup

# List backups
msr-firebase list-backups

# Restore from backup
msr-firebase restore backup-1234567890.json

↩️ Safe Rollbacks

Multiple rollback strategies:

# Roll back last migration
msr-firebase down

# Roll back multiple migrations
msr-firebase down --steps 3

🧪 Firebase Emulator Support

Test migrations locally before deploying:

# Start emulator
firebase emulators:start --only database

# Run migrations against emulator
export FIREBASE_DATABASE_URL=http://localhost:9000
msr-firebase migrate

Documentation

Full documentation available at https://migration-script-runner.github.io/msr-firebase/

Quick Links

Getting Started:

• Getting Started - Installation and quick start

Using MSR Firebase:

• CLI Usage - Command-line interface guide
• Library Usage - Programmatic API usage
• API Reference - Complete API documentation

Writing Migrations:

• Migration Scripts - How to write migrations
• Migration Locking - Distributed environments
• Transactions - Firebase transaction limitations
• Testing - Testing with Firebase Emulator
• Backup & Restore - Backup strategies

How to obtain Service Account Key

To use the Firebase Admin SDK in non-Google environments, you need a service account key file.

Official Documentation: Initialize the SDK in non-Google environments

Quick Steps:

1. Open https://console.firebase.google.com/project/{your_project_id}/settings/serviceaccounts/adminsdk (replace {your_project_id} with your actual project ID)
2. Click Generate new private key button
3. Download the JSON file and store it securely
4. Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the file path

Migration from v0.1.x

Breaking Change: Package name changed from msr-firebase to @migration-script-runner/firebase.

For complete upgrade instructions, troubleshooting, and migration scenarios, see the Migration Guide.

📄 License

This project is licensed under the MIT License with Commons Clause and Attribution Requirements.

Based on Migration Script Runner by Volodymyr Lavrynovych.

Quick Summary:

• ✅ Free to use in your applications (including commercial)
• ✅ Free to modify and contribute
• ❌ Cannot sell this adapter or Firebase-specific extensions as standalone products
• 🔒 Firebase migration extensions require attribution

See the LICENSE file and NOTICE file for detailed examples and FAQ.

By Volodymyr Lavrynovych • Created in Ukraine 🇺🇦