Skip to content
Anjunar/ DOCS

Preview

Before a deployment, see what the next start would do to a database, without changing its schema, data or history.

From code

Same plan, read-only

preview plans with the same rules, options and backfills as migrate, inside one read-only REPEATABLE READ transaction. It takes no migration lock and runs no DDL, so a role with read rights suffices.

scala
import com.anjunar.hibernateddl.executor.{DataChecks, PreviewOptions, PreviewRendering} import com.anjunar.hibernateddl.integration.HibernateSchemaMigration val report = HibernateSchemaMigration.preview(metadata, dataSource, previewOptions = PreviewOptions(dataChecks = DataChecks.Existence, includeExactCounts = false)) println(PreviewRendering.text(report)) // or PreviewRendering.json(report)
Output
Result: READY for the state read Mode: Migration Revision: 5 Target fingerprint: 9d4c1e7a52b8f03c6e1d9a47b2c85f10e3a6d7c94b1f2e08c5a3d6b9e7f40c21
Report

Steps, approvals, locks and checks

The report lists the mode, the steps in execution order with their SQL, the approvals required and missing, the locks the migration will take, and findings with stable codes.

Ready
A complete plan without blockers, and every required check passed.
Blocked
A blocker was found: a missing approval, drift, or data that breaks a constraint.
Incomplete
No blocker, but a check is open: a timeout or a missing privilege. Never treated as ready.

Data checks run on the rows as they are, with the migration's values projected: NULLs left in a column that becomes required, duplicates for a unique key, missing rows for a foreign key, rows that make a check false.

Command line

Without the application's classes

exportTarget and exportBackfills write the target and the backfills as JSON. The CLI previews from those files.

scala
Files.writeString(Path.of("target-schema.json"), HibernateSchemaMigration.exportTarget(metadata)) Files.writeString(Path.of("backfills.json"), HibernateSchemaMigration.exportBackfills(metadata))
shell
export HIBERNATE_DDL_PREVIEW_JDBC_URL=jdbc:postgresql://db:5432/app export HIBERNATE_DDL_PREVIEW_USER=reader HIBERNATE_DDL_PREVIEW_PASSWORD=... sbt "schemaCli/run preview --target target-schema.json --backfills backfills.json --format json"
0
Ready.
1
Blocked.
3
Incomplete.
2
Invalid call or technical error.
A ready preview grants nothing

The migration checks everything again under its locks. A database that changed after the preview still stops the start.