DEV Community: Feroz Shah

Applying and undoing migrations: migrate, status, rollback

Feroz Shah — Sun, 25 Oct 2026 16:23:55 +0000

migrax generate writes migrations, and three commands handle the rest: status shows what the database has, migrate applies what is missing, and rollback undoes it. This article goes through each one on a real project. It also covers what a rollback can and can't bring back, and what happens when someone edits a migration that already ran.

Tested with: Migrax 0.17.1, Hibernate 6.6.13, PostgreSQL 17. Every output below was copied from a real run.

Where we start

The shop project from the earlier articles has four applied migrations: the first tables, a phone column, and the two renames from Renaming columns and tables without losing data. Now two more entity changes come in: a notes field on PurchaseOrder, and an index on its createdAt column.

@Entity
@Table(name = "purchase_orders",
    indexes = @Index(name = "ix_orders_created", columnList = "createdAt"))
public class PurchaseOrder {
  ...
  @Column(length = 500)
  String notes;
}

Running migrax generate once per change gives two files: 0005_add_purchase_orders_notes.sql and 0006_index_purchase_orders.sql.

`status`: what has the database got?

$ migrax status
Migrations in src/main/resources/db/migration for jdbc:postgresql://localhost:5432/shop
  [X] 0001_initial.sql                    applied 2026-10-25 16:04:44
  [X] 0002_add_customers_phone.sql        applied 2026-10-25 16:04:58
  [X] 0003_rename_customers_name.sql      applied 2026-10-25 16:06:06
  [X] 0004_rename_orders.sql              applied 2026-10-25 16:07:06
  [ ] 0005_add_purchase_orders_notes.sql  pending
  [ ] 0006_index_purchase_orders.sql      pending
4 applied, 2 pending.

[X] is applied, [ ] is pending. Migrax keeps the history in a migrax_history table in the same database, with a checksum of every applied file. status only reads; it never changes anything. The alias showmigrations does the same.

Before applying: `--dry-run` and `--sql`

--dry-run lists what would run and checks it for risky SQL, without touching the database:

$ migrax migrate --dry-run
2 migration(s) would be applied:
  0005_add_purchase_orders_notes.sql
  0006_index_purchase_orders.sql
src/main/resources/db/migration/0006_index_purchase_orders.sql, statement 1: warning MX001
  CREATE INDEX ix_orders_created ON purchase_orders (createdAt)
  Building this index blocks writes to purchase_orders until it finishes.
  Fix: Use CREATE INDEX CONCURRENTLY in its own migration that starts with '-- migrax:no-transaction' ('migrax generate --safe' does this).

On a small table that warning doesn't matter. On a table with millions of rows, it is the difference between a quick deploy and minutes of blocked writes. The lint rules page lists every check.

If a DBA has to run the changes, --sql prints one script for them. It applies each migration in its own transaction and records it in the history, so Migrax sees it as applied afterwards:

$ migrax migrate --sql
-- Migration script written by Migrax: 2 migration(s) to apply.
-- Review it, then run the whole file with the database's own tool; it must stop
-- at the first error:
--   psql -v ON_ERROR_STOP=1 -f <this file>
-- Each migration is recorded in migrax_history, so 'migrax status' and later
-- 'migrax migrate' runs see it as applied.

-- 0005_add_purchase_orders_notes.sql
BEGIN;
-- Generated by Migrax 0.17.1 for postgresql

ALTER TABLE purchase_orders ADD COLUMN notes varchar(500);
INSERT INTO migrax_history(version,checksum,applied_at) VALUES('0005_add_purchase_orders_notes.sql','5f26d7ff0f5e8502d49b57c00fd7449f0619bcf7d8f38441f006fcd261904837',(CURRENT_TIMESTAMP AT TIME ZONE 'Etc/UTC'));
COMMIT;

-- 0006_index_purchase_orders.sql
...

`migrate`: all at once, or up to a point

migrax migrate applies every pending migration in order. --to stops after the one you name:

