To prepare for the deployment of our project, we will treat our local dev databases as though they are in production. This means that we should be writing and running migrations whenever we change our database schemas.
A migration is a basic file that has SQL commands for how to run the change (up) and how to revert it (down). Running a migration uses files generated with timestamps and simply runs all of them sequentially.
The TypeORM documentation covers in more depth what migrations are and how they should be used. We recommend reading through their docs before continuing.
Regarding seeding your database with fake data: we do not store our seed data in a migration. Because the migration:run command runs all migrations, it puts the seed data at risk of creating duplicates, erroring out, and stopping the seeding process.
Ideally, you don't need to seed your database too often. However, if you somehow royally destroy your local database, take the following steps:
- Empty your database using
npm run empty - Seed your database using
npm run seed - Run all the migrations using
npm run typeorm migration:run -- -c dev
You must run all the migrations after running the seed command, because the data generated by the factories reflects the schema represented by the initial migration.
Below, we highlight some quirks of the migration process in TypeORM, as well as put some quick commands as a cheatsheet reference for PharmD developers.
TypeORM migrations are a bit interesting because they don't consistently use one of JavaScript or TypeScript. The commands for creating or generating migration files produce .ts files, but they must be compiled back to JavaScript before a user can run or revert them. So that we don't have to remember which needs special attention, we've outlined some shortcuts below.
When creating or generating a new migration, it is essential that the developr fills out both the up and down functions.
Across all these commands, the -c flag specifies that we want this in the "dev" database. If you named your local database something different, you should use that instead. The -n flag specifies the name of the migration. Because these are using npm to run typeorm commands, we must include a -- between the command and the flags.
-
To create a migration from scratch:
npm run typeorm migration:create -- -n <NameOfMigration> -c dev- To fill this out, you can either write your own SQL commands or use the migration API to assemble your queries
-
To automatically generate a migration:
npm run typeorm migration:generate -- -n <NameOfMigration> -c dev- If automatically generating the migration, it is recommended to generate a new file after each change made to a model.
-
To run all migrations:
npm run typeorm migration:run -- -c dev- This is a custom command that compiles the TypeScript to JavaScript, as TypeORM requires
- This command runs all migrations
-
To revert a migration:
npm run typeorm migration:revert -- -c dev- This is a custom command that compiles the TypeScript to JavaScript, as TypeORM requires
- You need to run this command for each migration you want to revert. It will not revert all existing migrations at once.