DEV Community: Feroz Shah

Spring Boot: migrations at startup, health checks and metrics

Feroz Shah — Sun, 08 Nov 2026 06:23:23 +0000

Migrations are written in development, but they have to run wherever the application runs: on a colleague's laptop, in CI, in staging, in production. The simplest way to get there is to let the application apply them itself, each time it starts, before anything else touches the database.

This article adds the Migrax starter to a Spring Boot application, follows what happens at startup, starts two instances at once, and looks at what Actuator shows: a health check and Prometheus metrics. At the end, the pipeline runs the migrations instead of the application.

Tested with: Migrax 0.17.1, Spring Boot 3.5.7, Hibernate 6.6.33, Micrometer 1.15.5, PostgreSQL 17. Every output below was copied from a real run; log lines are shortened to the message.

The setup

A shop with two entities, Customer and PurchaseOrder. Besides the usual web and JPA starters, the application has Actuator, the Prometheus registry and the Migrax starter:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
<dependency>
  <groupId>org.migrax</groupId>
  <artifactId>migrax-spring-boot-starter</artifactId>
  <version>0.17.1</version>
</dependency>

application.properties has the database, Hibernate set to only check the schema, and the two Actuator endpoints used below:

spring.datasource.url=jdbc:postgresql://localhost:5432/shop
spring.datasource.username=shop
spring.datasource.password=${DB_PASSWORD}
spring.jpa.hibernate.ddl-auto=validate

management.endpoints.web.exposure.include=health,prometheus
management.endpoint.health.show-details=always

The migrations come from the entities. migrax init sets up the project (it reads the database settings from application.properties), and generate writes 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 purchase_orders
  - add foreign key fk_purchase_orders_cu_1ba47d9c on purchase_orders
Rollback script written to src/main/resources/db/migration/rollback.
Review the SQL, then run 'migrax migrate'.

The file sits in src/main/resources/db/migration, so it is packaged into the jar. That is where the starter looks.

What happens at startup

Start the application on the empty database:

HikariPool-1 - Start completed.
Migrax: Applying migration '0001_initial.sql'...
Migrax: Successfully applied migration '0001_initial.sql'.
Migrax: applied 1 migration(s)
Tomcat started on port 8080 (http) with context path '/'
Started ShopApplication in 9.05 seconds (process running for 10.302)

The order matters. The starter runs as soon as the connection pool is there and before JPA starts, so when Hibernate validates the schema, the tables already exist. With ddl-auto=validate, a database that doesn't match the entities stops the start, instead of failing on the first request.

Start it again and there is nothing to do:

Migrax: schema is up to date
Started ShopApplication in 8.571 seconds (process running for 9.58)

The application never needs the migrax command. It reads the migration files from the jar and records each one in the history table in the database, with a checksum.

Several instances starting together

A new field on Customer:

@Column(nullable = false, length = 2)
@ColumnDefault("'GB'")
private String country = "GB";

migrax generate writes 0002_add_customers_country.sql:

ALTER TABLE customers ADD COLUMN country varchar(2) DEFAULT 'GB' NOT NULL;

In production, the new version rarely starts alone: two or more instances start at the same moment. Only one of them may apply the migration. Migrax takes a lock in the database first (on PostgreSQL an advisory lock), and by default an instance that doesn't get it stops at once. Here are the two instances, started together:

--- instance 1
Migrax: Applying migration '0002_add_customers_country.sql'...
Migrax: Successfully applied migration '0002_add_customers_country.sql'.
Migrax: applied 1 migration(s)
Started ShopApplication in 10.515 seconds (process running for 11.809)

--- instance 2
Caused by: org.migrax.dialect.MigrationLockHeldException: Another Migrax process is applying migrations.

Nothing is broken: the migration ran once. But the second instance failed and has to be restarted, and an orchestrator counts that as a crash. Tell the instances to wait for each other instead:

migrax.lock-timeout=2m

To make the wait visible, the next run has more to do. The table now has two million customers, and an index on full_name is added to the entity (@Table(indexes = @Index(columnList = "fullName"))). generate writes it as 0003_index_customers.sql, and warns about it:

src/main/resources/db/migration/0003_index_customers.sql, statement 1: warning MX001
  CREATE INDEX idx_customers_full_name ON customers (full_name)
  Building this index blocks writes to customers until it finishes.
  Fix: Use CREATE INDEX CONCURRENTLY in its own migration that starts with '-- migrax:no-transaction' ('migrax generate --safe' does this).

Worth knowing on a busy table. Here it is fine. Both instances start again, with 0002 and 0003 pending (0002 was rolled back to run again):

--- instance 1
Migrax: Applying migration '0002_add_customers_country.sql'...
Migrax: Successfully applied migration '0002_add_customers_country.sql'.
Migrax: Applying migration '0003_index_customers.sql'...
Migrax: Successfully applied migration '0003_index_customers.sql'.
Migrax: applied 2 migration(s)
Started ShopApplication in 17.185 seconds (process running for 18.461)

--- instance 2
Migrax: Another Migrax process holds the migration lock; waiting up to 2m...
Migrax: schema is up to date
Started ShopApplication in 18.851 seconds (process running for 20.138)

The second instance waited until the first had built the index, found nothing left to do, and started. Set the timeout longer than your slowest migration takes; when it runs out, the instance stops as before.

The health check

With Actuator in the application, the starter adds a migrax health component:

$ curl -s localhost:8080/actuator/health/migrax
{"status":"UP","details":{"applied":3,"pending":0,"problems":0}}

problems counts migrations that failed, were edited after they were applied, or are in the history but no longer in the jar. Any of those, or a pending migration, makes the component DOWN. Turn it off with management.health.migrax.enabled=false.

An edited migration is the one people run into. Someone changes varchar(20) to varchar(30) in a migration that production has already applied, and the next start stops:

Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'migraxMigrator' defined in class path resource [org/migrax/spring/MigraxAutoConfiguration.class]: Checksum changed for applied migration 0004_add_purchase_orders_status.sql

The database already has the old version of that migration, and it never gets the new one. Leave applied migrations alone; a change goes into a new migration.

Metrics

The application has a Micrometer registry (here Prometheus), so Migrax records its migrations there without any setting. After the run above, the first instance shows:

$ curl -s localhost:8080/actuator/prometheus | grep ^migrax
migrax_lock_wait_seconds_max{database="default"} 0.044737607
migrax_migration_seconds_max{database="default",migration="0002_add_customers_country.sql",outcome="success"} 0.005012614
migrax_migration_seconds_max{database="default",migration="0003_index_customers.sql",outcome="success"} 6.10576425
migrax_migrations_applied_total{database="default"} 2.0
migrax_migrations_pending{database="default"} 0.0
migrax_run_seconds_max{database="default",outcome="success"} 6.212559502

(Only the _max lines of each timer are shown; _count and _sum are there too.) The second instance, the one that waited:

migrax_lock_wait_seconds_max{database="default"} 7.803599713
migrax_run_seconds_max{database="default",outcome="success"} 7.843474718

