Database Migrations with JPA Buddy & Liquibase - VittorioDeMarzi/hero-beans GitHub Wiki

Prerequisites ✅

  • You have IntelliJ IDEA Ultimate with the JPA Buddy plugin installed.
  • The liquibase-core dependency is added to your project (e.g., in build.gradle).
  • Your application is connected to an empty database (no schema or tables) via your application.properties file.
  • You are familiar with the concepts shown in the video: Use Liquibase with JPA/Hibernate entities in IntelliJ IDEA

A Designer-First Guide to Database Migrations with JPA Buddy & Liquibase

This documentation will guide you through managing your database schema by first modeling it visually in the JPA Designer.

1. Generating the Initial Schema 📜

First, we'll generate the initial database schema from your existing JPA entities. This process compares your entity definitions with the empty database and creates the necessary SQL to match them.

  1. Open the JPA Structure Panel: On the right side of your IntelliJ IDEA, open the "JPA Structure" tab.

  2. Select Entities: In the JPA Structure panel, select all the entities you want to include in your initial schema. You can use Ctrl+A (or Cmd+A on Mac) to select all of them.

  3. Generate Diff Changelog: Right-click on the selected entities and navigate to JPA Buddy -> Diff Changelog....

  4. Configure the Changelog: In the dialog box that appears:

    • Choose the "Model" as the source and the "DB" as the target. This tells JPA Buddy to compare your code (Model) to the database (DB).
    • Under "Changelog Properties," you can specify the file name for this initial schema setup. A good practice is to name it something descriptive, like 01-initial-schema.xml.
    • Click "OK".

  5. Review the Generated Changelog: JPA Buddy will now generate a new XML file in your src/main/resources/db/changelog directory. This file contains the necessary instructions for Liquibase to create the tables, columns, and constraints based on your entities.

2. Creating the Master Changelog मास्टर

The master changelog is the main entry point for Liquibase. It includes all other changelog files in the order they should be executed.

  1. Create a New File: In the src/main/resources/db/changelog directory, create a new file named master.xml.

  2. Add Master Changelog Boilerplate: Open the master.xml file and add the basic Liquibase XML structure:

    <?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                            http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.9.xsd">

</databaseChangeLog>

  3. Include the Initial Schema Changelog: Inside the <databaseChangeLog> tags, add an <include> tag to reference the initial schema file you created in the previous step.

    <include file="db/changelog/01-initial-schema.xml"/>

  4. Configure application.properties: It's crucial to configure your application.properties (or .yml) file correctly. This ensures that Liquibase is in full control of the database schema and avoids conflicts with Hibernate.

    # Disable Hibernate's automatic schema management (e.g., create, update, create-drop).
# This gives Liquibase exclusive control over the DB schema.
spring.jpa.hibernate.ddl-auto=none

# Explicitly enable Liquibase (this is the default, but it's good practice to set it).
spring.liquibase.enabled=true

# Tell Liquibase where to find the main changelog file.
spring.liquibase.change-log=classpath:db/changelog/master.xml

At this point, when you run your application, Liquibase will read the master.xml file, find the included 01-initial-schema.xml, and execute it to create your database tables.

3. Modifying Entities and Creating a New Changelog ✏️

Now, let's say you need to add a new field to one of your entities. The process is similar to creating the initial schema, but this time JPA Buddy will only generate the changes.

  1. Modify Your Entity: Open one of your JPA entity classes and add a new field. For example, you might add an email field to a User entity.

    @Column(name = "email")
private String email;

  2. Generate a New Diff Changelog:

    • In the JPA Structure panel, right-click on the entity you just modified.
    • Go to JPA Buddy -> Diff Changelog....

  3. Configure the New Changelog:

    • Again, choose "Model" as the source and "DB" as the target.
    • Give this new changelog a descriptive name, following a sequential naming convention, for example, 02-add-email-to-user.xml.
    • Click "OK".

  4. Review the New Changelog: A new XML file will be generated containing only the ALTER TABLE statement needed to add the new email column.

  5. Update the Master Changelog: Open your master.xml file and add a new <include> tag for the new changelog you just created. It's crucial to add it after the existing ones to maintain the correct order of execution.

    <?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
                            http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.9.xsd">

    <include file="db/changelog/01-initial-schema.xml"/>
    <include file="db/changelog/02-add-email-to-user.xml"/>

</databaseChangeLog>

Now, the next time you run your application, Liquibase will see that the first changelog has already been executed and will only apply the new one, adding the email column to your user table. You have successfully updated your database schema to match your JPA entities! ✨

⚠️ **GitHub.com Fallback** ⚠️