Diff db-docs and ps/migrations #594
Conversation
Deploying contributing-docs with
|
| Latest commit: |
df46729
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://6715d308.contributing-docs.pages.dev |
| Branch Preview URL: | https://db-docs-diff.contributing-docs.pages.dev |
|
Great job, no security vulnerabilities found in this Pull Request |
| If you alter the database schema, you must create an EF migration script to ensure that EF databases | ||
| keep pace with these changes. Developers must do this and include the migrations with their PR. | ||
|
|
||
| To create these scripts, you must first update your data model in `Core/Entities` as desired. This | ||
| will be used to generate the migrations for each of our EF targets. | ||
| will be used to generate the migrations for each of our EF targets. Additionally, for table changes | ||
| it is strongly recommended to define or update an `IEntityTypeConfiguration<T>` to accurately |
There was a problem hiding this comment.
This seems out of place, it's not directly related to migrations but general EF best practices.
There was a problem hiding this comment.
Where would it go then? I feel like the prior existing sentence is in the same camp, but both need to be modified for migrations so I put it here.
| We use a [SDK-style SQL project][MSBuildSQL] (`sqlproj`) to develop the database locally. This means | ||
| we have an up-to-date representation of the database in `src/Sql`, and any modifications needs to be | ||
| represented there as well. SDK-style SQL projects are still in preview the tooling is not yet | ||
| available in Visual Studio. However it is available in [Visual Studio Code][vscode] and [Azure Data | ||
| Studio][azureds] with the [SQL Database Projects][SDPE] extension, which provides schema comparison | ||
| and more. You may also modify the `.sql` files directly with any text editor. | ||
| We recommend reading [T-SQL Code Style](../code-style/sql.md) since it has a major impact in how we | ||
| write migrations. | ||
|
|
||
| To make a database change, start by modifying the `.sql` files in `src/Sql/dbo`. These changes will | ||
| also need to be applied in a migration script. Migration scripts are located in | ||
| `util/Migrator/DbScripts`. | ||
| ::: | ||
|
|
||
| You can either generate the migration scripts automatically using the _Schema Comparison_ | ||
| functionality or by manually writing them. Do note that the automatic method will only take you so | ||
| far and it will need to be manually edited to adhere to the code styles. | ||
| ## SQL database project | ||
|
|
||
| For added safe guards we have automated linting and validation to ensure the SQL project is always | ||
| up to date with the migrations. |
There was a problem hiding this comment.
I prefer my section it explains the SQL project with links to references and how they relate to DbScripts.
There was a problem hiding this comment.
Grabbed most of it with some removals due to what exists today.
| It is likely that a change does not require a non-backwards-compatible end phase e.g. all changes | ||
| may be backwards-compatible in their final form; in that case, only one phase of changes is |
There was a problem hiding this comment.
One issue with our existing DB model is that we've gravitated towards making every field optional. I don't see that as a. best practice and one of the dangers of almost always only using backwards compatible migrations.
There was a problem hiding this comment.
Neither do I see it as one.
| ### [Not Yet Implemented] Manual MSSQL migrations | ||
|
|
||
| There may be a need for a migration to be run outside of our normal update process. These types of | ||
| migrations should be saved for very exceptional purposes. One such reason could be an Index rebuild. | ||
|
|
||
| 1. Write a new Migration with a prefixed current date and place it in | ||
| `src/Migrator/DbScripts_manual` | ||
| 2. After it has been run against our Cloud environments and we are satisfied with the outcome, | ||
| create a PR to move it to `DbScripts`. This will enable it to be run by our Migrator processes in | ||
| self-host and clean installs of both cloud and self-host environments |
There was a problem hiding this comment.
Have we determined we will never do this?
There was a problem hiding this comment.
I'd say yes. It's problematic for self-host. Things like this just aren't added to source control if they have no auditable change. A rebuild could be done, but that isn't necessary in the source as it is transient.
| If you alter the database schema, you must create an EF migration script to ensure that EF databases | ||
| keep pace with these changes. Developers must do this and include the migrations with their PR. | ||
|
|
||
| To create these scripts, you must first update your data model in `Core/Entities` as desired. This | ||
| will be used to generate the migrations for each of our EF targets. | ||
| will be used to generate the migrations for each of our EF targets. Additionally, for table changes | ||
| it is strongly recommended to define or update an `IEntityTypeConfiguration<T>` to accurately |
There was a problem hiding this comment.
Where would it go then? I feel like the prior existing sentence is in the same camp, but both need to be modified for migrations so I put it here.
| We use a [SDK-style SQL project][MSBuildSQL] (`sqlproj`) to develop the database locally. This means | ||
| we have an up-to-date representation of the database in `src/Sql`, and any modifications needs to be | ||
| represented there as well. SDK-style SQL projects are still in preview the tooling is not yet | ||
| available in Visual Studio. However it is available in [Visual Studio Code][vscode] and [Azure Data | ||
| Studio][azureds] with the [SQL Database Projects][SDPE] extension, which provides schema comparison | ||
| and more. You may also modify the `.sql` files directly with any text editor. | ||
| We recommend reading [T-SQL Code Style](../code-style/sql.md) since it has a major impact in how we | ||
| write migrations. | ||
|
|
||
| To make a database change, start by modifying the `.sql` files in `src/Sql/dbo`. These changes will | ||
| also need to be applied in a migration script. Migration scripts are located in | ||
| `util/Migrator/DbScripts`. | ||
| ::: | ||
|
|
||
| You can either generate the migration scripts automatically using the _Schema Comparison_ | ||
| functionality or by manually writing them. Do note that the automatic method will only take you so | ||
| far and it will need to be manually edited to adhere to the code styles. | ||
| ## SQL database project | ||
|
|
||
| For added safe guards we have automated linting and validation to ensure the SQL project is always | ||
| up to date with the migrations. |
There was a problem hiding this comment.
Grabbed most of it with some removals due to what exists today.
| It is likely that a change does not require a non-backwards-compatible end phase e.g. all changes | ||
| may be backwards-compatible in their final form; in that case, only one phase of changes is |
There was a problem hiding this comment.
Neither do I see it as one.
| ### [Not Yet Implemented] Manual MSSQL migrations | ||
|
|
||
| There may be a need for a migration to be run outside of our normal update process. These types of | ||
| migrations should be saved for very exceptional purposes. One such reason could be an Index rebuild. | ||
|
|
||
| 1. Write a new Migration with a prefixed current date and place it in | ||
| `src/Migrator/DbScripts_manual` | ||
| 2. After it has been run against our Cloud environments and we are satisfied with the outcome, | ||
| create a PR to move it to `DbScripts`. This will enable it to be run by our Migrator processes in | ||
| self-host and clean installs of both cloud and self-host environments |
There was a problem hiding this comment.
I'd say yes. It's problematic for self-host. Things like this just aren't added to source control if they have no auditable change. A rebuild could be done, but that isn't necessary in the source as it is transient.
🎟️ Tracking
📔 Objective
⏰ Reminders before review
team
🦮 Reviewer guidelines
:+1:) or similar for great changes:memo:) or ℹ️ (:information_source:) for notes or general info:question:) for questions:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmedissue and could potentially benefit from discussion
:art:) for suggestions / improvements:x:) or:warning:) for more significant problems or concerns needing attention:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt:pick:) for minor or nitpick changes