$ migrax migrate --to 0005_add_purchase_orders_notes.sql
Applying migration '0005_add_purchase_orders_notes.sql'...
Successfully applied migration '0005_add_purchase_orders_notes.sql'.
Applied 1 migration(s) up to 0005_add_purchase_orders_notes.sql.
1 migration(s) after it stay pending.

$ migrax migrate
Applying migration '0006_index_purchase_orders.sql'...
Successfully applied migration '0006_index_purchase_orders.sql'.
Applied 1 migration(s); 6 total in src/main/resources/db/migration.

On PostgreSQL each migration runs in a transaction. If a statement fails, that migration is rolled back as a whole and migrate stops. Migrax also takes a lock on the database while it works, so two application instances that start at the same moment don't both apply the same migration.

`rollback`: undoing the newest migrations

Every generated migration has a rollback script next to it, in rollback/. migrax rollback runs the script of the newest applied migration and removes that migration from the history.

Because a rollback can delete data, Migrax wants a confirmation. In a terminal it asks:

$ migrax rollback
Rolling back 1 migration(s), newest first:
  0006_index_purchase_orders.sql
Roll back now? Data written to removed objects is lost. [y/N] y
Rolling back migration '0006_index_purchase_orders.sql'...
Rolled back migration '0006_index_purchase_orders.sql'.
Rolled back 1 migration(s).

In a script or CI job it stops instead, until you add --yes:

$ migrax rollback
Rolling back 1 migration(s), newest first:
  0006_index_purchase_orders.sql
error[MXE001]: Rollback needs confirmation.
Back up the database, then rerun with --yes.

--steps n undoes the newest n migrations. --dry-run shows the list first:

$ migrax rollback --steps 2 --dry-run
Would roll back 2 migration(s), newest first:
  0006_index_purchase_orders.sql
  0005_add_purchase_orders_notes.sql

--to keeps the migration you name and undoes everything after it:

$ migrax rollback --to 0003_rename_customers_name.sql --yes
Rolling back 3 migration(s), newest first:
  0006_index_purchase_orders.sql
  0005_add_purchase_orders_notes.sql
  0004_rename_orders.sql
Rolling back migration '0006_index_purchase_orders.sql'...
Rolled back migration '0006_index_purchase_orders.sql'.
Rolling back migration '0005_add_purchase_orders_notes.sql'...
Rolled back migration '0005_add_purchase_orders_notes.sql'.
Rolling back migration '0004_rename_orders.sql'...
Rolled back migration '0004_rename_orders.sql'.
Rolled back 3 migration(s).

Rolled-back migrations are pending again, so the next migrax migrate applies them again. The files stay where they are.

What a rollback can't bring back

A rollback restores the structure, not the data. Say someone stores a note on an order:

UPDATE purchase_orders SET notes = 'Gift wrap, please' WHERE id = 2;

Rolling back 0005 drops the notes column. Applying it again brings an empty column back, and the note is gone:

 id | notes
----+-------
  1 |
  2 |
  3 |

The rollback script says so in its header, so it shows in review before anything runs:

db/migration/rollback/0005_add_purchase_orders_notes.sql:

-- Generated by Migrax 0.17.1 for postgresql
-- Rollback for 0005_add_purchase_orders_notes.sql. 'migrax rollback' runs it.
-- Note: deletes data written to purchase_orders.notes since the migration ran.

ALTER TABLE purchase_orders DROP COLUMN notes;

The same applies the other way round: when a migration drops a column, its rollback can re-create the column but not its old values. To keep those, generate that migration with --keep-data. Migrax then copies the values into a backup table first, and the rollback puts them back (Rollbacks and recovery).

Don't edit a migration that already ran

Migrax stores a checksum of each applied file. If someone changes the file afterwards, even just by adding a comment, status shows it and exits with code 1:

$ migrax status
Migrations in src/main/resources/db/migration for jdbc:postgresql://localhost:5432/shop
  [X] 0001_initial.sql                    applied 2026-10-25 16:04:44
  [X] 0002_add_customers_phone.sql        applied 2026-10-25 16:04:58
  [X] 0003_rename_customers_name.sql      applied 2026-10-25 16:06:06
  [X] 0004_rename_orders.sql              applied 2026-10-25 16:08:46
  [!] 0005_add_purchase_orders_notes.sql  CHANGED: file changed after it was applied 2026-10-25 16:08:46
  [X] 0006_index_purchase_orders.sql      applied 2026-10-25 16:08:46
