@boundstate/firebase-migrate

CLI for syncing Firebase and handling migrations.

$ npm install @boundstate/firebase-migrate

Introduction

Migrating data in Firebase production apps is hard.

The aim of this tool is to ease the process, avoiding data loss or disruptions to services.

Each version of data is prefixed (e.g. /v1, /v2) so that apps can still function until they are updated. Rules for each version are defined in separate files, and are automatically combined and updated so that only the latest version of data is writable.

Quick start

Configure your project by creating firebase-migrate.json at the project root:

{
  "environment": {
    "project-1": {
      "someservice.key": "PROJECT_1_SOME_SERVICE_KEY"
    }
  },
  "migrations": "./firebase/migrations",
  "databaseRules": "./firebase/rules"
}

Options

• environment: map of projects to maps of Firebase functions config keys to ENV var names. (Config is set during the migration process before cloud functions are deployed)
• migrations: path to migrations
• databaseRules: path to Bolt files

Important: If using TypeScript, compile migrations before running the CLI, and point the migrations path in firebase-migrate.json to the build folder.

Create a migration

1. Create a migration file v1-to-v2.ts:

   import {MigrateFunction} from '@boundstate/firebase-migrate';
   
   const migrate: MigrateFunction = async (db) => {
     await db.update('/', {
       'example/path': true,
     });
   };
   
   export = migrate;

   Before this function is run, all data will be automatically copied from /v1 to /v2. Database operations performed in the function are automatically prefixed with /v2.

2. Create a file in your rules folder named v2-rules.bolt and define the security rules

3. Update references in your app code to use the v2 data

Using the CLI

Deploy to Firebase and apply any new migrations:

$ firebase-migrate --project <projectId>

Deploy only database rules, functions and/or storage rules (skipping migrations):

$ firebase-migrate --project <projectId> --only database functions storage

Deploy process

1. Load database metadata - If db metadata indicates a deploy is already in progress, this process is cancelled (unless the CLI is run with --force).
2. Parse database rules - Compiles database Bolt rules.
3. Parse migrations - Parses migration files and calculates a migration path if necessary.
4. Prepare database - Sets database metadata to indicate that a deploy (and a migration) is in progress.
5. Migrate - Makes the database read-only and runs any necessary migrations.
6. Deploy database rules - Combines and deploys the database rules, with all previous versions made read-only.
7. Deploy storage rules
8. Set functions config
9. Deploy functions - This is done last so that any db triggers are not run during the migration.