adastra_api/docs/decisions/0002-database-migration-mongodb-to-mysql.md

ADR 0002: Database Migration — MongoDB to MySQL with Sequelize

Date: 2026-04-26 Status: Accepted

Context

The project initially used MongoDB (evidence: mongo:start/mongo:stop Docker scripts still present in package.json, and $oid ObjectId references in the original data export). MongoDB was likely chosen for its flexible schema during early prototyping.

As the data model stabilised and relational queries became more common (joins between users, jumps, canopies, drop zones, etc.), a relational database became a better fit. MySQL is a well-known, widely hosted relational database with strong Sequelize support.

Decision

Migrate to MySQL with Sequelize as the ORM. Sequelize provides:

• Model definitions with typed fields
• Migration system (sequelize-cli db:migrate) for schema versioning
• Seeders for initial reference data
• Relationship declarations (src/database/relationships/)

The mongo:start/mongo:stop npm scripts are legacy artefacts and can be removed when confirmed no longer needed.

Consequences

• Positive: Relational integrity enforced at the database level. Joins are first-class.
• Positive: Sequelize migrations provide a reproducible setup path (npm run setup:api).
• Negative: Less flexible schema than MongoDB — changes require migrations.
• Note: The original data was exported from MongoDB (documents with $oid fields) and re-imported into MySQL via a one-shot migration script. That script has since been removed from the frontend codebase.