5 applied, 1 changed.
Some migrations need attention. See 'migrax help repair'.

migrate refuses to run at all:

$ migrax migrate
error[MXE104]: Checksum changed for applied migration 0005_add_purchase_orders_notes.sql
Run again with --verbose for details.

This protects you from a database that no longer matches its files: the edited SQL never ran on the databases that already applied the old version. Put the file back as it was (here, git checkout of the file) and write any new change as a new migration.

Summary

migrax status shows applied, pending and changed migrations, and never changes anything.
migrax migrate applies pending migrations in order. --dry-run previews and lints, --sql writes a script for a DBA, and --to stops at a given migration.
migrax rollback undoes the newest migrations (--steps, --to). It asks first, and needs --yes in scripts.
Rollbacks restore structure, not data. The rollback script's header says what gets lost, and --keep-data keeps it.
Never edit an applied migration. Write a new one.

More in the guides: Rollbacks and recovery and Production safety, which shows how migrax verify tests every rollback script before release.

Originally published at migrax.org.

Renaming columns and tables without losing data

Feroz Shah — Sun, 25 Oct 2026 16:22:41 +0000

Renames are where generated migrations usually go wrong. When a field changes from name to fullName, the database only sees one column disappear and another appear. A tool that just compares the two schemas drops the old column, and every value in it, then adds an empty new one.

Migrax notices when a change looks like a rename. In a terminal it asks you. In CI, where no one can answer, it refuses to write a migration that would lose the data. This article shows both cases for a column and for a table, and how to undo a rename.

Tested with: Migrax 0.17.1, Hibernate 6.6.13, PostgreSQL 17. Every output below was copied from a real run.

Where we start

This picks up where Generate SQL migrations from your JPA entities ended: a customers table and an orders table, two migrations applied, and a few rows of data:

      email       | id |     name     |      phone
------------------+----+--------------+------------------
 ada@example.com  |  1 | Ada Lovelace | +44 20 7946 0001
 alan@example.com |  2 | Alan Turing  |

Each order points at its customer through a foreign key.

Renaming a column

Rename the field in Customer:

  @Column(name = "full_name", nullable = false, length = 100)
  String fullName;

In CI: Migrax refuses

First, run generate where nobody can answer a question, such as a CI job or a script:

$ migrax generate
Possible rename: customers.name to customers.full_name. To keep the data, rerun with --rename customers.name=full_name.
2 change(s) for postgresql:
  1. drop column customers.name  [DESTRUCTIVE]
     ALTER TABLE customers DROP COLUMN name;
  2. add column customers.full_name
     ALTER TABLE customers ADD COLUMN full_name varchar(100) NOT NULL;
error[MXE108]: 1 destructive change(s) detected (marked [DESTRUCTIVE] above).
Review them, then run 'migrax generate --allow-destructive'. If a column or table was renamed, pass --rename table.old=new or --rename-table old=new instead.

It exits with code 1 and writes no file. Here, writing the plain drop and add would have been doubly wrong. It would have deleted both names. Then ADD COLUMN ... NOT NULL would have failed anyway, because the existing rows have no value for the new column.

The first line gives the option that keeps the data.

In a terminal: Migrax asks

Run the same command in a terminal and Migrax asks instead:

$ migrax generate
Did you rename customers.name to customers.full_name? [y/N] y
Created src/main/resources/db/migration/0003_rename_customers_name.sql:
  - rename column customers.name to full_name
Rollback script written to src/main/resources/db/migration/rollback.
src/main/resources/db/migration/0003_rename_customers_name.sql, statement 1: warning MX008
  ALTER TABLE customers RENAME COLUMN name TO full_name
  Application instances still running the old code use the old name and will fail.
  Fix: Rename in steps: add the new name, write to both, switch reads, then remove the old name ('migrax generate --zero-downtime' does this). Or deploy during a maintenance window.