That answers the questions that come up after a slow deployment: which migration took the time (the index, 6.1 seconds), and how long the other instances waited for it (7.8 seconds). For an alert, the counter of failed migrations is the one to watch:

- alert: MigraxMigrationFailed
  expr: increase(migrax_migrations_failed_total[15m]) > 0

With an OpenTelemetry bean, each run and each migration also becomes a span in the trace of the startup. migrax.metrics.enabled=false and migrax.tracing.enabled=false turn them off.

When a pipeline migrates

Some teams don't let the application change the schema. A deployment pipeline or a DBA runs the migrations, and the application only reads. One setting:

migrax.migrate-at-startup=false

The order then becomes the pipeline's job. A new status column on PurchaseOrder, deployed before the pipeline has migrated, doesn't get far:

Migrax: not migrating at startup (migrax.migrate-at-startup=false); 1 migration(s) pending
Caused by: org.hibernate.tool.schema.spi.SchemaManagementException: Schema-validation: missing column [status] in table [purchase_orders]

That is ddl-auto=validate doing its job. So: run migrax migrate (or the Maven goal migrax:migrate) as a step before the new version starts:

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

Not every pending migration stops the start. An index isn't checked by Hibernate's validation, so a release with a forgotten index migration (0005) starts fine, and is slow. That is where the health check and the pending gauge come in, because they keep working when the application doesn't migrate:

$ curl -s -w ' HTTP %{http_code}\n' localhost:8080/actuator/health/migrax
{"status":"DOWN","details":{"applied":4,"pending":1,"problems":0}} HTTP 503

$ curl -s localhost:8080/actuator/prometheus | grep ^migrax
migrax_migrations_pending{database="default"} 1.0

An alert on the gauge catches a pipeline step that was skipped:

- alert: MigraxMigrationsPending
  expr: migrax_migrations_pending > 0
  for: 30m

To keep traffic away from such an instance on Kubernetes, add the component to the readiness group:

management.endpoint.health.probes.enabled=true
management.endpoint.health.group.readiness.include=readinessState,migrax

Once the pipeline has run migrax migrate, the application notices on its own. It asks the database at most every 10 seconds, so no restart is needed:

$ curl -s -w ' HTTP %{http_code}\n' localhost:8080/actuator/health/migrax
{"status":"UP","details":{"applied":5,"pending":0,"problems":0}} HTTP 200

Summary

Add migrax-spring-boot-starter, keep the migrations in src/main/resources/db/migration, and the application applies them each time it starts, before JPA, so ddl-auto=validate checks the migrated schema.
Several instances: set migrax.lock-timeout (for example 2m). One instance migrates, the others wait and then start.
With Actuator, the migrax health component is DOWN for a pending, failed, edited or missing migration. With Micrometer, metrics show how long each migration took and how long the instances waited.
When a pipeline migrates, set migrax.migrate-at-startup=false, run migrax migrate before the new version starts, and alert on migrax_migrations_pending.

More in the docs: Spring Boot, Metrics and tracing and Containers and Kubernetes.

Originally published at migrax.org.

Generate and apply database migrations without leaving IntelliJ IDEA

Feroz Shah — Fri, 06 Nov 2026 16:39:56 +0000

You rename a field on a JPA entity. Then you leave the editor to write the SQL, write the rollback script, check which database you are about to change, and run it. The Migrax plugin for IntelliJ IDEA keeps all of that in the IDE. This article follows one renamed field from the edit to the applied migration.

Tested with: Migrax 0.19.0-rc.2, Migrax plugin 0.1.1, IntelliJ IDEA 2026.2.1, Hibernate 6.6.13, PostgreSQL 17. Every screenshot and output below comes from a real run.

The Migrax plugin after a rename: the generated migration and its rollback script, and the tool window with every migration applied.

Install the plugin

In IntelliJ IDEA open Settings > Plugins > Marketplace, search for Migrax and click Install. The plugin is free and works in IntelliJ IDEA Community and Ultimate 2024.2 or newer.

It needs the migrax command. It uses the path in Settings > Tools > Migrax if you set one, then migrax on your PATH, then a copy it downloaded itself. If it finds none, it offers to download the newest release (about 1 MB), checks it against its SHA-256 and unpacks it into the IDE's own folder. A Migrax you installed yourself is never changed.

In a project that does not use Migrax yet, choose Tools > Migrax > Set Up Migrax.... It runs migrax init in the folder you pick and shows what Migrax detected.

The margin icon in the next section needs Migrax 0.18 or newer, which is a release candidate at the time of writing. The rest of the plugin works with Migrax 0.17.

Where we start

This picks up where Renaming columns and tables without losing data started: the same customers and orders project, two migrations applied, and two customers in the table:

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

Rename the field

In Customer, rename name to fullName and give the column its new name:

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

A few seconds after the file changes, a Migrax icon appears in the margin next to the Customer class, and the status bar changes from "Migrax: in sync" to "Migrax: 2 changes". Hover over the icon to see what Migrax found:

Two changes: a new column and a dropped one. Migrax does not know yet that they are the same column.

Click the icon for Generate Migration, or for Show Plan to read the SQL first. They do what migrax generate and migrax plan do in a terminal.

Answer the rename question

Generate Migration asks the question the command line asks:

Answer Renamed and the migration keeps the data. Answer Not Renamed and Migrax drops the old column with its data and adds a new, empty one. Before it drops anything it asks again, and by default it keeps the dropped data in a backup table.

Review the migration

The new migration and its rollback script open in the editor, next to the earlier ones:

db/migration/0003_rename_customers_name.sql:

-- Generated by Migrax 0.19.0-rc.2 for postgresql

ALTER TABLE customers RENAME COLUMN name TO full_name;

db/migration/rollback/0003_rename_customers_name.sql:

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

ALTER TABLE customers RENAME COLUMN full_name TO name;

The highlighted line in the migration is a lint finding. Hover over it:

It is the same message migrax generate prints in a terminal. A rename moves no data, so the statement is fast. The warning is about application instances that still run the old code during a deploy and look for the old column name. The way out it names, migrax generate --zero-downtime, is in the plugin as Generate for Zero Downtime.

Apply the migration

Choose Tools > Migrax > Migrate..., or the Migrate button in the tool window. Before it runs anything, the plugin shows which database it will change and which migrations it will apply:

Confirm, and the migration runs in a background task, so the editor stays usable. The status bar returns to "Migrax: in sync", and the Migrax tool window lists every migration and its state. Click the status bar entry to open it:

The rename moved no data. The same two customers are in the table, under the new column name:

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

What else is in the tool window

The tool window has four tabs, and its buttons run the other commands. The plugin guide lists every one:

Where	What it does
Status tab	Every migration and its state: applied, pending, failed, changed or missing
Plan tab	The SQL of the next migration, with its lint findings
Lint tab	Locking and risky SQL in the pending migrations, or in all of them
Environments tab	Every configured database: in sync, pending, drift or unreachable
Roll Back...	Shows the database and the newest applied migration, then rolls it back
Drift	Lists changes made to the database outside the migrations
Verify	Applies every migration to a throwaway database and tests each rollback script, leaving your database alone
Report	Opens an HTML report of the schema, the migrations, the lint findings and the drift
Doctor	Checks Java, the build, the entities and the database connection

