Completing Major Upgrades in TVE/Partner Environments

Completing Major Upgrades in TVE/Partner Environments

Prior to v30, Hyperscience was shipped with a PostgreSQL 9.5.14 database. However, Hyperscience versions v30 and later come with a PostgreSQL 12.5 database, which may cause issues when upgrading from v28 to v30. Because we use the same PostgreSQL versions in TVE installations, the same issues may occur when upgrading TVE instances.

This article describes how to perform an upgrade of TVE/partner environments running Hyperscience v28 and earlier, and it provides the tools necessary to complete the process.

When upgrading, you can keep the current local database of your environment, or you can backup its content and restore it to the database included in the latest application version.

Therefore, this article covers two scenarios:

Upgrading Hyperscience without replacing the current local database with a new one

We strongly recommend creating a backup of your database before upgrading Hyperscience.

In some cases, you might need to keep the current database and not upgrade it. Other cases might require you to offload the data to an external database.

To upgrade a TVE/partner environment to a newer version (e.g., from v28 to v30) while keeping the database container intact, do the following:

1. Download the new bundle

Currently, this bundle is the v30 bundle.

2. Extract the bundle

tar xzvf <PATH_TO_NEW_BUNDLE>.tgz

3. Go to the directory where the v30 bundle was extracted

cd <PATH_TO_NEW_BUNDLE>

4. Copy the “.env” file from the previous bundle to the directory of the new bundle

Provided that your current directory is , run the following to copy the ".env" file there:

cp <PATH_TO_PREVIOUS_BUNDLE>/.env .

5. Start the application the standard way

sudo bash run.sh init
sudo bash run.sh

The PostgreSQL container won’t be changed, and the version used will be from the previous Hyperscience bundle (i.e., 9.5.14).

Upgrading Hyperscience and upgrading the database to а new version

These instructions describe how to upgrade the local database, which we recommend doing before any major upgrade.

Hyperscience v30 comes with a new version of the local PostgreSQL image. The steps below describe how to migrate the content of the current local database to the new database.

The following instructions rely on a set of additional scripts, attached to this article:

Specific instructions about the scripts can be found by opening them and reading their headers.

1. Download the new bundle

2. Extract the bundle in a directory

tar xzvf <PATH_TO_NEW_BUNDLE>.tgz

3. Copy the “.env” file from the previous bundle directory to the new bundle directory

cp /.env <PATH_TO_NEW_BUNDLE>/.env

4. Download the three scripts from the bottom of this article, and put them in the environment's new bundle directory

The scripts need to be present in the newly extracted bundle directory because postgres_restore.sh has to be alongside the newest postgres.tar coming with the new bundle.

5. Make the scripts executable

chmod +x <PATH_TO_NEW_BUNDLE>/common.sh
chmod +x <PATH_TO_NEW_BUNDLE>/postgres_backup.sh
chmod +x <PATH_TO_NEW_BUNDLE>/postgres_restore.sh

Note that you can run Docker commands on Podman with the podman-docker package. To learn how to install the podman-docker package, see step 2 of Configuring Podman in RHEL 8.

6. Run the postgres_backup.sh script by passing it the “.env” file that was copied to the new bundle directory

cd <PATH_TO_NEW_BUNDLE>
./postgres_backup.sh .env

The last command will create a backup of your current local database in the form of a SQL file. This file can also be used to restore the database contents to a third-party database. In the example below, the backup file is named dbbackupfile-2021-06-25-07:32:09.sql.

Remember the name of this backup file. This information will be part of the script's stdout.

7. Run the postgres_restore.sh script by passing it the SQL backup file that was created in the previous step

Running this script will convert the data from a format that is readable by the current PostgreSQL database (presumably v9.5.14) to a format readable in v12.5.

cd
./postgres_restore.sh .env /mnt/hs/db_backup/dbbackupfile-2021-06-25-07:32:09.sql

8. Start the new database from the latest bundle

cd
sudo bash run.sh db

9. Start the application the standard way

sudo bash run.sh init
sudo bash run.sh