case study 01 / migrax
Open source · Java CLI
Migrax
Generates SQL migrations from JPA entities, then lints them for table locks and data-loss risks before they reach production.
migrax · CLI · Maven / Gradle plugin
- Hibernate 5.4 – 7.4 · 6 databases
- SQL + rollback · drift detection
Problem
Entities change in Java, but the migration that changes the database is still written by hand. A hand-written ALTER can lock a large table, fail on existing rows, or break instances still running the old code — and that usually shows up in production, not review.
Design
Migrax is a Java 17+ tool that reads JPA entities, compares them with the database, and writes plain SQL plus a rollback script. Each supported Hibernate version (5.4 to 7.4) reads its own mapping, so tables, keys, indexes, join tables, element collections, sequences, and inheritance match what Hibernate expects. No configuration files: it compiles the project, finds dependencies, and reads database settings from the application config.
Path
- 01Change JPA entities
- 02migrax generate
- 03Review SQL + rollback
- 04migrax verify
- 05migrax migrate
Constraints
- Early release (0.1.x), MIT licensed.
- Requires Java 17+.
- Supports PostgreSQL, MySQL 8, MariaDB, SQL Server, Oracle 12c+, and H2.
Decisions
Plain SQL, not a black box
Every migration is SQL you can read and edit before it runs, with a rollback script next to it.
Lint before it ships
Statements that lock large tables, fail on existing rows, or break running instances are flagged before the migration reaches production.
Destructive changes are opt-in
When a dropped column looks like a rename, Migrax asks and renames it to keep the data. Drops only happen with --allow-destructive.
Limits
- Lint flags known risk patterns; a clean lint is not a guarantee that a migration is safe on every dataset.
- verify proves the rollback works against your Hibernate version — it does not replace testing with production-sized data.