How it works

The plugin contains no migration logic. Every button runs the migrax command in a background task, asks for --json output and draws the answer: the tool window tabs, the margin icon and the underlines. The IDE, your terminal and your CI call the same command, so they give the same result.

What it does not do yet

With several Migrax projects below one IDE project, the first one found is used.
Migrate and Roll Back work on the database in the project's settings. Other environments show in the Environments tab and are migrated from the command line.
Migrate and Roll Back cannot be cancelled once they start, because stopping halfway could leave a migration half applied.
The status bar and the margin icons check again about 5 seconds after an entity, migration or settings file changes. That check may build the project, and you can turn it off in Settings > Tools > Migrax.
Squash and merge are not in the IDE yet: use migrax squash and migrax merge.
Only IntelliJ IDEA is supported. Other JetBrains IDEs are not.

Summary

The Migrax plugin takes an entity edit to an applied migration inside IntelliJ IDEA. The margin icon shows what changed, Generate Migration writes the SQL and the rollback script and asks about renames, lint marks risky statements in the file, and Migrate... names the database before it runs. It is an early version (0.1.1), free, and open source under the Apache License 2.0.

Originally published at migrax.org.

Generated SQL migrations for Python, TypeScript and Go projects

Feroz Shah — Sat, 31 Oct 2026 11:55:26 +0000

Migrax started as a tool for Java: it reads JPA entities and writes the SQL migrations that bring the database in line with them. But the idea doesn't depend on Java. Every ORM knows the tables it expects, and almost every ORM can print them as CREATE TABLE statements.

That SQL is all Migrax needs. Keep it in a schema file, and Migrax compares it with what the existing migrations build, writes the next numbered migration with its rollback script, and applies it. This article follows a small Python project through its first changes, then shows the same loop with Drizzle in TypeScript and GORM in Go.

Tested with: Migrax 0.17.2-rc.1, PostgreSQL 17, SQLAlchemy 2.1.6 (Python 3.13), Drizzle ORM 0.45.4 with drizzle-kit 0.31.11 (Node.js 24), GORM 1.31.2 (Go 1.25). Docker runs the throwaway databases. Every output below was copied from a real run.

The idea in one picture

models.py  --export-->  db/schema.sql  --migrax generate-->  db/migrations/0002_....sql
 (your ORM)              (the tables                          + rollback/0002_....sql
                          you want)

The schema file says what the tables should look like. The migrations say how to get there, one reviewed step at a time. Both are committed. Migrax never touches your models, and your application never needs Migrax at runtime: the migrations are plain SQL files.

A Python shop with SQLAlchemy

Two tables, customers and their orders:

models.py:

from datetime import datetime
from decimal import Decimal

from sqlalchemy import ForeignKey, Numeric, String, func
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class Base(DeclarativeBase):
    pass


class Customer(Base):
    __tablename__ = "customer"
    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(String(150), unique=True)
    name: Mapped[str] = mapped_column(String(100))
    created_at: Mapped[datetime] = mapped_column(server_default=func.now())


class Order(Base):
    __tablename__ = "orders"
    id: Mapped[int] = mapped_column(primary_key=True)
    customer_id: Mapped[int] = mapped_column(ForeignKey("customer.id"), index=True)
    total: Mapped[Decimal] = mapped_column(Numeric(12, 2))
    status: Mapped[str] = mapped_column(String(20), server_default="new")

SQLAlchemy compiles a table into PostgreSQL's CREATE TABLE without connecting to anything. A short script turns the models into the schema file:

export_schema.py:

"""Prints the tables of models.py as SQL, for Migrax's schema file."""
from sqlalchemy.dialects import postgresql
from sqlalchemy.schema import CreateIndex, CreateTable

from models import Base

dialect = postgresql.dialect()
for table in Base.metadata.sorted_tables:
    print(f"{str(CreateTable(table).compile(dialect=dialect)).strip()};\n")
    for index in sorted(table.indexes, key=lambda i: i.name):
        print(f"{CreateIndex(index).compile(dialect=dialect)};\n")

Migrax reads its settings from the environment. The schema file is one more of them:

export MIGRAX_DATABASE_URL=jdbc:postgresql://localhost:55432/shop
export MIGRAX_DATABASE_USER=shop
export MIGRAX_DATABASE_PASSWORD=secret
export MIGRAX_LOCATIONS=filesystem:db/migrations
export MIGRAX_SCHEMA_FILE=db/schema.sql
export MIGRAX_DRIVERS=drivers        # holds postgresql-42.7.14.jar

The first migration

$ python export_schema.py > db/schema.sql
$ migrax generate
Starting a throwaway postgresql database (postgres:17-alpine)...
Read db/schema.sql: 2 table(s).
No snapshot yet: using the current database schema as the baseline.
Created db/migrations/0001_initial.sql:
  - create table customer
  - create table orders
  - add index ix_orders_customer_id on orders
  - add foreign key orders_customer_id_fkey on orders
Rollback script written to db/migrations/rollback.
Review the SQL, then run 'migrax migrate'.

To read the file, Migrax runs it on a throwaway PostgreSQL in Docker, in the same version as your server, and reads the tables back. So whatever the database accepts, Migrax understands, and what it doesn't accept fails here, not in production. The migration it writes:

db/migrations/0001_initial.sql:

CREATE TABLE customer (id integer GENERATED BY DEFAULT AS IDENTITY NOT NULL, email varchar(150) NOT NULL, name varchar(100) NOT NULL, created_at timestamp(6) DEFAULT now() NOT NULL, CONSTRAINT customer_pkey PRIMARY KEY (id), CONSTRAINT uk_customer_email UNIQUE (email));
CREATE TABLE orders (id integer GENERATED BY DEFAULT AS IDENTITY NOT NULL, customer_id integer NOT NULL, total numeric(12,2) NOT NULL, status varchar(20) DEFAULT 'new' NOT NULL, CONSTRAINT orders_pkey PRIMARY KEY (id));
CREATE INDEX ix_orders_customer_id ON orders (customer_id);
ALTER TABLE orders ADD CONSTRAINT orders_customer_id_fkey FOREIGN KEY (customer_id) REFERENCES customer (id);

Two details differ from SQLAlchemy's own SQL, and both are on purpose. SQLAlchemy writes SERIAL; Migrax writes identity columns, which hand out ids the same way. And constraints get names (uk_customer_email), so later migrations can refer to them.

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

The application saves its first customer, Ada Lovelace, with one order of 42.50.

Adding a column

A phone number for customers:

    phone: Mapped[str | None] = mapped_column(String(30))

Export again. Before writing anything, migrax check tells you what has no migration yet:

$ python export_schema.py > db/schema.sql
$ migrax check
Starting a throwaway postgresql database (postgres:17-alpine)...
Read db/schema.sql: 2 table(s).
1 change(s) in db/schema.sql have no migration:
  - add column customer.phone
