Database Migration

Jmix Studio creates migration scripts in the Liquibase changelog format by comparing the current state of your JPA entities with the current database schema of the corresponding data store. It happens automatically when you start the application using a Run/Debug Configuration. The changelog is saved in the source code of the application and is built into the binary artifact.

When the application starts, it automatically runs Liquibase with the generated changelogs to update the connected database.

Add-ons that your application depends on can also contain Liquibase changelog files. Changelogs from dependencies are executed on your database before the ones of the application.

Studio generates changelog files in the src/main/resources/<base_package>/liquibase directory of the application project. In this directory, Studio creates the changelog directory for the main data store, and <store>-changelog directories for additional data stores. Changelog files are created in subdirectories corresponding to the year and month of the current date. Name of each file includes a current day, a sequence number within the day, and a random character sequence to avoid conflicts if multiple developers work on the same project.

For each data store, there is a root changelog file located in the src/main/resources/<base_package>/liquibase directory. It contains a directive to include all generated changelog files under the changelog subdirectory.

The root Liquibase changelog for the main data store contains include directives for changelogs of all add-ons used in the project. It makes the changelog compatible with the Liquibase Gradle plugin and Liquibase CLI and allows you to run Liquibase outside the Studio or the application, for example, on a CI server.

Studio maintains the includes automatically when you add or remove add-ons. Also, when you start the application, it checks that includes in the root changelog correspond to the add-ons used in the project. If it finds a mismatch, Studio shows a notification dialog and suggests adding or removing includes. You can ignore some paths, and the notification won’t be shown again for the ignored items.

The root changelog file is passed to Liquibase when the application or Studio runs the database migration.

You can write Liquibase changelog files manually and put them into the structure described above. Liquibase executes included changelogs in the alphabetical order considering the whole path, so give your files appropriate names.

You can specify Liquibase properties for the main data store in application.properties in the same way as described in the Spring Boot documentation (see spring.liquibase.* properties), but replacing the spring.liquibase prefix with main.liquibase, for example:

For an additional store, replace main in the property name with the name of the data store.

By default, Jmix Studio compares all tables of the database with the data model, and generates migration scripts including DROP TABLE statements for tables that are not mapped to entities. If your database contains tables not associated with the application entities, you can ignore these tables by listing their prefixes or entire names in the main.datasource.studio.liquibase.exclude-prefixes application property. For example: