Skip to main content

The model, schema snapshot and database

A JCM model change has two jobs: describe the application you want to build and explain how an existing database reaches that shape. Keeping those jobs together makes a reviewable change; treating the database as disposable would lose the records the application exists to manage.

Three artifacts with different meanings​

ArtifactWhat it recordsWhat it does not establish
src/main/jcm/model/<Entity>.ymlThe entity's current declared fields, types, relationships and supported constraintsThat a running database already has those columns
src/main/jcm/model/schema.jsonThe model schema represented by the recorded changelogs, with their checksumsA live inventory of a database or proof that a deployment ran
Numbered Liquibase XML changelogsOrdered database changes that bring earlier schemas forwardThe business decision about how to populate, archive or correct existing values

The model generates Java entities and captions during the build. jcm changelog compares the model with the snapshot and writes the next migration and updated snapshot. The application applies pending migrations through Liquibase when it starts. Those are separate events: generating a changelog does not alter a running service.

This is why the model, snapshot and new migration belong in one commit. checkJcmModel, included in the build's checks, detects disagreements and changed recorded migrations. Committing only a new model can leave colleagues with an entity definition their database cannot support. Editing the snapshot by hand can conceal the missing migration from a casual review; it is not a replacement for producing the change.

Why some changes need an explicit decision​

Adding an optional field leaves a meaningful value for existing rows: no value. Increasing a text length preserves the old capacity. Those operations can be generated directly. A new required text field has a different problem: the generator does not know which value every existing record should receive. The supported path is to add it nullable, backfill with an application-specific migration, then make it required with the explicit change mark.

Removing a field requires its name under removed. Shortening text, changing decimal precision/scale or making an existing field required needs changed: true where supported. These marks record intent; they do not make every conversion safe or supported. For example, changing text to an integer remains a staged conversion with a new field and an explicit, verified value conversion. Dropping an entire entity/table is refused by this model tool.

Generated narrowing migrations guard against losing values on the supported databases. They can stop when rows violate the requested shape. Earlier change sets may already have completed, so recovery must respect the recorded history. Removing the guard or rewriting the already-used file discards that history. Once a marked change has been generated, remove the consumed mark so it cannot silently authorize a later destructive edit.

The data-model reference gives the exact supported changes, refusal messages and database-specific behavior. A general migration principle is not permission to improvise a conversion that the current tool refuses.

Generated files preserve a history​

An old migration describes what happened at a particular point in the application's life. A fresh database may still need it, and an existing database may have already recorded its checksum. Changing the old file to match the latest model gives those two databases different histories with the same filename.

Generate another migration instead. The snapshot tracks the written files and their checksums, and Liquibase checks what has run. This also explains why --baseline is a specialized operation: it records a model without generating the creation changes. It is intended for an application whose existing migrations already create the schema, not as a way to make a new database or a failing model check appear complete.

Changing a model is a build and restart operation. A studio publish can update supported runtime configuration, but it cannot generate a Java entity, apply a new model schema or replace a deployment. Model files and runtime configuration have separate folders and lifecycles even though both use YAML.

A clean install and an upgrade answer different questions​

A clean-database test asks whether the complete migration history creates a working current application. An upgrade rehearsal starts from a supported earlier schema with invented records, applies the new release, and checks what happened to those records. Both matter: an empty database cannot expose a narrowing conflict, a missing backfill or an integration still depending on a removed field.

Use the intended database family for upgrade evidence. Record the before/after release and migration identities, retained values, changed constraints and expected refusals. A successful HSQLDB test is not PostgreSQL or SQL Server upgrade evidence. A successful configuration check is not a backup or a completed restore exercise.

Reverting the application image also does not reverse a schema migration or reconstruct a dropped value. Release planning needs a data-compatible recovery decision alongside the code change. These responsibilities remain with the application even when JCM writes the routine migration XML.