Run 'migrax generate' and commit the result.
$ echo $?
2

Exit code 2 means "changes without a migration", which is the line to put in CI. Then:

$ migrax generate
Created db/migrations/0002_add_customer_phone.sql:
  - add column customer.phone
Rollback script written to db/migrations/rollback.
Review the SQL, then run 'migrax migrate'.

No database started this time: Migrax had read this version of the file a moment earlier and cached what it found in .migrax/schema-model.json. The migration and its rollback script:

db/migrations/0002_add_customer_phone.sql:

ALTER TABLE customer ADD COLUMN phone varchar(30);

db/migrations/rollback/0002_add_customer_phone.sql:

-- Rollback for 0002_add_customer_phone.sql. 'migrax rollback' runs it.
-- Note: deletes data written to customer.phone since the migration ran.

ALTER TABLE customer DROP COLUMN phone;

Renaming a column, keeping the data

name becomes full_name. Compared naively, that is a dropped column and a new one, and Ada's name would be gone. Migrax notices the likely rename. In a terminal it asks; in a script, where nobody can answer, it stops before dropping anything:

$ migrax generate
Possible rename: customer.name to customer.full_name. To keep the data, rerun with --rename customer.name=full_name.
2 change(s) for postgresql:
  1. add column customer.full_name
     ALTER TABLE customer ADD COLUMN full_name varchar(100) NOT NULL;
  2. drop column customer.name  [DESTRUCTIVE]
     ALTER TABLE customer DROP COLUMN name;
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.
$ migrax generate --rename customer.name=full_name
Created db/migrations/0003_rename_customer_name.sql:
  - rename column customer.name to full_name
Rollback script written to db/migrations/rollback.
db/migrations/0003_rename_customer_name.sql, statement 1: warning MX008
  ALTER TABLE customer 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'.

db/migrations/0003_rename_customer_name.sql:

ALTER TABLE customer RENAME COLUMN name TO full_name;

The warning is about deployment, not data: old instances that still query name break when the column is renamed. After migrax migrate, a three-line script that lists the customers through SQLAlchemy reads the row back under its new name:

$ python read.py
1 ada@example.com Ada Lovelace

Proving the migrations

The migrations now describe the schema in three steps. migrax verify checks that they really build what the schema file says, on an empty throwaway database of your server's version, and that every rollback script works:

$ migrax verify
Starting a throwaway postgresql database (postgres:17-alpine)...
Applying migration '0001_initial.sql'...
...
Applied 3 migration(s) to a fresh postgresql database.
Schema matches the schema file (structural comparison).
Rolling back migration '0003_rename_customer_name.sql'...
...
Rollback scripts: ok (3 rolled back and re-applied).
Verified.

And migrax status shows where the real database is:

$ migrax status
Migrations in db/migrations for jdbc:postgresql://localhost:55432/shop
  [X] 0001_initial.sql               applied 2026-10-26 16:02:43
  [X] 0002_add_customer_phone.sql    applied 2026-10-26 16:02:51
  [X] 0003_rename_customer_name.sql  applied 2026-10-26 16:02:58
3 applied.

Undoing the rename takes one command. In a terminal, rollback asks before it changes anything; in a script, pass --yes:

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

The column is called name again, with Ada's name still in it. migrax migrate applies the rename once more.

The same loop in TypeScript, with Drizzle

drizzle-kit export prints a Drizzle schema as SQL, without a database:

$ npx drizzle-kit export --dialect=postgresql --schema=./schema.ts > db/schema.sql
$ migrax generate
Starting a throwaway postgresql database (postgres:17-alpine)...
Read db/schema.sql: 2 table(s).
No snapshot yet: using the current database schema as the baseline.
Created db/migrations/0001_initial.sql:
  - create table customer
  - create table orders
  - add index orders_customer on orders
  - add foreign key orders_customer_id_customer_id_fk on orders
Rollback script written to db/migrations/rollback.
Review the SQL, then run 'migrax migrate'.

Adding phone: varchar("phone", { length: 30 }) to the customer table and exporting again gives 0002_add_customer_phone.sql with the same single ALTER TABLE customer ADD COLUMN as in Python. Drizzle's own names for indexes and foreign keys are kept as they are.

The same loop in Go, with GORM

GORM can't print its models as SQL, but its AutoMigrate creates them. Let it create the tables in a database of their own (shop_dev, never the one Migrax migrates), and copy them from there with pg_dump:

models.go:

type Customer struct {
    ID        uint      `gorm:"primaryKey"`
    Email     string    `gorm:"size:150;not null;uniqueIndex"`
    Name      string    `gorm:"size:100;not null"`
    CreatedAt time.Time `gorm:"not null;default:now()"`
}

type Order struct {
    ID         uint    `gorm:"primaryKey"`
    CustomerID uint    `gorm:"not null;index"`
    Customer   Customer
    Total      float64 `gorm:"type:numeric(12,2);not null"`
    Status     string  `gorm:"size:20;not null;default:'new'"`
}

$ go run .            # db.AutoMigrate(&Customer{}, &Order{}) on shop_dev
$ pg_dump --schema-only --no-owner --no-privileges shop_dev > db/schema.sql
$ migrax generate
Starting a throwaway postgresql database (postgres:17-alpine)...
Read db/schema.sql: 2 table(s).
No snapshot yet: using the current database schema as the baseline.
Created db/migrations/0001_initial.sql:
  - create table customers
  - create table orders
  - add index idx_orders_customer_id on orders
  - add foreign key fk_orders_customer on orders
Rollback script written to db/migrations/rollback.
Review the SQL, then run 'migrax migrate'.

Why not let AutoMigrate change the real database directly? It is fine in development, and GORM is upfront about its limits: its migration docs (as of October 2026) say it "WON'T delete unused columns to protect your data" and that "at some point you may need to switch to a versioned migrations strategy". With the dump in between, AutoMigrate stays where it is convenient, and production gets reviewed, numbered migrations with rollback scripts, renames that keep their data, and drops that need your confirmation.

In CI

Two lines catch a model change that has no migration:

python export_schema.py > db/schema.sql   # or: npx drizzle-kit export ..., pg_dump ...
migrax check                              # exit code 2: a change has no migration yet

Commit db/schema.sql and the .migrax/ folder with every migration. While the schema file is unchanged, migrax check reads the saved model and needs no Docker at all. Migrax itself runs on Java 17 or newer; a Python, Node or Go build that has no Java can use the container image ghcr.io/fsmutimeer/migrax instead.

What to know

Read the migration before you commit it. It is plain SQL, generated, but yours.
Views, functions, triggers and sequences don't belong in the schema file. Keep them in repeatable migrations (R__*.sql); identity columns work in the file.
Reshaping data is yours to write. Migrax moves the structure and keeps values through renames. Splitting full_name into first and last name needs a rule only you know: a migration written with migrax new, between two generated ones.
MySQL and MariaDB work the same way. Compile with SQLAlchemy's mysql dialect, or dump with mysqldump --no-data --skip-comments.

