Liquibase - Heigvd/Wegas GitHub Wiki

Changes in the data model

What you need

When changes are made to the data model, the database must be updated to reflect these changes.

Two databases are used:

  1. the first to run automated tests: the "wegas_test" database
  2. the second for live usage (local dev, prod, ...): the "wegas_dev" database

The way in which these changes are reflected is different in each case.

Test database

The test database is automatically reset before running the tests (JPA drop-and-create strategy). Thus, all data are loss... But the database structure is up-to-date regarding the datamodel.

Live Database

Data loss is not an option for the live database. Thus, database must be thoroughly migrated to reflect the JPA model.

Such refactors (changelogs) are defined with the help of Liquibase. They are stored in wegas-core/src/main/resources/dbchangelogs/. The changes are applied during the deployment of the webapp.

Writing those changeLogs may be painful. Luckily, Liquibase ships with handy tools (download here) to ease writing changeLogs. We are especially interested in the diffChangeLog tool.

This tool compute a changeLog between a database (FROM) and a reference (TO). In our case, the database is the live database, the reference is the test database.

Here is a script which stores the diff changeLog in an XML file named after the current timestamp. You can save it in a run-liquibase-diff.sh file and adjust the path to the liquibase folder and maybe the ports, users, passwords.

#!/bin/bash

LIQUIBASE_FOLDER=<PATH TO THE LIQUIBASE FOLDER YOU JUST DOWNLOADED>

## The 'production' database
FROM_PG_HOST=localhost
FROM_PG_PORT=5432
FROM_DB_NAME=wegas_dev
FROM_USER=user
FROM_PASSWORD=1234

## The 'test' database
TO_PG_HOST=localhost
TO_PG_PORT=5432
TO_DB_NAME=wegas_test
TO_USER=user
TO_PASSWORD=1234

FILENAME=`date +"%s"`.xml

${LIQUIBASE_FOLDER}/liquibase \
    --changeLogFile=${FILENAME} \
    --url="jdbc:postgresql://${FROM_PG_HOST}:${FROM_PG_PORT}/${FROM_DB_NAME}" \
    --username=${FROM_USER} \
    --password=${FROM_PASSWORD} \
    diffChangeLog \
    --referenceUrl="jdbc:postgresql://${TO_PG_HOST}:${TO_PG_PORT}/${TO_DB_NAME}" \
    --referencePassword=${TO_PASSWORD} \
    --referenceUsername=${TO_USER}

DIFF_RC = $rc

if [ "$?" -ne 0 ](/Heigvd/Wegas/wiki/-"$?"--ne-0-) ; then
  echo 'could not generate diff';
  exit $DIFF_RC;
else
  echo
  echo 'Successful !'
  echo
  echo "Please review the changeLog (${FILENAME}) then";
  echo '  1. move it to the changelogs directory: '
  echo "       mv ${FILENAME} wegas-core/src/main/resources/dbchangelogs/"
  echo '  2. build the war'
  echo '       mvn install -DskipTests -DskipYarn'
  echo '  3. run the app (in wegas-runtime)'
  echo '       ./run'
  echo
  exit $DIFF_RC;
fi

If there is no structural change between the two databases, no file is generated.

How to

You need liquibase to be installed.

  1. Do changes in the datamodel
  2. Build wegas-core (mvn -pl wegas-core install -DskipTests)
  3. Run any test (e.g. mvn test -pl wegas-core -Dtest=AnnouncementFacadeTest#getAllTest)
  4. Execute the liquibase diff script (run-liquibase-diff.sh)
  5. Review the changeLog
  6. Move it to the changelogs directory (wegas-core/src/main/resources/dbchangelogs/)
  7. Build the app (mvn install -DskipTests -DskipYarn)
  8. Deploy wegas (./run in wegas-runtime)

databasechangelog

Liquibase will add two tables in the database : databasechangelog and databasechangeloglock.

The table databasechangelog keeps the trace of which changes are already executed based on unique file names and a check sum of their content.

Change set application

When running wegas the unapplied changes are applied to the database (likely wegas_dev). Each change set will result in an [liquibase.changelog] log output that looks like

ChangeSet dbchangelogs/1774959964.xml::1774959984613-9::username ran successfully in 46ms

To double check the applied changes directly in DB see PostgreSQL-DB wiki

Resources