Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-01-11 00:08:30 +01:00
Code Issues Projects Releases Wiki Activity

chore: update database migration ADR (#6036)

Browse Source 
## Key Updates in the ADR

- **Separation of Migrations in PRs**: Migrations are now required to be
carried out in separate pull requests. This change is intended to
improve the monitoring and management of database schema changes during
deployment.

- **Primary Key Requirement for New Tables**: A new paragraph mandates
the inclusion of primary keys in all new tables, emphasizing the
importance of data integrity, efficient data retrieval, and supporting
table relationships. Additionally, by adding primary keys, we resolve
the issue of migrations failing during upgrades in replicated database
setups, as we are not using PostgreSQL replica identities. Exceptions to
this rule require a compelling justification.


Also added better structuring and styling to ADR for better readability.
This commit is contained in:
Jaanus Sellin 2024-01-30 11:07:32 +02:00 committed by GitHub
parent 7d6d4064a8
commit febd01a575
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 23 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
website/docs/contributing/ADRs/back-end/breaking-db-changes.md
View File

@ -11,19 +11,31 @@ The very same problem occurs when you apply a breaking migration just before the
The code is still running against the old schema as the migration takes a few seconds to apply.
## Decision
To address these challenges, follow these guidelines:
First please make sure to avoid breaking DB changes in the first place if possible.
### Avoid Breaking DB Changes
- **Prioritize avoiding breaking changes** in the DB schema whenever possible.
If breaking change is inevitable please use the "expand/contract" pattern.
### Use the "Expand/Contract" Pattern
If breaking changes are inevitable, use the "expand/contract" pattern:
In the "expand phase":
* maintain old and new DB schema in parallel
* maintain code that works with old and new DB schema
* keep it for 2 minor releases to give all clients a chance to upgrade the code
* with a fallback of 2 version we can also downgrade in this range without running down migrations
#### Expand Phase
- **Maintain both old and new DB schemas** in parallel.
- Ensure **code compatibility with both schemas**.
- Keep dual compatibility for **at least 2 minor releases**, allowing client upgrades.
- This approach also supports **downgrading within this version range** without reverting migrations.
In the "contract phase":
* remove the old schema when you know that no client is using the old version
#### Contract Phase
- **Remove the old DB schema** once no clients use the old version.
Action for a code reviewer:
* when you spot a migration with `ALTER table DROP COLUMN` or `ALTER table RENAME TO` please raise a flag if the "expand phase" was missed
### Code Reviewer Responsibilities
- **Action for a Code Reviewer:** When you spot a migration with `ALTER TABLE DROP COLUMN` or `ALTER TABLE RENAME TO`, please raise a flag if the "expand phase" was missed.
### Separate Migrations as Distinct PRs
- Carry out all migrations in **separate pull requests (PRs)** and closely monitor them during deployment. Monitoring should be performed using Grafana, observing any failing requests or errors in the logs.
### Primary Key Requirement for New Tables
- All new tables must have a primary key to ensure data integrity, improve query efficiency, and establish foreign key relationships. Primary keys also address migration issues in replicated databases without PostgreSQL replica identities. Exceptions require strong justification.
Following these guidelines reduces the risk of errors and compatibility issues during DB schema changes, enhancing stability and reliability in software development.