msr-firebase

library0.1.6jsnpmunverified

A TypeScript-first library (v0.1.6) for running database migration scripts against Firestore. Integrates with Firebase Admin SDK to manage migration state via a Firestore collection. Provides CLI and programmatic APIs for applying, rolling back, and listing migrations. Designed for teams requiring structured schema evolution in Firestore, similar to Alembic for SQL databases. Ships TypeScript declarations and supports ESM and CJS environments. Active development with limited community adoption.

database devops

npm install msr-firebase

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MSR-FIREBASE

msr-firebase

databasejavascriptv0.1.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MigrationRunner

✓ import { MigrationRunner } from 'msr-firebase'

✗ const { MigrationRunner } = require('msr-firebase');

Library supports both ESM and CJS. Default export not available; use named import.

createMigration

✓ import { createMigration } from 'msr-firebase'

✗ import createMigration from 'msr-firebase';

Mistaking default export for named export is common. Use named import.

MigrationScript

✓ import type { MigrationScript } from 'msr-firebase'

TypeScript users should import types with 'import type' to avoid runtime overhead.

Shows initializing the runner with Firebase Admin SDK, creating a migration with up/down functions, registering it, and executing pending migrations.

import { MigrationRunner, createMigration } from 'msr-firebase'; import * as admin from 'firebase-admin'; admin.initializeApp({ credential: admin.credential.applicationDefault(), }); const runner = new MigrationRunner({ firestore: admin.firestore(), migrationsPath: './migrations', stateCollection: '_migrations', }); // Define a migration script const migration1 = createMigration( 'add_users_collection', async (db) => { await db.collection('users').doc('example').set({ name: 'Alice' }); }, async (db) => { await db.collection('users').doc('example').delete(); } ); // Register and run migrations runner.register(migration1); await runner.runUp();

Debug

Known issues

gotchaState collection must not exist or be empty on first run; migration runner will create the collection.

fix

Ensure no conflicting collection named '_migrations' (or configured name) exists with unexpected documents.

affects: >=0.1.0

gotchaMigration scripts are not automatically discovered in directory; you must register each migration explicitly.

fix

Use runner.register() to add all migration scripts. Alternatively, use the programmatic API to load from a folder.

affects: >=0.1.0

deprecatedThe constructor option 'migrationsPath' is deprecated in favor of manual registration.

fix

Remove migrationsPath and register migrations manually via runner.register().

affects: >=0.1.5

Errors

Common errors & fixes

Error: The 'credential' property must be initialized before calling admin.firestore()

Attempting to use firestore before initializing admin app.

fix

Ensure admin.initializeApp() is called before creating MigrationRunner instance.

AssertionError [ERR_ASSERTION]: Migration 'example_migration' already exists

Registering a migration with a name that has already been applied or registered twice.

fix

Use unique migration names or check previously applied migrations with runner.getAppliedMigrations().

FirebaseError: Missing or insufficient permissions.

Service account key lacks permissions to write to the migration state collection or run migrations.

fix

Assign appropriate Firestore roles (e.g., 'Cloud Datastore User') to the service account.

Upgrade

Version history

0.1.6latest on npm

Audit

Dependencies

firebase-adminrequiredRequired to interact with Firestore for migration state and database operations.

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/vlavrynovych/msr-firebase ↗

packagemsr-firebase ↗

homepagehttps://github.com/vlavrynovych/msr-firebase#readme ↗