Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack

Documentation

Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

As of version 1.5, we use the Liquibase library to define and run each incremental changeset. The changeset file is stored in metadata/model/api/src/main/resources/liquibase-update-to-latest.xml.

As each changeset is executed, it is logged in the user's liquibasechangelog table. Future runs of the changelog file will check the liquibasechangelog table first to see if the changeset has been executed. If it has, then the change is skipped.

...

Workflow for Adding a Change

Step One: Be sure you are running the latest version

  • Make sure you are running the most recent version of your branch (aka, trunk, 1.5.x, etc). Someone might have committed other database changes to tables you are changing.
  • Deploy this war file to get your (version specific hopefully) database up-to-date and your changes will be going against the latest version.

Step Two: Update the database script file

  1. Open the /metadata/model/liquibase-update-to-latest.xml file.
  2. Add your update to the end using liquibase's format for updates. See the liquibase manual for help.
    • Use any unique string for the "id". The current date+time is an easy one e.g: 200804221449-1
    • Use your trac username for the "author"
    • Be sure to add a "comment" element in your changeSet, it is displayed in the webapp for end users to see

Step Three: Deploy OpenMRS to Run the Changes

  • When you compile and deploy the war file, openmrs will prompt you to run the database updates. Run them now to make sure they work correctly.

Step Four : Make related code changes

Obviously, all database related Hibernate mapping files must be updated to work with your new latest datamodel change.

Commit both the liquibase xml file and code changes simultaneously to the subversion repository.

Step Five: Update the wiki datamodel changelog (Optional)

We keep tallies on each major revision changes in the Changelog. Place each of your updates on the page in the form described there. This will make it a lot easier (for the Release Manager) when it comes time for the major version change.

...

Warnings

Never ever change a changeset!

Once you commit something to a branch, you should assume that another developer has already checked out your code and applied the database changes! Therefore, you should not just go and modify a changeset! Instead you should add another changeset below the previous one that does the necessary modifications. That way no developers have to go and mess with their database to get the changesets to apply.

If a changeset contains an error, you obviously must change it. However, you should change the liquibase changeset "id" on the element when you do so to prevent errors with other developers.=

Preconditions are important

...

You should always use a precondition in your changeset and not solely rely on liquibase comparing the id to the liquibasechangelog table. This is helpful for users that are upgrading from a 1.5.3 to a 1.6.0 because there have been changes (.1, .2, and .3) that happened to both the 1.5.x branch and to trunk.

Small Changesets are good

Each changeset should only be one logical unit. This allows the changeset to have a simple precondition and makes error recovery simple if the server crashes while running an update.

...

About the liquibase-data.zip file

When a new minor version (1.4-->1.5) is released, the liquibase-data.zip file should be updated. This is the only time the files in the /metadata/model/liquibase-data.zip will be updated. Developers should only worry about adding their change to the liquibase-update-to-latest.xml file.