Summary

Your ORM already describes the schema. Export it as SQL into a schema file: a short script for SQLAlchemy, drizzle-kit export for Drizzle, pg_dump after AutoMigrate for GORM.
migrax generate writes the next migration and its rollback script, asks about renames, and refuses to drop data without your confirmation.
migrax check in CI catches a model change without a migration, and migrax verify proves the migrations build exactly the schema in the file.
The migrations are plain SQL. Your application runs without Migrax.

The full reference, with MySQL and more ORMs: Schema file from your ORM.

Originally published at migrax.org.

Migrax vs Flyway: generated vs hand-written migrations

Feroz Shah — Sat, 31 Oct 2026 11:54:44 +0000

Flyway and Migrax both keep a database schema in numbered SQL files, apply them in order and record what ran. The difference is where the SQL comes from. With Flyway you write every migration yourself. With Migrax you change your JPA entities and it writes the migration, which you then review.

This article makes the same change with both, on the same PostgreSQL database, and compares what each one does along the way. It also says where Flyway is the better choice.

Tested with: Flyway Community 13.12.0 (the open-source command line, released 2026-10-30), Migrax 0.17.1, Spring Boot 3.5.7, Hibernate 6.6.33, PostgreSQL 17. Compared on 2026-10-31. Statements about Flyway's editions come from Redgate's feature summary (last updated 2026-10-27). Every output below was copied from a real run.

The change

A customers table with two rows, and the change from Stop using ddl-auto=update in production: name becomes full_name, email gets longer, and every customer needs a country.

With Flyway

You write the migration. A correct version keeps the data by renaming the column, and adds the required column in three steps because the table has rows:

V2__rename_name_add_country.sql:

ALTER TABLE customers RENAME COLUMN name TO full_name;
ALTER TABLE customers ADD COLUMN country varchar(2);
UPDATE customers SET country = 'GB';
ALTER TABLE customers ALTER COLUMN country SET NOT NULL;
ALTER TABLE customers ALTER COLUMN email TYPE varchar(320);

$ flyway migrate
Current version of schema "public": 1
Migrating schema "public" to version "2 - rename name add country"
Successfully applied 1 migration to schema "public", now at version v2 (execution time 00:00.019s)

Flyway runs what you wrote, exactly as written. Whether the file matches the entities, and whether it keeps the data, is up to you and your reviewers. If you forget the UPDATE, or write DROP COLUMN name and ADD COLUMN full_name instead of a rename, Flyway runs that too.

There is no way back with the open-source edition:

$ flyway undo
ERROR: Flyway Redgate Edition Required: undo is not supported by OSS Edition

Undo scripts (U2__...sql) and the undo command are part of Flyway Teams and Enterprise, and you write each undo script yourself.

With Migrax

You change the entity (fullName, length = 320, a new country field) and run generate:

$ migrax generate --rename customers.name=full_name
warning: Adding NOT NULL column 'customers.country' without a default fails if the table has rows. Add a default in the SQL, or add it as nullable, backfill, then make it NOT NULL.
Created src/main/resources/db/migration/0002_rename_customers_name_and_more.sql:
  - rename column customers.name to full_name
  - add column customers.country
  - alter column customers.email
Rollback script written to src/main/resources/db/migration/rollback.
...

It writes the forward migration and a rollback script, and lints the migration before anything runs. The warning above is the UPDATE you would otherwise have to remember. You edit the file the same way as the Flyway one, and end up with the same five statements. Without --rename, Migrax sees a column go away and another appear, asks whether it was a rename, and refuses to drop the column without --allow-destructive. In CI, where no one can answer, it stops and prints the --rename option to use.

migrax rollback runs the generated rollback script:

rollback/0002_rename_customers_name_and_more.sql:

ALTER TABLE customers DROP COLUMN country;
ALTER TABLE customers ALTER COLUMN email TYPE varchar(255);
ALTER TABLE customers RENAME COLUMN full_name TO name;

So the work moves from writing SQL to reviewing it. You still read every migration; you no longer type it, or its undo script.

What both do

Much of the day-to-day is the same:

Plain SQL files in order. Flyway's V1__...sql, Migrax's 0001_...sql. Both also run Java migrations for changes SQL can't express.
A history table with checksums. Both refuse to continue when someone edits a migration that already ran:

```shell $ flyway validate Migration checksum mismatch for migration version 1 -> Applied to database : -328024399 -> Resolved locally : 1803351363 Either revert the changes to the migration, or run repair to update the schema history.

$ migrax migrate error[MXE104]: Checksum changed for applied migration V1__create_customers.sql ```
Baselines for a database that existed before the tool: flyway baseline and migrax baseline.
Running at application startup, through Spring Boot's built-in Flyway support or the Migrax starter, and both have Maven and Gradle plugins.

Where they differ

	Flyway Community	Flyway Teams / Enterprise	Migrax
Who writes the SQL	You	You; Enterprise can generate it from a schema model	Generated from JPA entities, you review it
Undo / rollback	No	Teams and Enterprise: undo scripts you write	Rollback script generated with each migration
Dry run script	No	Yes	`migrax migrate --sql` prints the script without running it
Drift detection	No	Enterprise	`migrax drift`, and a check at startup
Lint for risky statements	No	Not in the feature summary	`migrax lint`, run on every `generate`
Throwaway-database check	No	Not in the feature summary	`migrax verify` applies every migration and rollback
Databases	About 30, including Snowflake, BigQuery and MongoDB (list)	Same, with Redgate support	12 relational databases
Licence	Apache 2.0	Commercial	Apache 2.0, every feature

"Not in the feature summary" means Redgate's feature summary doesn't list it; Redgate's documentation describes the checks each edition has.

Where Flyway is the better choice

There are no JPA entities. Migrax generates migrations from Hibernate, JPA and a few other Java mappings (or a SQL schema file). A project that writes SQL by hand, or isn't on the JVM, gains less from it, while Flyway works the same for everyone.
The database isn't one of Migrax's 12. Flyway reaches warehouses and document databases such as Snowflake, BigQuery, Databricks and MongoDB.
You want a vendor behind the tool. Redgate sells support, a desktop application and compliance features. Migrax is an open-source project.
The team prefers writing every statement. Some teams want the migration to be the source of truth, not the entities. Flyway is built around that.

Switching from Flyway

Migrax reads Flyway's history table, so a project can switch without rerunning anything. Copy or keep the V*__ files in the migration folder and run:

$ migrax import flyway
Recorded 2 migration(s) as applied.
Next: disable Flyway (spring.flyway.enabled=false), then run 'migrax generate'; its first run uses the current database as the baseline.

$ migrax status
Migrations in src/main/resources/db/migration for jdbc:postgresql://localhost:5432/shop_fw
  [X] V1__create_customers.sql         applied 2026-10-31 11:45:20
  [X] V2__rename_name_add_country.sql  applied 2026-10-31 11:45:20
2 applied.

$ migrax generate
No snapshot yet: using the current database schema as the baseline.
No changes detected.
Saved the entity schema as the baseline snapshot: .migrax/snapshot.json

