Database migrations

Migrations

Whenever a change to the database model is made, it is necessary to generate a migration using the EF Core tools. This allows for the database schema to be updated based on the new model.

Creating a migration

Due to the split-project setup of the solution, additional arguments need to be passed to dotnet ef migrations add. It needs -s to specify the startup project as DragaliaAPI.csproj due to this project having ApiContext in the service container, but it also needs -p to specify DragaliaAPI.Database.csproj as the project containing the database model. You can skip one of these arguments by running the dotnet ef command inside either the main project folder or the database project folder, and then you only have to supply the relative path to the other project file. For example, from the database project folder you can run:

dotnet ef migrations add name -s ..\DragaliaAPI\DragaliaAPI.csproj

Naming convention

Migrations should be named after the version they are applied against, and there is then a suffixed number to differentiate subsequent migrations in a version. Note that the EF Core tools will automatically prefix a timestamp. For example:

20221223145417_1-0-0_alpha_1 (given name: 1-0-0_alpha_1)
20221223145417_1-0-0_alpha_2
20221223145417_1-0-0_alpha_3

20221223145417_1-1-0_alpha_1
20221223145417_1-1-0_alpha_2

Applying a migration

If the ASPNETCORE_ENVIRONMENT env var is 'Development' or 'Staging', then migrations are applied automatically on startup. Running with Docker locally, this is set automatically by docker-compose-override.yaml. In other words, you don't have to worry about applying migrations manually in the development environment.

If you wish to deploy to production, you may find this resource from Microsoft about managing migrations to be useful. The recommended way is with SQL scripts that are carefully reviewed to ensure no data loss occurs, and of course with plenty of backups.