🧱 Database Migration

Overview

This document describes the steps required to migrate an existing dataset from a database or revert a migration. Migrations should take place whenever the persistent data schema changes, to avoid errors and data loss.

Format

• Migrations should be create inside scripts/migrations
• Migrations should extend BaseMigration and implement up and down methods
• Each migration should be documented using module docstrings
• Each migration file should be named following this format:

  yyyy_mm_dd__table_name__change_description.py
  

  Example:

  2025_04_20__songs__seconds_to_seconds_duration.py
  

Requirements

• Backend/ should be the root folder
• Backend setup must be done before running any script

➡️ Migrate (Up)

This procedure will apply a migration on a dataset.

1. Go to Backend/
2. Create a migration file that extends BaseMigration class under app/scripts/migrations
3. Write module docs at the top of the file describing what the migration does
4. Add the following entrypoint:

   migration = Migration()
   asyncio.run(migration.execute_migration())
   

5. Run python -m app.scripts.migrations.migration_file db_uri up. Example:

   python -m app.scripts.migrations.migration_file mongodb://root:root@127.0.0.1:27017/ db_uri up
   

🔙 Revert Migration (Down)

This procedure will revert a migration on a dataset.

1. Follow the same steps as for doing a migration but instead execte this code:

   python -m app.scripts.migrations.migration_file mongodb://root:root@127.0.0.1:27017/ db_uri down