Review the SQL, then run 'migrax migrate'.

The default is "no". If you just press Enter, Migrax treats the change as a drop and an add, and refuses as in CI.

The same answer as an option

In a script, give the answer up front with --rename table.old=new:

$ migrax generate --rename customers.name=full_name
Created src/main/resources/db/migration/0003_rename_customers_name.sql:
  - rename column customers.name to full_name

It writes exactly the same files as the "y" answer. Both runs above created byte-identical migrations. Separate several column renames with commas.

The migration

db/migration/0003_rename_customers_name.sql:

-- Generated by Migrax 0.17.1 for postgresql

ALTER TABLE customers RENAME COLUMN name TO full_name;

db/migration/rollback/0003_rename_customers_name.sql:

-- Generated by Migrax 0.17.1 for postgresql
-- Rollback for 0003_rename_customers_name.sql. 'migrax rollback' runs it.

ALTER TABLE customers RENAME COLUMN full_name TO name;

A rename moves no data, so it is fast even on a large table. Apply it, and the names are still there:

$ migrax migrate
Applying migration '0003_rename_customers_name.sql'...
Successfully applied migration '0003_rename_customers_name.sql'.
Applied 1 migration(s); 3 total in src/main/resources/db/migration.

 id |  full_name   |      email
----+--------------+------------------
  1 | Ada Lovelace | ada@example.com
  2 | Alan Turing  | alan@example.com

How Migrax spots a rename

It treats a dropped column and an added column in the same table as a possible rename when:

they are the same name in another style, like created_at and createdAt (even when the type changed too), or
the new column has the same type as the old one.

A rename that also changes the type becomes a RENAME followed by an ALTER.

Renaming a table

Now rename the orders table:

@Entity
@Table(name = "purchase_orders")
public class PurchaseOrder {

A table rename has one more catch. Hibernate puts the table name into the names of the foreign keys it creates, so renaming the table changes the key's name too. Without an answer, Migrax again sees a drop and refuses:

$ migrax generate
Possible rename: table orders to purchase_orders. To keep the data, rerun with --rename-table orders=purchase_orders.
4 change(s) for postgresql:
  1. drop foreign key fk_orders_customer_id_54d4cc52 on orders  [DESTRUCTIVE]
     ALTER TABLE orders DROP CONSTRAINT fk_orders_customer_id_54d4cc52;
  2. create table purchase_orders
     CREATE TABLE purchase_orders (createdAt timestamp(6) with time zone, customer_id bigint NOT NULL, id bigint GENERATED BY DEFAULT AS IDENTITY NOT NULL, total numeric(12,2) NOT NULL, CONSTRAINT purchase_orders_pkey PRIMARY KEY (id));
  3. drop table orders  [DESTRUCTIVE]
     DROP TABLE orders;
  4. add foreign key fk_purchase_orders_cu_1ba47d9c on purchase_orders
     ALTER TABLE purchase_orders ADD CONSTRAINT fk_purchase_orders_cu_1ba47d9c FOREIGN KEY (customer_id) REFERENCES customers (id);
error[MXE108]: 2 destructive change(s) detected (marked [DESTRUCTIVE] above).
Review them, then run 'migrax generate --allow-destructive'. If a column or table was renamed, pass --rename table.old=new or --rename-table old=new instead.

Answer "y" in a terminal, or pass --rename-table orders=purchase_orders (both write the same files again):

$ migrax generate
Did you rename table orders to purchase_orders? [y/N] y
Created src/main/resources/db/migration/0004_rename_orders.sql:
  - rename table orders to purchase_orders
  - rename foreign key fk_orders_customer_id_54d4cc52 to fk_purchase_orders_cu_1ba47d9c on purchase_orders
Rollback script written to src/main/resources/db/migration/rollback.

(The MX008 warning from before appears here too.)

db/migration/0004_rename_orders.sql:

-- Generated by Migrax 0.17.1 for postgresql

ALTER TABLE orders RENAME TO purchase_orders;
ALTER TABLE purchase_orders RENAME CONSTRAINT fk_orders_customer_id_54d4cc52 TO fk_purchase_orders_cu_1ba47d9c;

The foreign key keeps its columns and its target and only gets its new name. On PostgreSQL, CockroachDB, YugabyteDB and H2 that is a RENAME CONSTRAINT, which is instant. Other databases can't rename a foreign key, so there Migrax drops the key and adds it again under the new name. That makes the database check every row once. Before Migrax 0.17.1, a table rename needed --allow-destructive because of this key. Now the answer to the rename question is enough.

After migrax migrate, the orders still belong to the same customers:

 id |  full_name   | total
----+--------------+--------
  1 | Ada Lovelace |  49.90
  2 | Ada Lovelace | 120.00
  3 | Alan Turing  |  15.50

migrax drift agrees that the database matches the entities:

$ migrax drift
No drift: the database matches the snapshot.

Undoing a rename

The rollback script renames everything back, foreign key included:

db/migration/rollback/0004_rename_orders.sql:

ALTER TABLE purchase_orders RENAME CONSTRAINT fk_purchase_orders_cu_1ba47d9c TO fk_orders_customer_id_54d4cc52;
ALTER TABLE purchase_orders RENAME TO orders;

$ migrax rollback --yes
Rolling back 1 migration(s), newest first:
  0004_rename_orders.sql
Rolling back migration '0004_rename_orders.sql'...
Rolled back migration '0004_rename_orders.sql'.
Rolled back 1 migration(s).

A rename moves no data, so undoing it loses none either. migrax migrate applies it again.

A rename while the old code still runs

The MX008 warning is about deployment, not data. During a rolling deploy, instances of the old version keep running for a while. They still query customers.name and fail as soon as the column is renamed. You have two options:

deploy during a short maintenance window, so no old instance is left when the migration runs, or
rename in steps: add the new column, write to both, switch reads, then drop the old one. migrax generate --zero-downtime writes these steps for you (Zero-downtime changes).

Summary

Migrax spots likely renames and asks about them. It never drops data on a guess.
In CI it refuses with MXE108 and prints the exact --rename or --rename-table option to use.
A table rename also renames its foreign keys, in place where the database supports it.
Every rename has a rollback script that renames it back.

Generate SQL migrations from your JPA entities

Feroz Shah — Sun, 25 Oct 2026 16:20:15 +0000

Your JPA entities already describe the schema you want. Writing the same change again by hand as SQL is slow and easy to get wrong. Migrax compares your entities with the last state you committed and writes the SQL migration for you, along with a rollback script. You review the SQL, commit it, and apply it.

This article walks through that loop on a small project: create the first tables, add a column, and catch a missing migration in CI.

Tested with: Migrax 0.16.0, Hibernate 6.6.13, PostgreSQL 17. Every output below was copied from a real run.

The project

Two entities, a customer and an order:

@Entity
@Table(name = "customers")
public class Customer {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  Long id;

  @Column(nullable = false, unique = true, length = 150)
  String email;

  @Column(nullable = false, length = 100)
  String name;
}

@Entity
@Table(name = "orders")
public class PurchaseOrder {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  Long id;

  @ManyToOne(optional = false)
  Customer customer;

  @Column(nullable = false, precision = 12, scale = 2)
  BigDecimal total;

