Metadb POSTGRESQL Upgrade

This article introduces the operations required for major version upgrades of Metadb.

• Standalone/Cluster Deployment Upgrade
• Container Deployment Upgrade
• K8s Deployment Upgrade
• Windows Deployment Upgrade

Standalone/Cluster Deployment

Pre-upgrade Verification

After starting the metadb service, the following prompt appears, indicating that your metadb version is lower than the current built-in version of HENGSHI SENSE.

During the installation upgrade, the following prompt appears, indicating that your metadb version is lower than the current built-in version of HENGSHI SENSE.

Version Upgrade

Before executing, copy the new version of metadb from the HENGSHI upgrade package to the lib directory of the current deployment. For example:

cp -a hengshi-sense-[version]/lib/postgresql-17.4-linux-64 {HENGSHI_HOME}/lib/

cd {HENGSHI_HOME}
bin/hengshi-sense-bin stop hengshi ## Stop the HENGSHI service
bin/hengshi-sense-bin stop metadb ## Ensure the metadb service is stopped before performing the upgrade.
bin/hengshi-sense-bin upgrade metadb ## Perform the upgrade

The following prompt indicates that your metadb database has been successfully upgraded:

Note

If you prepare the PostgreSQL installation package yourself, you can configure the export METADB_VERSION="17.4" variable in the hengshi-sense-env.sh file to specify the upgrade version.

Version Rollback

1. If an exception occurs during the upgrade process, please perform the following steps to complete the version rollback operation.
   The program to be rolled back, postgresql-x.y.z, refers to the version of postgresql before the upgrade. In this example, it is postgresql-13.5.4-linux-64.

cd {HENGSHI_HOME}
rm -rf pg_data
mv pg_data_bak pg_data
cd /opt/hengshi/lib
rm -rf pgsql
ln -s postgresql-13.5.4 pgsql

Old Data Cleanup

After upgrading and starting HENGSHI SENSE, and confirming that the business data is functioning normally upon login, you can perform the following operations to clean up old data:

cd /opt/hengshi
rm pg_data_bak -rf

Container Deployment

Pre-upgrade Verification

Please contact the support team to confirm the current metadb version information and upgrade the metadb version information.
For example:

1. The current HENGSHI SENSE version is 5.4.6, and the metadb version is postgresql-13.5.
2. The target HENGSHI SENSE version to upgrade is 6.0.0, and the metadb version is postgresql-17.4.

Version Upgrade

1. Upgrade the metadb service main version. Use the upgrade image hengshi-sense:metadb-upgrade-X.0. Please obtain the corresponding image first, where the tag X.0 represents the main version number of HENGSHI.
2. Modify the .env file, setting HS_IMAGE_TAG=$TAG to configure $TAG as the metadb-upgrade-X.0 upgrade image tag.
3. Modify the docker-compose.yaml file, adding the following configuration under the metadb service. Note that 13.5.4 is the current metadb version number.

environment:
      PG_VERSION: 13.5.4

Note: PG_VERSION can be set to the detailed version number 13.5.4 or just 13.5. The upgrade program will match the latest available version corresponding to the main version number 13.

4. Pre-upgrade operations:

# Stop the hengshi service
docker-compose stop hengshi

# Stop the metadb service
docker stop hengshi-metadb
docker rm -f hengshi-metadb

# Start metadb-upgrade-X.0
docker-compose up -d hengshi-metadb

5. Execute the upgrade operation:

# Ensure the metadb-upgrade container status is Up before proceeding with the upgrade operation.
docker-compose run --rm metadb upgrade metadb

The above prompt indicates that your metadb database upgrade is complete.

6. Modify the .env file, setting HS_IMAGE_TAG=$TAG to configure $TAG as the X.0 upgrade image tag. For example, in this case, it should be 6.0.0.

Version Rollback

1. If an exception occurs during the upgrade process, please perform the following steps to complete the version rollback.
2. Confirm the information in the env configuration file, specifically the HSHOME address information.

cd $HSHOME # Navigate to the directory configured in HSHOME
cd hsdata
rm -rf pg_data
mv pg_data_bak pg_data

3. After completing the rollback, restore the image tag in the .env file to the previous version, which in this example is 5.4.6.

k8s Deployment

Pre-upgrade Verification

Please contact the support team to confirm the current metadb version information and upgrade the metadb version information.
For example:

1. The current HENGSHI SENSE version is 5.4.6, and the metadb version is postgresql-13.5.
2. The target HENGSHI SENSE version to upgrade is 6.0.0, and the metadb version is postgresql-17.4.

Version Upgrade

1. Upgrade the metadb service version by using the upgrade image hengshi-sense:metadb-upgrade-X.0. Please obtain the corresponding image first, where X.0 represents the major version number of HENGSHI.
2. Modify the image field in metadb.yaml from registry.hengshi.org/hengshi-sense:5.4.6 to hengshi-sense:metadb-upgrade-X.0.
3. Update the configmap.yaml configuration parameters by adding the following configuration. Note that 13.5.4 represents the current metadb version number.

PG_VERSION: 13.5.4

Note: PG_VERSION can be set to the detailed version number 13.5.4 or just the major version number 13.5. The upgrade program will match the latest available version corresponding to the major version number 13.

4. Pre-upgrade operations:

# Stop the HENGSHI service
kubectl -n hengshi scale deployment hengshi-sense --replicas=0

# Stop the metadb service
kubectl -n hengshi scale sts metadb --replicas=0

# Start the metadb-upgrade-X.0 service (ensure the image address in metadb.yaml has been updated)
kubectl -n hengshi apply metadb.yaml
kubectl -n hengshi scale sts metadb --replicas=1

5. Execute the following upgrade operation:

# Ensure the metadb-upgrade container status is "Up" before proceeding with the upgrade operation.
kubectl -n hengshi exec -it metadb-0 -- /docker-entrypoint.sh upgrade metadb single

The above message indicates that your metadb database has been successfully upgraded.

6. Modify the image field in metadb.yaml from registry.hengshi.org/hengshi-sense:metadb-upgrade-X.0 to the main service version. For example, in this case, it should be 6.0.0.

Version Rollback

1. If an exception occurs during the upgrade process, please perform the following steps to complete the version rollback:

kubectl -n hengshi exec -it metadb-0 -- /bin/bash
cd /opt/hengshi
rm -rf pg_data
mv pg_data_bak pg_data

2. After the rollback is complete, restore the image tag in the metadb.yaml file to the previous version, which in this example is 5.4.6.

Windows Deployment

Pre-upgrade Verification

Determine the current version by checking the PG_VERSION file in the *installation directory\pg_data* to confirm the current metadb version.

Please Note

Ensure that the *installation directory\lib* contains the program for the pre-upgrade metadb version.
For example, if the PG_VERSION file content is 9.6, the *lib* directory should contain the postgresql-9.6.2-windows-64 program directory.

Version Upgrade

1. Start the upgrade by entering the name of the program version to be upgraded
   

2. Click the Start Upgrade button
   

3. A Upgrade Completed message will appear, indicating the upgrade process is finished.

• Note: After the upgrade, a pg_data_bak directory will appear. This directory contains the old version database files. Once you confirm the upgraded database is correct, you can clean up this directory as needed.

Version Rollback

1. If an exception occurs during the upgrade process, please perform the following steps to complete the version rollback.
2. Delete the pg_data directory and rename the pg_data_bak directory to pg_data.
3. Edit the installation directory\bat\common.bat file and modify the pgsql variable to pgsql=postgresql-9.6.2-windows-64.