MondoKit GCP Firestore Migrations

Set up and run migrations, with state stored in firestore and a mutex lock to ensure only one is run at a time

Note: @mondokit libs all require ESM. If your project still uses CommonJS, then you can continue using our previous incarnation, gae-js, until you can make the upgrade.

Find the source code at gcp-firestore-migrations on GitHub.


npm install @mondokit/gcp-firestore-migrations



Run Migrations as a function e.g /migrate route handler


Bootstrap Migrations to be run before application starts

Migration Files

The AutoMigration interface

Use naming convention with date and index number to version migrations


const userRepository = new TimestampedRepository<User>("users");

export const v_20220122_001_addUsers: AutoMigration = {
    id: "v_20220122_001_addUsers",   
    migrate: async ({ logger }) => {"Adding users");
      const createdUsers = await[
          name: "User 1",
          name: "User 2",
      ]);`Creating ${createdUsers.length} new users`);
    // Optional function that skips if returning true. For example to skip in a certain environment.
    // skip: () => true,
    // Optional options to override from defaults, or those defined globally
    // options: { disableTimestampUpdate: false },

Application Startup (index.ts)

import { bootstrap } from "@mondokit/gcp-core";
import { bootstrapMigrations } from "@mondokit/gcp-firestore-migrations";
import { firestoreLoader, firestoreProvider, newTimestampedEntity } from "@mondokit/gcp-firestore";
import {v_20220122_001_addUsers} from "./migrations/v_20220122_001_addUsers"

// Add firestore support

// After firestore initialised
const migrations: AutoMigration[] = [

await bootstrap([bootstrapMigrations(migrations)]);
// OR with options
// await bootstrap([bootstrapMigrations(migrations, { disableTimestampUpdate: true })]);

Migration options (either global or per migration)

All properties are optional. These options can be specified globally (via the bootstrapMigrations or runMigrations functions) or overridden for an individual migration file (via the AutoMigration interface with the options property). Any options set via AutoMigration options will take preference over global settings or defaults.

Property Type Default Description
disableTimestampUpdate boolean false If enabled, this will skip automatically updating timestamp values via TimestampedRepository