A schema migration tool for firestore heavily inspired by flyway
yarn global add fireway
# or
npx fireway
In order to fireway be able to connect to firestore you need to set up the environment variable GOOGLE_APPLICATION_CREDENTIALS
with service account file path.
Example:
export GOOGLE_APPLICATION_CREDENTIALS="path/to/firestore-service-account.json"
Usage
$ fireway <command> [options]
Available Commands
migrate Migrates schema to the latest version
For more info, run any command with the `--help` flag
$ fireway migrate --help
Options
--require Requires a module before executing
-v, --version Displays current version
-h, --help Displays this message
Examples
$ fireway migrate
$ fireway --require="ts-node/register" migrate
fireway migrate
Description
Migrates schema to the latest version
Usage
$ fireway migrate [options]
Options
--path Path to migration files (default ./migrations)
--projectId Target firebase project
--dryrun Simulates changes
--forceWait Forces waiting for migrations that do not strictly manage async calls
--require Requires a module before executing
-h, --help Displays this message
Examples
$ fireway migrate
$ fireway migrate --path=./my-migrations
$ fireway migrate --projectId=my-staging-id
$ fireway migrate --dryrun
$ fireway migrate --forceWait
$ fireway --require="ts-node/register" migrate
Migration file name format: v[semver]__[description].js
// each script gets a pre-configured firestore admin instance
// possible params: app, firestore, FieldValue, FieldPath, Timestamp, dryrun
module.exports.migrate = async ({firestore, FieldValue}) => {
await firestore.collection('name').add({key: FieldValue.serverTimestamp()});
};
For type checking and Intellisense, there are two options:
ts-node
is installedDefine a ts-node
configuration block inside your tsconfig.json
file:
{
"ts-node": {
"transpileOnly": true,
"compilerOptions": {
"module": "commonjs"
}
}
}
Create a migration
// ./migrations/v0.0.1__typescript-example.ts
import { MigrateOptions } from 'fireway';
export async function migrate({firestore} : MigrateOptions) {
await firestore.collection('data').doc('one').set({key: 'value'});
};
Run fireway migrate
with the require
option
$ fireway migrate --require="ts-node/register"
Alternatively, you can use JSDoc for Intellisense
/** @param { import('fireway').MigrateOptions } */
module.exports.migrate = async ({firestore}) => {
// Intellisense is enabled
};
Typically, fireway
expects a --projectId
option that lets you specify the Firebase project associated with your Firestore instance against which it performs migrations.
However, most likely you'll want to test your migration scripts locally first before running them against your actual (presumably, production) instances.
If you are using the Firestore emulator, define the FIRESTORE_EMULATOR_HOST environment variable, e.g.:
export FIRESTORE_EMULATOR_HOST="localhost:8080"
The firestore node library will connect to your local instance. This way, you don't need a project ID and migrations will be run against your emulator instance. This works since fireway
is built on the firestore node library.
fireway
collectionMigration results are stored in the fireway
collection in firestore
// /fireway/3-0.0.1-example
{
checksum: 'fdfe6a55a7c97a4346cb59871b4ce97c',
description: 'example',
execution_time: 1221,
installed_by: 'system_user_name',
installed_on: firestore.Timestamp(),
installed_rank: 3,
script: 'v0.0.1__example.js',
success: true,
type: 'js',
version: '0.0.1'
}
# To install packages and firestore emulator
$ yarn
$ yarn setup
# To run tests
$ yarn test
MIT