Upgrade Guide

Overview

This article explains the best practices for upgrading eXist-db. It introduces key concepts and provides instructions for different types of upgrades. Following these instructions will ensure your data is properly backed up and preserved during the upgrade process.

Key concepts

The primary goal of an eXist upgrade is to migrate your eXist application to a new version while preserving the contents of your database.

Before embarking on an upgrade, you should first review the new version's release notes (see the eXist Developer's Blog for an archive of all past release notes). The release notes introduce the new version's new features, improvements, and bug fixes, but they also outline any new requirements (e.g., the required version of Java). For the purpose of this guide, the most important item in the release notes is whether the new version is binary-compatible with the previous version or not. Pay close attention to these notes, as they will tell you which upgrade route to follow here.

If a new version is binary-compatible with the previous version, it means that the format eXist uses to store the contents of the database has not changed, so the data can be used by new version without modification. However, if a new version is not binary-compatible, then it means that the new version of eXist has changed the way it reads data from or stores data into the database. As a result, some additional steps are required to migrate your data to the new version of eXist.

You should always back up your data before upgrading to any new version of eXist; the directions below indicate when and how to perform a backup. Why is backing up data important before an upgrade? Of course, upgrade procedures are tested with each release, but as with any software upgrade, unexpected events can occur, so these procedures give you a backup of your data that you can revert to with your previous version of eXist and resume work.

For the same reason, you should not install the new version of eXist over the previous version. Instead, these instructions have you install the new version into a fresh new directory.

Binary Compatible Upgrades

Follow these steps if the new version of eXist is binary-compatible with the your old version. Check the new version's release notes to find out whether it is binary compatible with your old version.

  1. Stop the old installation of eXist, if it is running.

  2. Create a backup of the data from your old installation of eXist.

  3. Install the new version of eXist. Do not install one eXist version over another one. Always install the new version into a fresh new directory.

  4. Remove the empty data directory from the new installation. Typically the data directory is located in webapp/WEB-INF/data. If you are not sure where the data directory is located, you can check the exist.log, searching for entires after startup pertaining to DATA_DIR.

  5. Copy the entire old data directory, and paste it to the location of the directory you just deleted in the previous step.

  6. Start the new eXist instance.

  7. Check the exist.log for any errors during startup.

Binary Non-compatible Upgrades

Follow these steps if the new version of eXist is not binary-compatible with the your old version. (Check the new version's release notes to find out whether it is binary compatibility with your old version.) Additional steps are required when upgrading to a new version of eXist whose database format is not binary-compatible with your old installation. The key difference is that you must perform a full restore of your backed up data onto the new installation of eXist, rather than simply copying the data directory to the new installation.

  1. Create a server-side backup. This can be done in a number of ways:

    1. Use Backup Central from the Dashboard (with "Zip" option for databases with less then 4GB)

    2. The Emergency Backup Tool (GUI) for installer based systems:

      java -jar start.jar -Xmx2048m org.exist.backup.ExportGUI
    3. The Emergency Backup Tool (CLI) for headless sytems:

      java -jar start.jar org.exist.backup.ExportMain -x -z
    4. Via XQuery:

      system:trigger-system-task("org.exist.storage.ConsistencyCheckTask", <parameters> <param name="backup" value="yes"/> <param name="output" value="export"/> </parameters>)

    Once the backup is complete, you should check the backup report in the export directory within either the data directory (for backups created via the Dashboard, or Xquery) or $EXIST-HOME (for Backups created by the Emergency Backup Tool).

    Normally this report just contains the list of collections which were backed up. If you see any warnings or errors, it is especially important that you perform a “full restore” of your backed-up data onto the new installation of eXist.

  2. Stop the old installation of eXist.

  3. Install the new version of eXist. (Again, do not install one eXist version over another one. Always install the new version into a fresh new directory.)

  4. Perform a full restore of the backup onto the new version of eXist.

History of Non-compatible Upgrades

This is a list of binary non-compatible releases for quick reference.

Should you need to perform non-incremental upgrade across mutiple non-compatible releases, e.g. from 1.4 to 3.6, we strongly recommend to first check past release notes to understand how breaking changes might affect you.

After making the necessary changes to your old instance, we recommend to attempt a longjump upgrade, ie. restoring into the latest desired version. YMMV.

latest release notes
3.0 special notes
2.2 special notes
2.0 special notes
1.4.0 special notes
Notes on previous releases