Liquibase
Prior to IntelliJ IDEA version 2024.1, some Liquibase features were only available with the JPA Buddy plugin. The following video demonstrates these features, which are now available with the Liquibase plugin.
To enable corresponding features, make sure that the project contains the Liquibase dependency. It also provides a number of actions to quickly generate changelogs, run them, preview SQL statements, and so on.
Initialize schema
With IntelliJ IDEA, you can initialize your database schema based on the mappings provided in your JPA entities. It will generate a set of DDL commands for your current entities in the form of a Liquibase changelog.
Press Ctrl+Shift+A and start typing Liquibase Init Schema.
You can also open a Liquibase changelog file, press Alt+Insert, and select Liquibase Init Schema. In this case, the opened file parameters will be used in the Changelog Preview window.
To generate the DDL script based on the data model, select Model and specify the corresponding persistence unit.
IntelliJ IDEA provides an option to create migration scripts specifically for changes in selected entity changes. In the Scope list, click Selected Entities and, in the Select Entities for Custom Scope window, choose entities.
Changelog Preview Window
If you want to save the changelog as a regular file, then the following configuration options will be available:
Directory and File name fields are responsible for configuring the location of the generated changelog. If a changelog with the specified name already exists, you will be prompted with a warning, after which the changes will be appended to that changelog.
You can use Include to, Include folder, and Include context to specify whether a changelog should be included in another changelog. If you check the Include folder box, it generates the include statement for the entire folder, not just the current changelog.
From the File type drop-down list, you can choose one of the four file types (YAML, JSON, SQL, XML) supported by Liquibase, in which IntelliJ IDEA will generate the changelog.
If you want to save the changelog as a scratch file, then you can configure only its name and type.
The left side of the window shows a preview of the changesets that will be generated. You can click on each change to see what it will look like. To combine several changes into one changeset or to ignore them, simply drag and drop them. The top left corner of the preview window contains various actions to modify the resulting changelog:
The following actions are provided:
Add Changelog — create a secondary changelog
Add Change Set — create a new changeset in the selected changelog
Remove from Changelog with options:
Remove from Changelog — simply remove the changes from the current changelog
Remove and Ignore — remove the changes and add them to Ignored, so they are excluded from future changesets too
Restore from Ignored — move the changes from Ignored to the changelog
Set Context (for changesets)
Set Labels (for changesets)
Show Other Actions — select all changes based on the danger level, expand/collapse all changes
Create empty changelog
In the Project tool window, right-click the db/changelog directory.
Select New (or press Alt+Insert) and select Liquibase Empty Changelog.
In the New Liquibase Changelog dialog that opens, select an XML or YAML format for the changelog file.
This will create a new file based on the Liquibase file template. You can check all available file templates in the IDE settings (Ctrl+Alt+S), under .
IntelliJ IDEA provides you with coding assistance in XML and YAML Liquibase changelog files, including validation against the Liquibase schema, suggestion for known parameters, and navigation to property declarations and to included files.
Primary and Secondary Changelogs
IntelliJ IDEA lets you put the changes into two types of changelogs: Primary and Secondary. One use case for this is separating safe changes that can be run automatically and changes that require your attention and need to be run manually.
The changes can be separated automatically by their type (in ). Alternatively, you can create a secondary changelog manually in the Preview window using the Add Changelog action. Then you can simply drag the desired changesets into the new changelog.
By default, Primary and Secondary changelogs are generated in separate directories, which can be customized in the plugin settings. Read more in the IDE settings in the section.
Generate migration script
If a database connection is not established, create one.
In the Database tool window, right-click a database and select Create Liquibase Changelog.
Alternatively, open a JPA entity in the editor and do one the following:
Click
in the gutter and select Create Liquibase Changelog.Place the caret at an entity, press Alt+Enter to invoke intention actions, and select Create Liquibase Changelog.
In the dialog that opens, select a source (the desired state of the data model) and target (the old state of the data model).
You can choose between the following source options:
DB: should be used in case you have an up-to-date database and would like to generate migration scripts for updating another DB to the same state.
Model: use it to generate migration scripts representing the difference between the current state of the entity relationship model (JPA entities) and the old (target) state.
The target can be set to:
DB — target DB with an older version of the schema.
Snapshot — use this option in case you have the desired state stored in a data model snapshot. It can be generated by IntelliJ IDEA as well.
Click OK. IntelliJ IDEA will analyze the difference between Source and Target and show the Changelog Preview dialog.
If you want to save the changelog as a regular file, then the following configuration options will be available:
In the Directory field, specify the location where you want to save the changelog file.
In the File name field, enter the name of a generated changelog file.
You can use Include to, Include folder, and Include context to specify whether a changelog should be included in another changelog. If you select the Include folder checkbox, it generates the include statement for the entire folder, not just the current changelog.
In the File type list, you can choose one of the four file types (YAML, JSON, SQL, XML) supported by Liquibase, in which IntelliJ IDEA will generate the changelog.
If you want to save the changelog as a scratch file, select Scratch File on top of the Changelog Preview dialog and specify its name and type.
Navigate through changelog using the Structure tool window
If you have a lot of changesets in your Liquibase changelog file, the logical view of the Structure tool window can be useful to quickly preview the file and navigate through it. It shows change types as separate nodes, which you can expand to access more details.
The logical view is available for XML and YAML changelog files.
With your changelog file opened in the editor, open the Structure tool window: .
Alternatively, press Alt+7.
In the Structure tool window, open the Logical tab.
Click any change to navigate to its definition in the changelog file. For
includeandincludeAlltags, you will be redirected to the changeset in the included file.
Deploy the changes
Once your changelogs are ready, you can use a dedicated Liquibase run configuration to trigger the update and synchronize your database with your code. You can launch this run configuration from the run widget and from selected tool windows.
Run the update from the run widget
If the Liquibase run configuration is already selected in the widget, click
Run. Alternatively, press Shift+F10.
If another configuration is selected in the widget, click its name. In the popup that opens, find the Liquibase run configuration and click
Run next to it.Alternatively, press Alt+Shift+F10. In the popup that opens, select the Liquibase run configuration.
IntelliJ IDEA launches the Liquibase run configuration in the Run tool window.
Run the update from tool windows
You can launch the Liquibase run configuration from the following tool windows:
Persistence tool window:
Right-click a persistence unit, entity, or Liquibase changelog, and select
Run Liquibase Update….
Database tool window:
Go to the toolbar and select
Run Liquibase Update….Right-click a database, schema, or table, and select
Run Liquibase Update….
IntelliJ IDEA launches the Liquibase run configuration in the Run tool window.
Run the update from the root changelog
You can launch the Liquibase run configuration directly from your root changelog file if the spring.liquibase.change-log property in your application properties points to it.
Open your root changelog file.
In the gutter, click
Run Liquibase Update….
IntelliJ IDEA launches the Liquibase run configuration in the Run tool window.
Liquibase run configuration
The Liquibase run configuration lets you deploy your changes to a connected database without having to run the whole application or use the terminal. Under the hood, this configuration runs the Liquibase update command.
Create a Liquibase run configuration
Open the Run/Debug Configurations dialog:
In the main toolbar, click the run widget and select Edit Configurations….
Alternatively, go to .
On the left side of the dialog, select
Add New Configuration | 
Liquibase.Set up the run configuration options.
Run configuration options
Item | Description |
|---|---|
Name | Specify a name for the run configuration to quickly identify it among others when editing or running. |
Store as project file | Save the run configuration settings to a file that you can share with other team members. The default location is .idea/runConfigurations. However, if you do not want to share the .idea directory, you can save the configuration to any other directory within the project. By default, this option is disabled, and IntelliJ IDEA stores run configuration settings in .idea/workspace.xml. |
Required options
Item | Description |
|---|---|
Root changelog file | Specify the path to your root changelog file. |
DB connection | Specify which database Liquibase should target when running the changelogs. You need to select an existing data source from the Database tool window or create a new one by clicking |
.Additional options
To add these options to your run configuration, select Modify options on the right side of the dialog and then select the relevant options from the list.
Item | Description |
|---|---|
Context | Specify context filters to narrow down which changesets Liquibase will run during the update. In case of multiple values, separate them with commas. |
Labels | Specify label filters to narrow down which changesets Liquibase will run during the update. In case of multiple values, separate them with commas. |
Default schema | Specify the schema that Liquibase should manage. Learn more about this setting from Liquibase's official documentation. |
Liquibase schema | Specify the schema where Liquibase should create its tracking tables. Learn more about this setting from Liquibase's official documentation. |
Log level | Select the minimum severity level that should be logged during the update. Learn more about this setting from Liquibase's official documentation. |
Liquibase Settings
Base settings
Item | Description |
|---|---|
Liquibase version | Specify which Liquibase version you want to use in the project. If you leave this field empty, the IDE will use the version from your build file. |
Changeset author | Specify the value for the If you leave this field empty, the IDE will use the username from your operating system. |
File type | Select which language to use when generating changelogs:
|
Add empty rollback to changesets which don't support implicit one | Automatically add an empty To learn how to write rollback statements, refer to the official Liquibase documentation. |
Changelog Templates
Whenever an empty or differential Liquibase changelog is created, IntelliJ IDEA generates the file name based on the templates. You can configure primary/secondary directory and name of the changelogs.
The following variables and macros are available for the precise configuration:
#increment(<start>, <step>, <decimalFormat>): generate versions using a numeric sequence.start: version number for the first migrationstep: value to increase each version number bydecimalFormat: DecimalFormat pattern used to format the version number
#date(<simpleDateFormat>): generate versions using the current system date.simpleDateFormat: SimpleDateFormat pattern used to format the date
${semVer.<getterMethod>}: generate versions using the semantic version from the project's build file.getterMethod: method that extracts a specific segment of the semantic version. Here are examples for a 1.2.3-SNAPSHOT+build4 version:${semVer.getRawVersion()}: 1.2.3-SNAPSHOT+build4${semVer.getMajor()}: 1${semVer.getMinor()}: 2${semVer.getPatch()}: 3${semVer.getPreRelease()}: SNAPSHOT
DB Types
Sometimes software must provide support for a few DBMS types. In this case, Liquibase is the best choice, as it offers a cross-DB solution to declare DDL modifications. IntelliJ IDEA supports this solution as well. When generating cross-DB changelogs, it uses Liquibase properties to specify correct data types for each DBMS:
Therefore, there is no need to create separate changelogs for different DBMSes.
Changeset Templates
The Changeset Templates settings let you preconfigure commonly used changeset attributes for each change type. IntelliJ IDEA will automatically insert them into the relevant changesets every time you generate a changelog.
Item | Description |
|---|---|
Select what Liquibase should do if it encounters an error while executing the changeset:
| |
Select what Liquibase should do if it detects that an already executed changeset has been modified:
| |
Create Preconditions | Automatically add relevant preconditions to the changeset and select what Liquibase should do if they are not met:
|
Additional features for Spring projects
On top of the standard Liquibase support provided by IntelliJ IDEA, projects based on the Spring framework can leverage additional IDE features.
Statuses of changelogs and changesets
Typically, if you want to check which changelogs were already applied, you need to either run Liquibase's change tracking commands or inspect its changelog table in your database. IntelliJ IDEA provides a faster alternative by displaying the statuses of your changes directly in the IDE.
Statuses of whole changelog files are displayed in the Project tool window (Alt+1).
Each changelog is represented by the Liquibase logo (), and its status is reflected by a small icon in the logo's lower-right corner:
Icon | Status |
|---|---|
| All changesets in the changelog were successfully applied to the database. |
| The changelog was run, but one of its changesets failed. You can find out more about the error by hovering over the file name.  To check which changeset caused the error, open the underlined changelog in the editor and look for a red exclamation mark in the gutter.  |
(None) | Status icons are not displayed in the following cases:
|
Statuses of particular changesets are displayed in the editor gutter when you open a changelog file.
JPA Buddy features
You can install the JPA Buddy plugin to get even more support for Liquibase:
JPA Designer
The JPA Designer tool window lets you generate and modify code.
In the upper part of the tool window (JPA Palette), select an action for example, Create, and then double-click an element, for example, Table.
The lower part of the tool window (JPA Inspector) adapts to the selected element of the changelog, for example, a changeSet, and allows you to modify its attributes.
To learn more about JPA Designer, refer to Entity Designer.
Editor toolbar
The Editor Toolbar provides fast access to relevant actions. It includes:
An action to select the opened file in JPA Structure
All actions from JPA Palette
Init Schema Changelog action
Diff Changelog action
JPA Buddy understands your data model and prefills the changesets as much as possible. And with the help of JPA Inspector you can explore the attributes of each changelog element:
Troubleshooting
- Changelogs or changesets are displayed without status icons
This feature is only available in Spring projects. If your project does use Spring, make sure that:
You added the Liquibase dependency to your project's build file.
You connected to the corresponding database, and the connection is active in the Database tool window.
Your configuration file (application.properties or application.yml) meets the following criteria:
spring.liquibase.change-logpoints to your root changelog file.spring.liquibase.urlorspring.datasource.urlmatches the URL you used to connect to the database.
You already ran a Liquibase update, and its results were recorded in the database changelog table.