From 6c5bba19f9a2c6e21f47a306822ce60df900c37d Mon Sep 17 00:00:00 2001 From: Quentin Gliech Date: Thu, 4 Dec 2025 15:14:33 +0100 Subject: [PATCH] Developer documentation for modifying or removing database migrations --- docs/development/database.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/development/database.md b/docs/development/database.md index 5ffe8a5a8..91bd7f9fa 100644 --- a/docs/development/database.md +++ b/docs/development/database.md @@ -40,7 +40,7 @@ cargo sqlx prepare ## Migrations -Migration files live in the `migrations` folder in the `mas-core` crate. +Migration files live in the `migrations` folder in the `mas-storage-pg` crate. ```sh cd crates/storage-pg/ # Again, in the mas-storage-pg crate folder @@ -50,3 +50,29 @@ cargo sqlx migrate add [description] # Add new migration files ``` Note that migrations are embedded in the final binary and can be run from the service CLI tool. + +### Removing migrations + +For various reason, we may want to delete migrations. +In case we do, we *must* declare that migration version as it is fine to be missing. +This is because on startup, MAS will validate that all the applied migrations are known, and warn if some are missing. + +To do so, get the migration version and add it to the `ALLOWED_MISSING_MIGRATIONS` array in the `mas-storage-pg` crate. + +### Modifying existing migrations + +We may want to modify existing migrations to fix mistakes. +In case we do, we *must* save the hash of the original migration file so that MAS can validate it on startup. + +To do so, extract the first 16 bytes of the existing applied migration and append it to the `ALLOWED_ALTERNATE_CHECKSUMS` array in the `mas-storage-pg` crate. + +```sql +SELECT version, ENCODE(SUBSTRING(checksum FOR 16), 'hex') AS short_checksum +FROM _sqlx_migrations +WHERE version = 20250410000002; +``` +``` + version | short_checksum +----------------+---------------------------------- + 20250410000002 | f2b8f120deae27e760d079a30b77eea3 +```