Upgrade Guide

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 at $EXIST_HOME/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

   2. The Emergency Export Tool (GUI):

      1. Unix/Linux:

         bin/export-gui.sh

      2. Windows:

         bin\export-gui.bat

   3. The Emergency Backup Tool (CLI) for headless sytems:

      1. Unix/Linux:

         bin/export.sh

      2. Windows:

         bin\export.bat

   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.

Upgrading from Source

The following steps only apply to users who wish to upgrade eXist instances that were built from (modified) source code, instead of from the provided installers.

Before attempting to upgrade always perform a full backup. Stop eXist after the backup has been generated.

1. Determine which files contain local modification and would be in conflict with updated files from the new version of exist-db, by running git status inside the local folder where you cloned exist. You should pay special attention to Configuration files, such as:

   • etc/conf.xml

   • etc/webapp/WEB-INF/controller-config.xml

   • etc/jetty/webapps/exist-webapp-context.xml

2. A typical sequence to replay the local modifications on top of the upstream changes to the master branch would look like this:

   git fetch
   git stash
   git rebase origin/master
   git stash pop
   

3. Finally follow the build instructions for eXist-db.

Upgrading docker images

When following eXist-db's stable release channel via the docker release tag, orchestrators will automatically check and pull newer images. To avoid that you accidentally pull a binary incompabtile image that will break your container, we recommend testing your app on a continous integration service on both release, and latest. This way your CI will inform you and prevent incompatible upgrades making it into production.

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, for instance from 1.4 to 3.6, we strongly recommend to first check past release notes to understand how breaking changes might affect you.