Search…
Upgrading
As with any software upgrade, it is important that you back up your data before you upgrade HEAVY.AI. Each release introduces efficiencies that are not necessarily compatible with earlier releases of the platform. HEAVY.AI is never expected to be backward compatible.
Back up the contents of your $HEAVYAI_STORAGE directory, where all data and configuration information are stored.

Considerations when Upgrading from Release 5.x to Release 6.0

Before Upgrading to Release 6.0

IMPORTANT - Before you begin, create a backup of your $OMNISCI_STORAGE folder (typically /var/lib/omnisci). A backup is essential for recoverability; do not proceed with the 5.x-to-6.x upgrade without confirming that a full and complete backup is available and ready. In addition, you should also back up omnisci.conf and servers.json.
  • Create a backup of the data directory.
  • Rename the /data directory to /storage before starting the server
  • If you are using the default Docker image command or default systemd command, rename omnisci.conf to heavy.conf.
If upgrading, your omnisci database will not be automatically renamed to the new default name heavyai.

Essential Changes for Release 6.0

The following table describes the changes to environment variables, storage locations, and filenames in Release 6.0 compared to Release 5.x. Except where noted, revised storage subfolders, symlinks for old folder names, and filenames are created automatically on server start. Change descriptions proceeded by ** Manual Change ** require user intervention.
Description
Release 5.x
Release 6.0
Environmental variable for storage location
$OMNISCI_STORAGE
$HEAVYAI_STORAGE
** Manual Change - OPTIONAL ** Default location for $HEAVYAI_STORAGE / $OMNISCI_STORAGE
/var/lib/omnisci
/var/lib/heavyai
$HEAVYAI_STORAGE / $OMNISCI_STORAGE location in Docker images
/omnisci-storage
/var/lib/heavyai
** Manual Change ** storage/ Storage/data folder (located inside your $OMNISCI_STORAGE directory)
data/
storage/
Storage subfolder - data
data/mapd_data
storage/data
Storage subfolder - catalog
data/mapd_catalogs
storage/catalogs
Storage subfolder - import
data/mapd_import
storage/import
Storage subfolder - export
data/mapd_export
storage/export
Storage subfolder - logs
data/mapd_log
storage/log
Server INFO logs
omnisci_server.INFO
heavydb.INFO
Server ERROR logs
omnisci_server.ERROR
heavydb.ERROR
Server WARNING logs
omnisci_server.WARNING
heavydb.WARNING
Web Server ACCESS logs
omnisci_web_server.ACCESS
heavy_web_server.ACCESS
Web Server ALL logs
omnisci_web_server.ALL
heavy_web_server.ALL
Install directory
/omnisci (Docker images) /opt/omnisci (suggested location for bare metal install)
/opt/heavyai/ (both Docker and bare metal)
Binary file - core server (located in install directory)
bin/omnsici_server
bin/heavydb
Binary file - web server (located in install directory)
bin/omnisci_web_server
bin/heavy_web_server
Binary file - command- line SQL utility
bin/omnisql
bin/heavysql
Binary file - JDBC jar
bin/omnisci-jdbc-6.0.0-SNAPSHOT.jar
bin/heavydb-jdbc-6.0.0-SNAPSHOT.jar
Binary file - Utilities (SqlImporter) jar
bin/omnisci-utility-6.0.0-SNAPSHOT.jar
bin/heavydb-utility-6.0.0-SNAPSHOT.jar

After Upgrading to 6.0

If you attempt to run an old release using the migrated storage/data directory, you could see the following error on server startup:
FileMgr.cpp:1104 Table storage forward compatibility is not supported. Version of OmniSci software used is older than the version of table being read: 2
In this case, a manual data version rollback is required for older releases to work with migrated storage directories. Follow these steps:
  1. 1.
    Create a backup of the data directory.
  2. 2.
    Run the following on the command line, replacing {path_to_storage_directory} with the path to the storage/data directory:
echo -n -e '\x1\x0\x0\x0' | tee {path_to_storage_directory}/data/table_*/filemgr_version

Upgrading Using Docker

To upgrade HEAVY.AI in place in Docker, stop the Docker container, back up your data directory, then run the HEAVY.AI Docker install command.
  1. 1.
    In a terminal window, get the Docker container ID:
    1
    docker container ls
    Copied!
    You see output similar to the following. The first entry is the container ID. In this example, it is 9e01e520c30c:
    1
    CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
    2
    9e01e520c30c heavyai/heavyai-ee-cpu “/bin/sh -c ‘/heavyai...” 3 days ago Up 3 days 0.0.0.0:6273-6274->6273-6274/tcp confident_neumann
    Copied!
  2. 2.
    Stop the HEAVY.AI Docker container. For example:
    1
    docker container stop 9e01e520c30c
    Copied!
    Optionally, remove the HEAVY.AI Docker container. This removes unused Docker containers on your system and saves disk space. For example:
    1
    docker container rm 9e01e520c30c
    Copied!
  3. 3.
    Back up the storage directory on the host machine. The default location is ~/var/lib/heavyai.
  4. 4.
    Download the latest version of Docker.
    For Enterprise edition without GPUs:
    1
    docker pull heavyai/heavyai-ee-cpu
    Copied!
    For Enterprise edition with GPUs:
    1
    docker pull heavyai/heavyai-ee-cuda
    Copied!
  5. 5.
    Run the Docker run command.
    For Enterprise edition without GPUs:
    1
    sudo docker run --name=heavyai \
    2
    -d \
    3
    -v /var/lib/heavyai:/var/lib/heavyai \
    4
    -p 6273-6280:6273-6280 \
    5
    heavyai/heavyai-ee-cpu:v5.4.0
    Copied!
    For Enterprise edition with GPUs:
    1
    sudo docker run --name=heavyai \
    2
    -d --runtime=nvidia \
    3
    -v /var/lib/heavyai:/var/lib/heavyai \
    4
    -p 6273-6280:6273-6280 \
    5
    heavyai/heavyai-ee-cuda:v5.4.2
    Copied!
