{"id":15102891,"url":"https://github.com/kevlened/fireway","last_synced_at":"2025-09-27T00:31:54.519Z","repository":{"id":38420726,"uuid":"199922536","full_name":"kevlened/fireway","owner":"kevlened","description":"A schema migration tool for firestore","archived":true,"fork":false,"pushed_at":"2024-03-28T10:35:45.000Z","size":412,"stargazers_count":279,"open_issues_count":25,"forks_count":42,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-09-21T08:04:44.239Z","etag":null,"topics":["firebase","firestore","migration","schema","schema-migration"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kevlened.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-31T20:13:27.000Z","updated_at":"2024-09-13T14:47:13.000Z","dependencies_parsed_at":"2024-06-18T20:12:44.171Z","dependency_job_id":null,"html_url":"https://github.com/kevlened/fireway","commit_stats":{"total_commits":99,"total_committers":12,"mean_commits":8.25,"dds":"0.36363636363636365","last_synced_commit":"ed478ff7f751f8565241f59083197dfb83ad20d6"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevlened%2Ffireway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevlened%2Ffireway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevlened%2Ffireway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevlened%2Ffireway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kevlened","download_url":"https://codeload.github.com/kevlened/fireway/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219871828,"owners_count":16554457,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firebase","firestore","migration","schema","schema-migration"],"created_at":"2024-09-25T19:09:09.417Z","updated_at":"2025-09-27T00:31:49.215Z","avatar_url":"https://github.com/kevlened.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fireway\nA schema migration tool for firestore heavily inspired by [flyway](https://flywaydb.org/)\n\n## Install\n\n```bash\nyarn global add fireway\n\n# or \n\nnpx fireway\n```\n\n## Credentials\n\nIn 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.\n\nExample:\n```bash\nexport GOOGLE_APPLICATION_CREDENTIALS=\"path/to/firestore-service-account.json\"\n```\n\n## CLI\n\n```bash\nUsage\n  $ fireway \u003ccommand\u003e [options]\n\nAvailable Commands\n  migrate    Migrates schema to the latest version\n\nFor more info, run any command with the `--help` flag\n  $ fireway migrate --help\n\nOptions\n  --require        Requires a module before executing\n  -v, --version    Displays current version\n  -h, --help       Displays this message\n\nExamples\n  $ fireway migrate\n  $ fireway --require=\"ts-node/register\" migrate\n```\n\n### `fireway migrate`\n```bash\nDescription\n  Migrates schema to the latest version\n\nUsage\n  $ fireway migrate [options]\n\nOptions\n  --path         Path to migration files  (default ./migrations)\n  --projectId    Target firebase project\n  --dryrun       Simulates changes\n  --forceWait    Forces waiting for migrations that do not strictly manage async calls\n  --require      Requires a module before executing\n  -h, --help     Displays this message\n\nExamples\n  $ fireway migrate\n  $ fireway migrate --path=./my-migrations\n  $ fireway migrate --projectId=my-staging-id\n  $ fireway migrate --dryrun\n  $ fireway migrate --forceWait\n  $ fireway --require=\"ts-node/register\" migrate\n```\n\n## Migration file format\n\nMigration file name format: `v[semver]__[description].js`\n\n```js\n// each script gets a pre-configured firestore admin instance\n// possible params: app, firestore, FieldValue, FieldPath, Timestamp, dryrun\nmodule.exports.migrate = async ({firestore, FieldValue}) =\u003e {\n    await firestore.collection('name').add({key: FieldValue.serverTimestamp()});\n};\n```\n\n## Typed Migrations\n\nFor type checking and Intellisense, there are two options:\n\n### TypeScript\n\n1. Ensure [`ts-node`](https://www.npmjs.com/package/ts-node) is installed\n2. Define a `ts-node` configuration block inside your `tsconfig.json` file:\n\n   ```json\n   {\n     \"ts-node\": {\n       \"transpileOnly\": true,\n       \"compilerOptions\": {\n         \"module\": \"commonjs\"\n       }\n     }\n   }\n   ```\n3. Create a migration\n\n   ```ts\n    // ./migrations/v0.0.1__typescript-example.ts\n\n    import { MigrateOptions } from 'fireway';\n\n    export async function migrate({firestore} : MigrateOptions) {\n        await firestore.collection('data').doc('one').set({key: 'value'});\n    };\n   ```\n4. Run `fireway migrate` with the `require` option\n\n   ```sh\n   $ fireway migrate --require=\"ts-node/register\"\n   ```\n\n### JSDoc\n\nAlternatively, you can use [JSDoc](https://jsdoc.app/) for Intellisense\n\n```js\n/** @param { import('fireway').MigrateOptions } */\nmodule.exports.migrate = async ({firestore}) =\u003e {\n    // Intellisense is enabled\n};\n```\n\n## Running locally\n\nTypically, `fireway` expects a `--projectId` option that lets you specify the Firebase project associated with your Firestore instance against which it performs migrations. \nHowever, most likely you'll want to test your migration scripts _locally_ first before running them against your actual (presumably, production) instances. \nIf you are using the [Firestore emulator](https://firebase.google.com/docs/emulator-suite/connect_firestore), define the FIRESTORE_EMULATOR_HOST environment variable, e.g.:\n\n`export FIRESTORE_EMULATOR_HOST=\"localhost:8080\"`\n\nThe 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](https://www.npmjs.com/package/@google-cloud/firestore). \n\n## Migration logic\n\n1. Gather all the migration files and sort them according to semver\n2. Find the last migration in the `fireway` collection\n3. If the last migration failed, stop. (remove the failed migration result or restore the db to continue)\n4. Run the migration scripts since the last migration\n\n## Migration results\n\nMigration results are stored in the `fireway` collection in `firestore`\n\n```js\n// /fireway/3-0.0.1-example\n\n{\n  checksum: 'fdfe6a55a7c97a4346cb59871b4ce97c',\n  description: 'example',\n  execution_time: 1221,\n  installed_by: 'system_user_name',\n  installed_on: firestore.Timestamp(),\n  installed_rank: 3,\n  script: 'v0.0.1__example.js',\n  success: true,\n  type: 'js',\n  version: '0.0.1'\n}\n```\n\n## Contributing\n\n```bash\n# To install packages and firestore emulator\n$ yarn\n$ yarn setup\n\n# To run tests\n$ yarn test\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevlened%2Ffireway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkevlened%2Ffireway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevlened%2Ffireway/lists"}