db/README.md
This tooling is built on top of doctrine/migrations.
The tool's built-in help system (passing --help to any of the commands) is ground truth.
Use ./cli list migrations to show all available migrations commands.
We are in the process of overhauling CLI and module-related tooling, so this covers the current state of things.
[!IMPORTANT] The Doctrine Migrations system is NOT fully integrated into OpenEMR yet. Don't make database changes using this until #10708 is completed (at minimum).
Run ./cli migration:generate.
Edit the file it creates.
Migrations will automatically have a timestamp applied to the file name, and will be run in sequential order. Be aware of the order of operations.
Aim to limit any given migration to a single table if possible. Multiple, smaller migrations are easier to test and review. Exercise good judgment when to make mode widespread changes within a single migration.
[!WARNING] This will result in schema changes to your database. Certain changes may take a long time to execute, which could lead to service interruptions.
Run ./cli migrate, and follow the prompts.
[!CAUTION] Reverting (rolling back) a migration is highly likely to lead to data loss!
Under some circumstances, you may need to roll back a migration. This is mostly used during development where you are iterating on the final schema changes, and should be very rare in production environments.
Run ./cli migrate prev to run the "down" path of the most recent migration.
[!NOTE] Not all migrations will support a roll back procedure.
To continue rolling back changes, you may run the same command more than one time. The CLI also supports migrating to a specific version; see its built-in help system for details.
Once a migration script has made it into a tagged release, it may not be altered again1. Doing so will lead to different installations having inconsistent schemas, which makes management and development extremely error-prone.
Make changes with a new migration that runs on top of the released migration to "roll forward" to the desired state.
Minor syntactical adjustments are OK as long as the produced schema does not change. Usually updating class imports due to a refactor, etc. This should still be fairly rare. ↩