This runs both HEAVY.AI server and Immerse web server in that container.
You can optionally add --rm to the Docker run command so that the container is removed when it is stopped.
When upgrading from a significantly earlier version, there might be internal changes that invalidate the metadata in the /var/lib/heavyai directory. You can rename the directory or point to a different directory to run a later version of HEAVY.AI.
See also the note regarding the CUDA JIT Cache in Optimizing Performance.

Upgrading Using Yum

To upgrade an existing system installed with Yum to the latest version, you run the Yum update command. The command upgrades HEAVY.AI in place without disturbing your configuration or stored data.
To upgrade HEAVY.AI using Yum:
  1. 1.
    Stop the HEAVY.AI servers.
    1
    sudo systemctl stop heavy_web_server
    2
    sudo systemctl stop heavyai_server
    Copied!
  2. 2.
    Back up your $HEAVYAI_STORAGE directory (default location is /var/lib/heavyai).
If you are upgrading from v5.x to v6.x, proceed to the Installation, Configuration, and Initialization sections on the appropriate installation page and follow the instructions:
Then, run these commands to disable existing services and uninstall the prior version: sudo systemctl disable omnisci_web_server sudo systemctl disable omnisci_server sudo yum remove omnisci
To permanently remove services, use these commands:
rm /lib/systemd/omnisci_server*.service rm /lib/systemd/omnisci_web_server*.service systemctl daemon-reload systemctl reset-failed
3. Run the Yum update command.
1
yum update heavyai
Copied!
4. When installation is complete, restart the HEAVY.AI servers.
1
sudo systemctl start heavyai_server
2
sudo systemctl start heavy_web_server
Copied!

Upgrading Using Apt

To upgrade an existing system installed with Apt to the latest version, you run the Apt update and upgrade commands. HEAVY.AI is upgraded in place without disturbing your configuration or stored data.
To upgrade HEAVY.AI using Apt:
  1. 1.
    Stop the HEAVY.AI servers.
    1
    sudo systemctl stop heavy_web_server
    2
    sudo systemctl stop heavyai_server
    Copied!
  2. 2.
    Back up your $HEAVYAI_STORAGE directory (default location is /var/lib/heavyai).
If you are upgrading from v5.x to v6.x, proceed to the Installation, Configuration, and Initialization sections on the appropriate installation page and follow the instructions:
Then, run these commands to disable existing services and uninstall the prior version: sudo systemctl disable omnisci_web_server sudo systemctl disable omnisci_server sudo apt remove omnisci
To permanently remove services, use these commands:
rm /lib/systemd/omnisci_server*.service rm /lib/systemd/omnisci_web_server*.service rm /lib/systemd/omnisci_sd_server*.service systemctl daemon-reload systemctl reset-failed
3. Run the Apt update command.
1
apt update
Copied!
4. Run the Apt upgrade command.
1
apt upgrade heavyai
Copied!
5. When installation is complete, restart the HEAVY.AI servers.
1
sudo systemctl start heavyai_server
2
sudo systemctl start heavy_web_server
Copied!

Upgrading Using a Tarball

To upgrade HEAVY.AI using a tarball, stop the servers, back up your data, expand the TAR file to replace the HEAVY.AI application, and then restart the servers.
You might prefer to create a separate directory for each version of HEAVY.AI as you upgrade. You could create an installs directory, and use a symbolic link to point to the current version. Another option is to rename the directory of the previous version before expanding the TAR file in the /opt/heavyai directory. To revert to an earlier version, you can redirect the symbolic link or move the directory of the release you want to use to /opt/heavyai.
  1. 1.
    Stop the HEAVY.AI web server and HEAVY.AI server.
    1
    sudo systemctl stop heavy_web_server
    2
    sudo systemctl stop heavyai_server
    Copied!
  2. 2.
    Back up your $OMNISCI_STORAGE file (default location is /var/lib/heavyai).
  3. 3.
    Optionally, move the previous version of the /opt/heavyai directory to another location. For example:
    1
    sudo mv /opt/heavyai /opt/heavyai_previous
    Copied!
    Otherwise, remove the /opt/heavyai directory. For example:
    1
    sudo rm -r /opt/heavyai
    Copied!
  4. 4.
    Download and expand the HEAVY.AI TAR file, per the installation instructions.
  5. 5.
    Restart the servers.
    1
    sudo systemctl start heavyai_server
    2
    sudo systemctl start heavy_web_server
    Copied!