  Instant createdAt;
}

Migrax needs to know where the database is. In src/main/resources/application.properties:

migrax.url=jdbc:postgresql://localhost:5432/shop
migrax.user=shop
migrax.password=shop

A Spring Boot, Quarkus, Micronaut or Helidon project can skip this: Migrax reads the framework's own data source settings.

Install Migrax, then run migrax init and migrax doctor in the project folder. init creates the migration folder; doctor checks that the project compiles, finds the entities and reaches the database.

The first migration

$ migrax generate
No snapshot yet: using the current database schema as the baseline.
Created src/main/resources/db/migration/0001_initial.sql:
  - create table customers
  - create table orders
  - add foreign key fk_orders_customer_id_54d4cc52 on orders
Rollback script written to src/main/resources/db/migration/rollback.
Review the SQL, then run 'migrax migrate'.

Migrax reads the entities through Hibernate's own mapping, so the SQL matches what Hibernate expects, column types and constraint names included:

db/migration/0001_initial.sql:

-- Generated by Migrax 0.16.0 for postgresql

CREATE TABLE customers (email varchar(150) NOT NULL, id bigint GENERATED BY DEFAULT AS IDENTITY NOT NULL, name varchar(100) NOT NULL, CONSTRAINT customers_pkey PRIMARY KEY (id), CONSTRAINT uk_customers_email UNIQUE (email));
CREATE TABLE orders (createdAt timestamp(6) with time zone, customer_id bigint NOT NULL, id bigint GENERATED BY DEFAULT AS IDENTITY NOT NULL, total numeric(12,2) NOT NULL, CONSTRAINT orders_pkey PRIMARY KEY (id));
ALTER TABLE orders ADD CONSTRAINT fk_orders_customer_id_54d4cc52 FOREIGN KEY (customer_id) REFERENCES customers (id);

Next to it is the rollback script. It says which data a rollback would delete:

db/migration/rollback/0001_initial.sql:

-- Generated by Migrax 0.16.0 for postgresql
-- Rollback for 0001_initial.sql. 'migrax rollback' runs it.
-- Note: deletes data written to customers since the migration ran.
-- Note: deletes data written to orders since the migration ran.

ALTER TABLE orders DROP CONSTRAINT fk_orders_customer_id_54d4cc52;
DROP TABLE customers;
DROP TABLE orders;

Both are plain SQL files. Read them, change them if you want, and apply them:

$ migrax migrate
Applying migration '0001_initial.sql'...
Successfully applied migration '0001_initial.sql'.
Applied 1 migration(s); 1 total in src/main/resources/db/migration.

Migrax also wrote .migrax/snapshot.json: the schema your entities describe right now. Commit it with the migration files. The next generate compares against it, so it doesn't need a database to work out what changed.

Adding a column

Add a field to Customer:

  @Column(length = 30)
  String phone;

$ migrax generate
Created src/main/resources/db/migration/0002_add_customers_phone.sql:
  - add column customers.phone
Rollback script written to src/main/resources/db/migration/rollback.
Review the SQL, then run 'migrax migrate'.

db/migration/0002_add_customers_phone.sql:

ALTER TABLE customers ADD COLUMN phone varchar(30);

The file name describes the change. The rollback script is ALTER TABLE customers DROP COLUMN phone;. Apply it with migrax migrate, as before.

Keeping entities and migrations in sync

Someone will eventually change an entity and forget to generate the migration. Say a teammate renames the field name to fullName (column full_name) and pushes only the Java change. migrax check catches that without a database, so it fits in CI:

$ migrax check
2 entity change(s) have no migration:
  - drop column customers.name
  - add column customers.full_name
Run 'migrax generate' and commit the result.

It exits with code 2 when a migration is missing and 0 when everything matches:

$ migrax check
OK: entities match the snapshot.

Summary

Change an entity, run migrax generate, read the SQL, commit, run migrax migrate.
Every migration comes with a rollback script that says what data it would delete.
migrax check in CI catches entity changes that have no migration.

Originally published at migrax.org.

DEV Community: Feroz Shah

Applying and undoing migrations: migrate, status, rollback

Where we start

status: what has the database got?

Before applying: --dry-run and --sql

migrate: all at once, or up to a point

rollback: undoing the newest migrations

What a rollback can't bring back

Don't edit a migration that already ran

Summary

Renaming columns and tables without losing data

Where we start

Renaming a column

In CI: Migrax refuses

In a terminal: Migrax asks

The same answer as an option

The migration

How Migrax spots a rename

Renaming a table

Undoing a rename

A rename while the old code still runs

Summary

Generate SQL migrations from your JPA entities

The project

The first migration

Adding a column

Keeping entities and migrations in sync

Summary

`status`: what has the database got?

Before applying: `--dry-run` and `--sql`

`migrate`: all at once, or up to a point

`rollback`: undoing the newest migrations