API database migrations

Database Migrations

Migrations are the recommended way to change the database schema, particularly once the database contains user data, when it may not be possible to drop the entire database and rebuild it from scratch.

Migrations are run automatically whenever the API or the Geoprocessing service started/restarted. To prevent migrations from running on startup, see the main README.md (API_RUN_MIGRATIONS_ON_STARTUP and GEOPROCESSING_RUN_MIGRATIONS_ON_STARTUP env vars).

TypeORM includes a cli tool, which however cannot handle entity files written in TypeScript.

A npm script is available in marxan-api and in geoprocessing-service to run the TypeORM CLI tool:
"typeorm": "ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js"

Create migration file

depending on the conection default or geoprocessingDB

docker exec -it marxan-api npm run typeorm migration:create -- -n My--New-Migration -c "<connection>"
> mgis-api@1.5.0 typeorm /opt/mgis-api
> ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js "migration:create" "-n" "My--New-Migration"

Migration /opt/geoprocessing/src/migrations/<connection>/1584368092372-My--New-Migration.ts has been generated successfully.

How to run the latest migration manually

With connection being default(marxan-api-db) or geoprocessingDB:

docker exec -it marxan-api npm run typeorm migration:run -- -c "<connection>"

How to revert the latest migration manually

docker exec -it <container_name> npm run typeorm migration:revert -- -c "<connection>"

How to make a database change that affects code

1. Create a new migration as described above.
2. Update all entity files that will be affected.
3. This migration will be automatically applied to the database immediately after creation if the docker is currently running.
4. If there were any errors in the migration, they will be visible in the docker logs.
5. To fix these errors remove the new migration file, fix any affected TypeORM *.entity.ts files and then run migration:generate again

You can find more detailed information in TypeORM's migrations documentation.