Documentation Home

Generating Data Model Changes with Liquibase

Upgrading major/minor versions of Broadleaf core or installing/upgrading new modules usually requires the addition of new columns or tables to your database. This guide will walk you through generating these schema migrations against your database platform in order to confidently deploy the upgrade to your qa/production environments.

If you are not already using Liquibase to automatically run data migrations for you, see Setting up Liquibase.

  1. Download the liquibase binaries so that you can execute them from a command line (http://www.liquibase.org/download/)

    If you are already using Liquibase locally the versions should match. You can also take the .jar file directly from your `~/.m2/repository

  2. Download the JDBC driver jar for the database you are using. Some examples (versions could be different depending on your specific database version):

  3. Create a copy of your existing database into a new schema. This new schema will be referred to as broadleaf-original and will serve as the base for the database diff. The schema that your project is point to will be referred to as broadleaf-updated

  4. [[Modify your application properties | Environment Properties]] to ensure that Hibernate will automatically update the schema. If you are using community, you will need to set these values:

    blPU.hibernate.hbm2ddl.auto=update
    blSecurePU.hibernate.hbm2ddl.auto=update
    blCMSStorage.hibernate.hbm2ddl.auto=update
    blSecurePU.hibernate.hbm2ddl.auto=update
    

    For Enterprise, you will also need to change the auto ddl for blEventPU:

    blPU.hibernate.hbm2ddl.auto=update
    blSecurePU.hibernate.hbm2ddl.auto=update
    blCMSStorage.hibernate.hbm2ddl.auto=update
    blSecurePU.hibernate.hbm2ddl.auto=update
    blEventPU.hibernate.hbm2ddl.auto=update
    
  5. Go through any code mofications necessary for the project to fully start up. If you are adding a new module, this means add the module to your dependencies. If you are upgrading Broadleaf or dependent modules, this means completing the upgrade from a code perspective. After you have finished starting up the application, you now have a version of the fully updated database (the broadleaf-updated schema your application was pointing to before). Now it is time to compare the 2 to generate the changelog to move to different environments

  6. Take the liquibase jar from step 1 and execute the diffChangeLog command, passing in the JDBC URLs for the broadleaf-updated as the "reference" connection. The original, unchanged database (broadleaf-original) are the other, non-reference connection properties. The following example is for MySQL, for other databases you will need to change the --classpath and --driver for your database driver.

    java -jar liquibase-core-3.5.3.jar --classpath=/path/mysql-connector-java-5.1.32.jar --driver=com.mysql.jdbc.Driver --url=jdbc:mysql://localhost:3306/broadleaf-original --username=username --password=password --referenceUrl=jdbc:mysql://localhost:3306/broadleaf-updated --referenceUsername=username --referencePassword=password diffChangeLog > broadleaf-update.xml
    

    This command generates a file called broadleaf-update.xml. This is a Liquibase changelog file that you can give to Liquibase to perform the migration. This file can be converted to SQL by executing the following command:

    java -jar liquibase-core-3.5.3.jar --classpath=/Users/broadleaf/lib/mysql-connector-java-5.1.32.jar --driver=com.mysql.jdbc.Driver --changeLogFile=broadleaf-update.xml --url=jdbc:mysql://localhost:3306/broadleaf-new --username=username --password=password updateSQL > broadleaf-update.sql
    
  7. Now that the changelog file has been generated, you can review the the diff of the schema changes and make any adjustments

  8. Apply the changelog to all environments. We recommend having Liquibase run as a Spring bean on startup to ensure all databases are kept in sync, documented here