The old files keep working, and the next entity change becomes 0003_...sql. Each other environment needs migrax import flyway once. The guide Switching from Flyway or Liquibase has the details.

Summary

Flyway applies the SQL you write. Migrax writes the SQL from your entities, with a rollback script and lint warnings, and you review it.
Both keep a checksummed history, refuse edited migrations, baseline existing databases and run at startup.
Undo, dry-run scripts and drift detection are paid Flyway features; in Migrax they are part of the free tool.
Flyway is the better fit without JPA entities, for databases Migrax doesn't support, or when you want commercial support.

Originally published at migrax.org.

Catching schema drift before it breaks production

Feroz Shah — Sat, 31 Oct 2026 11:54:01 +0000

Migrations only describe a database as long as nobody changes it any other way. Then someone adds a column during an incident, a DBA widens a type, a data import relaxes a constraint, and nobody writes it down. The next migration was tested against a database that production no longer is.

That gap is called drift. This article makes four changes by hand on a production database, finds them with migrax drift, keeps the one that was wanted, undoes the rest, and then makes the application refuse to start on a database that has drifted.

Tested with: Migrax 0.17.1, Spring Boot 3.5.7, Hibernate 6.6.33, PostgreSQL 17. Every output below was copied from a real run; log lines are shortened to the message.

The starting point

A Spring Boot application with a customers table, built by two migrations and applied to production:

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

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

  @Column(nullable = false, length = 100)
  private String fullName;

  @Column(nullable = false, length = 2)
  private String country = "GB";
}

Here production is the database shop_prod and development is shop, on the same PostgreSQL server. .migrax/snapshot.json records the schema those migrations produce. generate keeps it up to date and it is committed with the migrations, so it is also the yardstick for drift.

Four changes nobody wrote down

During a busy week, four statements run on production by hand:

ALTER TABLE customers ADD COLUMN vip boolean NOT NULL DEFAULT false;
ALTER TABLE customers ALTER COLUMN full_name DROP NOT NULL;
ALTER TABLE customers ALTER COLUMN email TYPE varchar(200);
CREATE INDEX customers_country_idx ON customers (country);

The first is a hotfix for a feature that is coming anyway. The second was needed for a data import and never reverted. The third was a mistake. The fourth sped up a slow report.

Finding them

$ migrax drift --url jdbc:postgresql://localhost:5432/shop_prod
3 difference(s) between the database and the snapshot:
  - customers.email: expected varchar(320) but the database column is shorter (varchar(200))
  - customers.full_name: expected NOT NULL but the database has NULL
  - customers.vip: column exists in the database but not in the expected schema
Someone changed the database outside migrations. Write a migration for intended changes ('migrax new <name>'), or revert them.

drift reads the live schema and compares it with the snapshot. It checks tables, columns, types, nullability, primary and foreign keys and unique constraints. Plain indexes are not part of that comparison, so customers_country_idx isn't listed; migrax diff, further down, does show it.

The shorter email is the dangerous one. The entity allows 320 characters, so the first customer with a long address gets an error from the database. Nothing in the code or the migrations would show why.

drift exits with code 2 when it finds differences, and --json gives the same result for a script:

$ migrax drift --url jdbc:postgresql://localhost:5432/shop_prod --json
{"against":"snapshot","pending":0,"differences":[{"kind":"type","object":"customers.email","detail":"expected varchar(320) but the database column is shorter (varchar(200))"},{"kind":"nullability","object":"customers.full_name","detail":"expected NOT NULL but the database has NULL"},{"kind":"extra_column","object":"customers.vip","detail":"column exists in the database but not in the expected schema"}]}
$ echo $?
2

With --entities, drift compares the database with the entities instead of the snapshot. That answers a different question: not "did someone change the database?" but "does the database fit the code I have now?"

Keeping the change you want

The vip column is wanted, so it belongs in the entity and in a migration, like every other change:

  @ColumnDefault("false")
  @Column(nullable = false)
  private boolean vip;

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

ALTER TABLE customers ADD COLUMN vip boolean DEFAULT false NOT NULL;

Every other database (development, staging, a new laptop) needs this statement. Production already has the column and would fail on it, so add IF NOT EXISTS:

ALTER TABLE customers ADD COLUMN IF NOT EXISTS vip boolean DEFAULT false NOT NULL;

The migration now runs everywhere, and production records it like any other:

$ migrax migrate --url jdbc:postgresql://localhost:5432/shop_prod
Applying migration '0003_add_customers_vip.sql'...
Successfully applied migration '0003_add_customers_vip.sql'.
Applied 1 migration(s); 3 total in src/main/resources/db/migration.

$ migrax drift --url jdbc:postgresql://localhost:5432/shop_prod
2 difference(s) between the database and the snapshot:
  - customers.email: expected varchar(320) but the database column is shorter (varchar(200))
  - customers.full_name: expected NOT NULL but the database has NULL
Someone changed the database outside migrations. Write a migration for intended changes ('migrax new <name>'), or revert them.

Undoing the rest

For the changes that shouldn't be there, migrax diff writes the SQL. It compares two live databases: the source is one that is right (here the development database, which only ever got migrations), the target is production. The source's credentials come from MIGRAX_SOURCE_USER and MIGRAX_SOURCE_PASSWORD, or --source-user and
--source-password-file:

$ migrax diff jdbc:postgresql://localhost:5432/shop --url jdbc:postgresql://localhost:5432/shop_prod
To make jdbc:postgresql://localhost:5432/shop_prod match jdbc:postgresql://localhost:5432/shop:
3 change(s) for postgresql:
  1. drop index customers_country_idx on customers  [DESTRUCTIVE]
     DROP INDEX customers_country_idx;
  2. alter column customers.email
     ALTER TABLE customers ALTER COLUMN email TYPE varchar(320);
  3. alter column customers.full_name
     ALTER TABLE customers ALTER COLUMN full_name SET NOT NULL;
To keep them, save the SQL as a migration: migrax diff <source-url> --sql

diff also compares indexes, so the report index shows up here. --sql prints the same statements as one script to review and hand to whoever runs SQL on production:

-- Generated by Migrax 0.17.1 for postgresql

DROP INDEX customers_country_idx;
ALTER TABLE customers ALTER COLUMN email TYPE varchar(320);
ALTER TABLE customers ALTER COLUMN full_name SET NOT NULL;

Keep the lines you mean to run. If the index is worth having, leave out the DROP INDEX and add the index to the entity (@Table(indexes = ...)) so the next generate writes it for everyone else. SET NOT NULL fails if the import left rows without a name, so fill those in first. Once the script has run:

$ migrax drift --url jdbc:postgresql://localhost:5432/shop_prod
No drift: the database matches the snapshot.

$ migrax diff jdbc:postgresql://localhost:5432/shop --url jdbc:postgresql://localhost:5432/shop_prod
Same schema: jdbc:postgresql://localhost:5432/shop_prod matches jdbc:postgresql://localhost:5432/shop.

Noticing it the next time

Finding drift by chance is too late. There are two places to check for it on purpose.

