FirebaseConfig

Configuration class for Firebase Realtime Database migrations.

Table of contents

1. Overview
2. Class Signature
3. Firebase-Specific Properties
   1. databaseUrl
   2. applicationCredentials
   3. shift
   4. tableName
4. Standard MSR Properties
   1. folder
   2. locking
   3. transaction
   4. displayLimit
   5. logLevel
5. Methods
   1. buildPath()
      1. Parameters
      2. Returns
      3. Example
   2. getRoot()
      1. Returns
      2. Example
6. Usage Examples
   1. Minimal Configuration
   2. Complete Configuration
   3. Environment-Specific Configuration
   4. Multi-Environment Database
   5. Configuration from Environment
7. Configuration Priority

---

Overview

FirebaseConfig extends MSR Core’s Config class to provide Firebase-specific configuration options for migrations.

Inheritance: Extends Config from MSR Core

Class Signature

class FirebaseConfig extends Config

---

Firebase-Specific Properties

databaseUrl

Firebase Realtime Database URL.

databaseUrl: string | undefined

Default: process.env.DATABASE_URL

Example:

config.databaseUrl = 'https://your-project.firebaseio.com';

---

applicationCredentials

Path to Firebase service account key JSON file.

applicationCredentials: string | undefined

Default: process.env.GOOGLE_APPLICATION_CREDENTIALS

Example:

config.applicationCredentials = './serviceAccountKey.json';

---

shift

Root path prefix for multi-environment database namespacing.

shift: string | undefined

Default: undefined (root level)

Use Case: Store multiple environments in a single Firebase database

Example:

// Different environments in same database
config.shift = 'production';  // Data at /production/*
config.shift = 'staging';     // Data at /staging/*
config.shift = 'development'; // Data at /development/*

---

tableName

Name of the migration tracking node in Firebase.

tableName: string

Default: 'schema_version'

Example:

config.tableName = 'migrations';

---

Standard MSR Properties

FirebaseConfig inherits all standard configuration properties from MSR Core’s Config class:

folder

Path to migrations directory.

folder: string

Default: './migrations'

Example:

config.folder = './db/migrations';

---

locking

Migration locking configuration for distributed environments.

locking: {
  enabled: boolean;
  timeout: number;
}

Default: { enabled: false, timeout: 600000 }

Example:

config.locking = {
  enabled: true,        // Enable in production
  timeout: 600000       // 10 minutes
};

---

transaction

Transaction configuration (Firebase uses TransactionMode.NONE).

transaction: {
  mode: TransactionMode;
}

Default: { mode: TransactionMode.NONE }

Firebase Realtime Database does not support database-wide transactions. MSR Firebase automatically sets this to NONE. See Transaction Guide for details.

---

displayLimit

Maximum number of migrations to display in CLI output.

displayLimit: number

Default: 100

---

logLevel

Logging verbosity level.

logLevel: 'error' | 'warn' | 'info' | 'debug'

Default: 'info'

---

Methods

buildPath()

Constructs a full Firebase path with shift prefix.

buildPath(path: string): string

Parameters

path - string Path segment to append to shift prefix

Returns

string - Full path including shift prefix

Example

const config = new FirebaseConfig();
config.shift = 'production';

config.buildPath('users');     // Returns: 'production/users'
config.buildPath('posts/123'); // Returns: 'production/posts/123'

---

getRoot()

Gets the root path including shift prefix.

getRoot(): string

Returns

string - Root path with trailing slash

Example

const config = new FirebaseConfig();
config.shift = 'staging';

const root = config.getRoot(); // Returns: 'staging/'

---

Usage Examples

Minimal Configuration

import { FirebaseConfig } from '@migration-script-runner/firebase';

const config = new FirebaseConfig();
config.databaseUrl = 'https://my-project.firebaseio.com';
config.applicationCredentials = './key.json';

---

Complete Configuration

import { FirebaseConfig } from '@migration-script-runner/firebase';

const config = new FirebaseConfig();

// Firebase connection
config.databaseUrl = process.env.DATABASE_URL;
config.applicationCredentials = process.env.GOOGLE_APPLICATION_CREDENTIALS;

// Migration settings
config.folder = './migrations';
config.tableName = 'schema_version';
config.shift = process.env.NODE_ENV; // dev/staging/production

// Locking (production only)
config.locking = {
  enabled: process.env.NODE_ENV === 'production',
  timeout: 600000 // 10 minutes
};

// Display settings
config.displayLimit = 50;
config.logLevel = 'info';

---

Environment-Specific Configuration

import { FirebaseConfig } from '@migration-script-runner/firebase';

function createConfig(env: 'development' | 'staging' | 'production'): FirebaseConfig {
  const config = new FirebaseConfig();

  // Common settings
  config.folder = './migrations';
  config.tableName = 'schema_version';

  if (env === 'production') {
    // Production: separate database, with locking
    config.databaseUrl = process.env.PROD_DATABASE_URL;
    config.applicationCredentials = process.env.PROD_CREDENTIALS;
    config.locking = {
      enabled: true,
      timeout: 600000
    };
  } else {
    // Dev/Staging: shared database with shift
    config.databaseUrl = process.env.DEV_DATABASE_URL;
    config.applicationCredentials = process.env.DEV_CREDENTIALS;
    config.shift = env; // Namespace: /development/* or /staging/*
  }

  return config;
}

// Usage
const config = createConfig('staging');

---

Multi-Environment Database

import { FirebaseConfig } from '@migration-script-runner/firebase';

// Share one Firebase database across environments using shift
class MultiEnvConfig {
  static create(environment: string): FirebaseConfig {
    const config = new FirebaseConfig();
    config.databaseUrl = 'https://shared-db.firebaseio.com';
    config.applicationCredentials = './serviceAccountKey.json';
    config.shift = environment; // dev/staging/production

    // Each environment has isolated data
    // /dev/users, /dev/posts
    // /staging/users, /staging/posts
    // /production/users, /production/posts

    return config;
  }
}

const devConfig = MultiEnvConfig.create('dev');
const stagingConfig = MultiEnvConfig.create('staging');
const prodConfig = MultiEnvConfig.create('production');

---

Configuration from Environment

import { FirebaseConfig } from '@migration-script-runner/firebase';
import 'dotenv/config';

const config = new FirebaseConfig();

// Automatically reads from process.env
config.databaseUrl = process.env.DATABASE_URL;
config.applicationCredentials = process.env.GOOGLE_APPLICATION_CREDENTIALS;
config.folder = process.env.MIGRATIONS_FOLDER || './migrations';
config.shift = process.env.FIREBASE_SHIFT;

// Parse boolean from env
config.locking.enabled = process.env.ENABLE_LOCKING === 'true';

// Parse number from env
config.displayLimit = parseInt(process.env.DISPLAY_LIMIT || '100', 10);

// Parse log level
config.logLevel = (process.env.LOG_LEVEL as any) || 'info';

---

Configuration Priority

Configuration can be set via multiple sources (in order of priority):

1. CLI Flags (highest priority)

   npx msr-firebase migrate \
     --database-url https://my-project.firebaseio.com \
     --credentials ./key.json
   

2. Programmatic Configuration

   config.databaseUrl = 'https://my-project.firebaseio.com';
   

3. Environment Variables

   export DATABASE_URL=https://my-project.firebaseio.com
   

4. Default Values

   new FirebaseConfig() // Uses process.env by default