Skip to main content

journal-upgrade & journal-downgrade

Overview​

Occasionally, Ember undergoes changes to its Journal format, requiring a one-time migration procedure. This document outlines the steps for performing the migration when prompted by the system.

In some special cases, you may need to consider a journal downgrade procedure, which allows you to roll back to the previous journal format version if required.

Symptoms​

During Ember startup, you may encounter the following error message, indicating that a journal format migration is required:

2020-09-11 17:00:17.530 FATAL [main]: Startup failed. Error:
deltix.anvil.journal.JournalException: Journal version 20 does not match with expected 21. Erase old journal or convert it to new format
       at deltix.anvil.journal.Journal.verifyVersion(Journal.java:784)
       at deltix.anvil.journal.Journal.verifyMeta(Journal.java:487)
       at deltix.anvil.journal.image.JournalImage.mapMeta(JournalImage.java:256)

Prerequisites​

Before proceeding with the journal migration, ensure the following:

  • Stop Ember processes: The Ember process itself and ALL Ember satellite processes such as Ember Monitor, Ember Data Warehouse, Ember Journal Compactor, and Deltix Trading node must be STOPPED when the journal migration takes place.
  • Disk space: Make sure you have enough disk space. Measure the size of the $EMBER_WORK\journal directory and ensure that you have that much free space.

Journal Upgrade Procedure​

The journal format migration can be performed using a special utility called journal-upgrade.

  1. Define the EMBER_WORK environment variable. The journal-upgrade tool relies on it to locate the $EMBER_WORK/journal subdirectory.

  2. Start the journal-upgrade tool. It will prompt you for confirmation before proceeding with the upgrade:

    #export EMBER_WORK=/deltix/emberwork
    #/deltix/ember/bin/journal-upgrade
    This tool will upgrade journal format to version 21.
    Would you like to proceed? (y/n): y
    Upgrading journal from version 20 to 21...
    Successfully upgraded journal to version 21
    Backup of the journal is stored in /deltix/emberwork/journal_20_backup

A backup of the previous journal will be saved under EMBER_WORK in the journal_N_backup directory, where N is original format version. For example, it will be under /deltix/emberwork/ journal_20_backup in the example above.

Journal Downgrade Procedure​

In some special abnormal cases, you may want to roll back a new journal version update.

You have two options:

  • Restore Ember Journal from a backup.
  • Use the special journal-downgrade utility.

The first option is faster and may seem more straightforward. However, the new version might have already processed some important events (e.g., trades), and the backup journal version will not include them. In situations like these, use the journal-downgrade tool.

Here is an example of running the journal-downgrade tool:

#\deltix\ember\bin\journal-downgrade 20
This tool will downgrade journal format to version 20.
Would you like to proceed? (y/n): y
Downgrading journal from version 21 to 20...
Successfully downgraded journal to version 20
Backup of the journal is stored in /deltix/emberwork/journal_21_backup