Documentation Home
Changelog

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 pointed to will be referred to as broadleaf-updated

  4. Modify your application properties to ensure that Hibernate will automatically update the schema.

    If you are using Community edition, 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 modifications 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 with Hibernate set to update, you now have a version of the fully updated database (the broadleaf-updated schema your application was pointing to before).

  6. Now it is time to compare broadleaf-original and broadleaf-updated to generate the changelog necessary to move to different environments. 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) is the other, non-reference connection properties. The following example is for MySQL. For other databases, you will need to change the --classpath and --driver to 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, if you prefer your changelogs as sql:

    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. Most likely, the only tables that should be changed are Broadleaf tables relevant to what you're upgrading, either a specific module or the entire framework.

  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