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.

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:

  
  $ 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

"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.

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.

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:

1. 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.
2. 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.
3. 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:

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.

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.

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.

More in the guide: Changing entities.

Originally published at migrax.org.

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.