Don't understand how to use this tool.

[natecraft1]

I need to do a migration and would love to use this tool but the README is not very helpful. Can you do a tutorial or add more documentation?

I installed yarn then tried yarn add -G fireway but it said error Missing list of packages to add to your project.

[Acterion]

Does your project also use a yarn package manager?

[kevlened]

The project uses yarn, but the instructions were incorrect. yarn add -G fireway should be yarn global add fireway. This is fixed in the README.

I should write a brief guide for folks where fireway is their first migration tool. For now, I've written an intro below.

Keep in mind that fireway doesn't know anything about your data; you have to write all the migration logic. fireway provides an easy way to organize your migrations and test them using --dryrun. Each migration file is just a .js or .ts file that has a version and a description. fireway sees which migration files have not been run yet (it stores which files have been run in the fireway collection on your firestore instance) and then runs them in order. Here's the gist for your first migration:

0. Install fireway
1. Create a directory called /migrations
2. Create /migrations/v0.0.0__first.js with the contents below:

module.exports.migrate = async ({firestore}) => {
    // Use firestore like you normally would
    await firestore.collection('something').doc('big').set({nice: 'field'});
};

3. Run fireway migrate --dryrun. This will connect to your firestore instance, using the credentials you've set with GOOGLE_APPLICATION_CREDENTIALS. Follow the guide here for auth instructions.
4. While running the migration, you'll see some logged messages, stats, and any errors. Because you used --dryrun, your migration didn't actually write to the database. If the migration succeeds using --dryrun, then go to the next step.
5. Run fireway migrate to commit to your actual firestore instance.
6. If there are any issues now, you'll have to make a decision, either write a new migration to fix the issues, or restore your firestore instance to a previous state.

• If you decide to write a new migration, you'll need to remove the failed migration entry (it's in the fireway collection), then delete your old migration file (or edit it if you just need to tweak it to fix the error).
• If you want to restore your instance, you'll need to plan ahead by backing up before Step 5. Follow the guide here to backup and restore your firestore instance.

[kevlened]

Closing the issue for now. If you have any questions, please comment! I've pinned the issue so other folks who have trouble can easily find it.