On a schedule. Because drift exits with 2, a nightly CI job or Kubernetes CronJob fails when it finds something, and the usual alert for a failed job tells you the next morning.

When the application starts. With the Spring Boot starter, the application runs the same comparison each time it starts, right after it applies any pending migrations. Turn it on with one line:

migrax.drift.check=fail

The application reads the expected schema from META-INF/migrax/snapshot.json, so the build has to put the snapshot there. With Maven, that is the package-snapshot goal of the Migrax plugin:

<plugin>
  <groupId>org.migrax</groupId>
  <artifactId>migrax</artifactId>
  <version>0.17.1</version>
  <executions>
    <execution>
      <goals>
        <goal>package-snapshot</goal>
      </goals>
    </execution>
  </executions>
</plugin>

(The Gradle plugin and the Quarkus extension copy it without any setup.)

A week later someone adds another column by hand, and the next deployment stops:

Migrax: schema is up to date
Migrax: 1 difference(s) between the database and the schema its migrations produce:
  - customers.hotfix_note: column exists in the database but not in the expected schema
Someone changed the database outside migrations. Write a migration for intended changes, or revert them.
(migrax.drift.check=fail stops the start; warn only logs.)

The change is noticed at the deployment, not weeks later when something breaks. On a database without drift, the log says so and the application starts:

Migrax: schema is up to date
Migrax: no drift: the database matches the schema its migrations produce
Started ShopApplication in 6.757 seconds (process running for 7.945)

migrax.drift.check=warn logs the same differences without stopping the start, which is a gentler way to begin. Quarkus, Micronaut, Helidon and Jakarta EE take the same setting.

Summary

migrax drift compares a live database with the schema its migrations produce and exits with 2 when someone changed it by hand. --json is for scripts, --entities compares with the code instead.
A hand-made change you want goes into the entity and a migration. IF NOT EXISTS lets the database that already has it run the migration too.
migrax diff writes the SQL that undoes the rest, by comparing with a database that only ever got migrations. Unlike drift, it also compares indexes.
Run drift on a schedule, or set migrax.drift.check=fail so the application doesn't start on a drifted database.

More in the guides: Production safety and Comparing databases.

Originally published at migrax.org.

Stop using ddl-auto=update in production

Feroz Shah — Sat, 31 Oct 2026 11:53:11 +0000

spring.jpa.hibernate.ddl-auto=update is the fastest way to get started: change an entity, restart, and the table follows. It stays in the configuration long after the first demo, and one day it runs against a database with real customers in it.

This article makes three ordinary entity changes with update switched on and shows what Hibernate does to the database. Then it moves the same project, with its existing data, to generated migrations that you review before they run.

Tested with: Migrax 0.17.1, Spring Boot 3.5.7, Hibernate 6.6.33, PostgreSQL 17. Every output below was copied from a real run; log lines are shortened to the message.

The starting point

A Spring Boot application with one entity:

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

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

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

and the setting this article is about:

spring.jpa.hibernate.ddl-auto=update

On the first start Hibernate creates the table. Two customers sign up:

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

So far update has done exactly what it promises.

Three ordinary changes

The next release changes the entity in three small ways:

name becomes fullName,
email gets longer (length = 320),
every customer now needs a country (nullable = false, "GB" by default in Java).

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

  @Column(nullable = false, length = 100)
  private String fullName;

  @Column(nullable = false, length = 2)
  private String country = "GB";

The application starts, and the next customer tries to sign up. With logging.level.org.hibernate.SQL=debug, the log shows what update did:

alter table if exists customers add column country varchar(2) not null
GenerationTarget encountered exception accepting command : Error executing DDL "alter table
  if exists customers add column country varchar(2) not null" via JDBC [ERROR: column
  "country" of relation "customers" contains null values]
alter table if exists customers alter column email set data type varchar(320)
alter table if exists customers add column full_name varchar(100) not null
GenerationTarget encountered exception accepting command : Error executing DDL "alter table
  if exists customers add column full_name varchar(100) not null" via JDBC [ERROR: column
  "full_name" of relation "customers" contains null values]
Started ShopApplication in 5.803 seconds (process running for 6.91)
insert into customers (country,email,full_name) values (?,?,?)
ERROR: column "country" of relation "customers" does not exist
Application run failed

Three things happened, and only one of them was what you meant:

The rename isn't a rename. Hibernate has no way to know that full_name is the old name. It tries to add a new, empty column next to it.
Adding the required columns fails. PostgreSQL can't add a NOT NULL column without a default to a table that already has rows. Hibernate logs a warning and carries on.
The application starts anyway. The failures are logged as warnings and startup carries on. The error only shows up when the first customer signs up.

Only the longer email worked.

The quick fix makes it worse

The obvious way out is to drop nullable = false from the two new fields so Hibernate can add them. That works, in the sense that the columns appear:

alter table if exists customers add column country varchar(2)
alter table if exists customers add column full_name varchar(100)
Started ShopApplication in 6.557 seconds (process running for 7.569)
insert into customers (country,email,full_name) values (?,?,?)
ERROR: null value in column "name" of relation "customers" violates not-null constraint
Application run failed

The old name column is still there, still NOT NULL, and the entity no longer writes to it. Every signup fails. The table now looks like this:

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

The existing customers have no full_name and no country, so the application shows them without a name. Nothing recorded what changed or when, and there is no way to undo it except by hand.

None of this is a bug in Hibernate. update only ever adds: it never renames, never drops, never moves data, and doesn't stop the application when a statement fails. That is a safe choice for a tool that runs on every start without asking anyone, and it is the reason it shouldn't touch a database whose data matters.

Switching to migrations

The same change, done with Migrax. The database goes back to where it was before the release: two customers and a name column. The entity is back at version 1 too, because the switch is easiest between releases.

1. Let `doctor` find the setting

$ migrax doctor
...
  [warn]  Hibernate will change your database schema by itself
          Found:  spring.jpa.hibernate.ddl-auto = update
                  in src/main/resources/application.properties, line 4

          Why:    Hibernate adds tables and columns itself when the application starts. Migrations
                  then fail with "already exists", and the database drifts from what your migrations
                  describe, so other environments end up different.

          Fix:    change   spring.jpa.hibernate.ddl-auto=update
                  to       spring.jpa.hibernate.ddl-auto=none
                  (or validate: Hibernate then checks the schema at startup without changing it)
  [info]  Snapshot: none yet; the first generate uses the database as baseline
  [ok]    Database URL: jdbc:postgresql://localhost:5432/shop
  [ok]    Connected: PostgreSQL 17.11 (Debian 17.11-1.pgdg13+2) (driver 42.7.8)
...
All checks passed, with 1 warning(s) above.

Migrax reads the database settings from spring.datasource.*, so there is nothing else to configure. Change the line to validate:

spring.jpa.hibernate.ddl-auto=validate

With validate, Hibernate still checks at startup that every entity matches a table and column, and refuses to start if one doesn't. It just never changes anything.

2. Record what the database already has

