Upgrade Guide

(1Q18)


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

Introduction

The primary goal of an 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 features, improvements and bug fixes. They can also outline any new requirements (for instance 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.

If a new version is binary-compatible with the previous version, it means the format eXist uses to store the contents of the database has not changed. The data can be used by new version without modification.

However, if a new version is not binary-compatible, the new version of eXist has changed the way it reads data from or stores data into the database. Additional steps are required to migrate your data to the new version of eXist.

Always back up your data before upgrading to any new version of eXist.

Do not install the new version of eXist over the previous version. Instead, 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 (as can be found in the release notes):

  1. Stop the existing installation of eXist.

  2. Create a backup of the data from your existing installation.

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

  4. Remove the still empty data directory from the new installation. By default the data directory is located in webapp/WEB-INF/data. If you are not sure where the data directory is, check the main logfile exist.log , searching for entries after start-up pertaining to DATA_DIR.

  5. Copy the entire existing data directory, and paste it to the location of the new data directory (the directory you 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 (as can be found in the release notes). The key difference with upgrading to a binary-compatible new version is that you have to perform a full restore of your backed-up data into 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 even more important to perform a “full restore” of your backed-up data.

  2. Stop the existing 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. 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.

If a non-incremental upgrade across multiple non-compatible releases is necessary, foir instance from 1.4 to 3.6, we strongly recommend to first check past release notes to understand how breaking changes might affect you.

latest

release notes

3.0

special notes

2.2

special notes

2.0

special notes

1.4.0

special notes