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.
Add Liquibase to an existing project
Open the build file in the editor (pom.xml or build.gradle depending on the build tool used in your project).
Add the Liquibase library, and make sure its version matches the rest of your project:
<dependency> <groupId>org.liquibase</groupId> <artifactId>liquibase-core</artifactId> <version>4.32.0</version> </dependency>implementation 'org.liquibase:liquibase-core:4.32.0'implementation("org.liquibase:liquibase-core:4.32.0")Press Ctrl+Shift+O to import the changes.
For more information about working with build tools, refer to Maven or Gradle.
Generate an init changelog
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.
Open the Persistence tool window.
In the tool window, right-click a persistence unit or entity, and select
New | 
Liquibase Init Changelog.In the Init Schema Changelog dialog that opens, select which data model the migration should be based on:
Model: entity mappings from a persistence unit
DB: schema from a connected database
Based on your selection, IntelliJ IDEA automatically fills in the persistence unit or database connection, which you can change if needed.
Click OK.
In the Changelog Preview dialog that opens, configure the changelog and click Save.
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 a diff changelog
Make sure IntelliJ IDEA is connected to your database.
Open the Database tool window, right-click a database or table, and select
Create Liquibase Changelog….Alternatively, open the Persistence tool window, right-click a persistence unit or entity, and select
New | Liquibase Changelog….
In the Diff Database Changelog dialog that opens, select which data models to compare:
Source (referenceURL) (current data model):
DB: schema from a connected database
Model: entity mappings from a persistence unit
Target (URL) (previous data model):
DB: schema from a connected database
Snapshot: schema from a data model snapshot
If you select DB or Model, IntelliJ IDEA automatically fills in the database connection or persistence unit, which you can change if needed.
Click OK.
In the Changelog Preview dialog that opens, configure the changelog and click Save.
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.