The first generate has nothing to compare with yet, so it uses the live database:

$ migrax generate
No snapshot yet: using the current database schema as the baseline.
No changes detected.
Created src/main/resources/db/migration/0001_baseline.sql with the 1 table(s) the database already has.
  It is recorded as applied in this database without running it; empty databases are created from it.
Saved the entity schema as the baseline snapshot: .migrax/snapshot.json

0001_baseline.sql describes the table as it is:

-- Generated by Migrax 0.17.1 for postgresql
-- Baseline: the tables the database already had before its first migration.
-- That database records it as applied without running it; empty databases are created from it.

CREATE TABLE customers (id bigint GENERATED BY DEFAULT AS IDENTITY NOT NULL, email varchar(255) NOT NULL, name varchar(100) NOT NULL, CONSTRAINT customers_pkey PRIMARY KEY (id), CONSTRAINT uk_customers_email UNIQUE (email));

This database won't run it, because the table is already there. A new laptop, a test database or migrax verify starts empty and builds the table from it. "No changes detected" means the entities and the database agree, so nothing is lost by switching. If update had already left old columns behind, they would show up here as changes to review.

Commit the migration folder and .migrax/snapshot.json.

3. Make the change again

Now the same three changes to Customer. This time generate writes them down instead of running them:

$ migrax generate --rename customers.name=full_name
warning: Adding NOT NULL column 'customers.country' without a default fails if the table has rows. Add a default in the SQL, or add it as nullable, backfill, then make it NOT NULL.
Created src/main/resources/db/migration/0002_rename_customers_name_and_more.sql:
  - rename column customers.name to full_name
  - add column customers.country
  - alter column customers.email
Rollback script written to src/main/resources/db/migration/rollback.
src/main/resources/db/migration/0002_rename_customers_name_and_more.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.
  ...
src/main/resources/db/migration/0002_rename_customers_name_and_more.sql, statement 2: warning MX002
  ALTER TABLE customers ADD COLUMN country varchar(2) NOT NULL
  Adding a NOT NULL column without a default fails when customers has rows.
  Fix: Add a DEFAULT, or add the column as nullable, backfill it, then make it NOT NULL.
...
Review the SQL, then run 'migrax migrate'.

Without --rename, Migrax notices that a column went away while another appeared and asks whether it was a rename; in CI it refuses to guess and stops. Renaming columns and tables without losing data shows both.

The warning MX002 is the failure from the update run, found before anything ran. The migration is a plain SQL file, so fix it the way the warning says: add the column, fill it, then make it required.

-- Generated by Migrax 0.17.1 for postgresql

ALTER TABLE customers RENAME COLUMN name TO full_name;
ALTER TABLE customers ADD COLUMN country varchar(2);
UPDATE customers SET country = 'GB';
ALTER TABLE customers ALTER COLUMN country SET NOT NULL;
ALTER TABLE customers ALTER COLUMN email TYPE varchar(320);

Next to it, rollback/0002_rename_customers_name_and_more.sql undoes the change:

ALTER TABLE customers DROP COLUMN country;
ALTER TABLE customers ALTER COLUMN email TYPE varchar(255);
ALTER TABLE customers RENAME COLUMN full_name TO name;

4. Apply it

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

The application starts with validate, the next customer signs up, and the existing ones kept their names:

 id |       email       |  full_name   | country
----+-------------------+--------------+---------
  1 | ada@example.com   | Ada Lovelace | GB
  2 | alan@example.com  | Alan Turing  | GB
  3 | grace@example.com | Grace Hopper | GB

The other environments

Production, staging and every teammate's database have the same table but no migration history. Each one needs to be told once that the baseline is already there:

$ migrax status
Migrations in src/main/resources/db/migration for jdbc:postgresql://localhost:5432/shop_prod
  [ ] 0001_baseline.sql                        pending
  [ ] 0002_rename_customers_name_and_more.sql  pending
2 pending.

$ migrax baseline 0001 --yes
Recording 1 migration(s) as applied without running them:
  0001_baseline.sql
Recorded. Run 'migrax migrate' to apply the migrations after 0001_baseline.sql.

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

(Point each command at that database with --url, or the environment variables your deployment already uses.)

Forgetting baseline is safe. migrate tries to create the table, the database refuses, and nothing is recorded or changed:

$ migrax migrate
Applying migration '0001_baseline.sql'...
error: Failed executing migration '0001_baseline.sql': ERROR: relation "customers" already exists
error[MXE102]: Migration '0001_baseline.sql' failed and was not recorded as applied. ...

baseline then refuses too, because the failed attempt counts as history. Record the baseline with repair instead, and carry on:

$ migrax repair 0001_baseline.sql --action applied --yes
Repaired history for 0001_baseline.sql (action: applied). Keep a record of this repair.

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

Other frameworks

The setting has a different name outside Spring Boot, and migrax doctor finds each of them:

Framework	Setting	Change to
Spring Boot	`spring.jpa.hibernate.ddl-auto`	`validate` or `none`
Quarkus	`quarkus.hibernate-orm.schema-management.strategy`	`validate` or `none`
Micronaut	`jpa.default.properties.hibernate.hbm2ddl.auto`	`validate` or `none`
Plain Hibernate, Jakarta EE	`hibernate.hbm2ddl.auto`	`validate` or `none`

Summary

ddl-auto=update only adds. It turns a rename into a second, empty column, can't add a required column to a table with rows, and lets the application start when a statement fails.
Switch between releases: set validate, run migrax generate once to record the existing tables as 0001_baseline.sql, and run migrax baseline 0001 --yes once on every other database.
From then on every change is a SQL file you review, with lint warnings for the statements that fail on real data, and a rollback script.

More in the guides: Quick start and Production safety.

Originally published at migrax.org.

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

Spring Boot: migrations at startup, health checks and metrics

The setup

What happens at startup

Several instances starting together

The health check

Metrics

When a pipeline migrates

Summary

Generate and apply database migrations without leaving IntelliJ IDEA

Install the plugin

Where we start

Rename the field

Answer the rename question

Review the migration

Apply the migration

What else is in the tool window

How it works

What it does not do yet

Summary

Generated SQL migrations for Python, TypeScript and Go projects

The idea in one picture

A Python shop with SQLAlchemy

The first migration

Adding a column

Renaming a column, keeping the data

Proving the migrations

The same loop in TypeScript, with Drizzle

The same loop in Go, with GORM

In CI

What to know

Summary

Migrax vs Flyway: generated vs hand-written migrations

The change

With Flyway

With Migrax

What both do

Where they differ

Where Flyway is the better choice

Switching from Flyway

Summary

Catching schema drift before it breaks production

The starting point

Four changes nobody wrote down

Finding them

Keeping the change you want

Undoing the rest

Noticing it the next time

Summary

Stop using ddl-auto=update in production

The starting point

Three ordinary changes

The quick fix makes it worse

Switching to migrations

1. Let doctor find the setting

2. Record what the database already has

3. Make the change again

4. Apply it

The other environments

Other frameworks

Summary

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

1. Let `doctor` find the setting

`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