Upgrading HVR Hub on Linux

This section describes the requirements and step-by-step instructions on how to upgrade the HVR Hub System to a new version on Linux.

For upgrading the HVR Agent, see Upgrading HVR Agent.

In the case of a distributed setup, along with the HVR Hub System installation, there may be one or more HVR Agent installations on the source and target machines. Since HVR versions 6.1.0 and higher are fully compatible with each other, upgrading all installations may not be required.

Each HVR release contains new features and/or fixes for certain bugs. Each feature or fix is only effective if the correct machine is upgraded. Typically, the release notes (also available in HVR_HOME/hvr.rel directory and on the downloads page) contain information about which features and fixes have been added and which machines must be upgraded for each feature and fix to be effective. New features should not be used until all machines that are specified for that feature are upgraded; otherwise, errors may occur.

For example, if a new release fixes an Integrate bug, then that release must be installed on the HVR Agent machine(s) that performs Integrate. There will be no benefit if only the HVR Hub System is upgraded using that release.

Requirements

Following are the prerequisites for upgrading the HVR Hub System on Linux:

HVR installation file
Obtain the latest version of the HVR Hub System installation file for Linux (e.g., fivetran-6.2.0-hub_and_agent-linux_glibc2.12-x64-64bit_ga.tar.gz). You can downloaded the installation file from the Downloads tab in the Fivetran dashboard. For more information, see Downloading HVR.
Backup the HVR directories and repository database:
- Create a backup of the directories HVR_HOME (installation files) and HVR_CONFIG (HVR state).
- Create a backup of the repository database, which contains metadata definitions and settings. Use the native backup option provided by the DBMS.
- Optionally, save a hub snapshot using the UI option Save Hub Snapshot or the command hvrsnapshotsave.
Creating a backup is essential because it provides a reliable method to roll back or downgrade to the previous stable version if issues arise during an upgrade. This ensures that all data and settings can be restored to their original state if needed.
Downgrading using a hub snapshot is more complex than using a hub repository database backup. The hub snapshot contains only the hub configuration.

Upgrade Steps

Perform the following steps to upgrade the HVR Hub System:

Perform steps 1 - 3 for all active channels.

Suspend the capture job running in a channel.
Run the command hvrsuspend.
```
hvrsuspend hub channel-cap
```
Ensure that the integrate job finishes integrating all the changes. This can be verified as follows:
1. No transaction (.tx) files are left in the router directory ($HVR_CONFIG/hubs/hub/channels/channel/locs/src_loc/router/loc_tgt_loc/).
2. The integrate job has status Waiting... in the channel-integ-location.out log file located at $HVR_CONFIG/hubs/hub/logs/.
Suspend the integrate job.
Run the command hvrsuspend.
```
hvrsuspend hub channel-integ
```
Stop the HVR Hub Server.
- If the Hub Server is configured with systemd, use the command systemctl to terminate the process.
```
systemctl stop hvrhubserver
```
- If the Hub Server is NOT configured with systemd, use the command hvrhubserver to terminate the process.
```
hvrhubserver -k
```
Ensure that all HVR processes have stopped. To verify whether any HVR processes are still running, use a command like the following:
ps -ef | grep hvr
If any HVR processes are running, use the kill command to terminate the process.
Install the new version of the HVR Hub System; uncompress the installation file (e.g., fivetran-6.1.0_21-hub_and_agent-linux_glibc2.12-x64-64bit_ga_patch.tar.gz) into the HVR_HOME directory.
```
cd $HVR_HOME
```
```
tar xzf /tmp/fivetran-6.1.0_21-hub_and_agent-linux_glibc2.12-x64-64bit_ga_patch.tar.gz
```
Start the HVR Hub Server by using the command hvrhubserver.
```
hvrhubserver -d
```
Activate replication in the channel to capture changes from the beginning of the oldest current (not closed) transaction, regenerate jobs and enroll information for tables.
Perform this step for all the channels.
In some cases, other replication components should also be reactivated depending on the type of changes contained in the version being installed.
Run the hvractivate command with options -J and -oje. This will update the job scripts, scheduler jobs, job groups and extend the enrollment details for tables.
```
hvractivate -J cap -J integ -oje hub channel
```
Alternatively, run the hvractivate command with options -J and -ojE. This will update the job scripts, scheduler jobs, job groups and recreate the enroll file for all tables in the channel.
```
hvractivate -J cap -J integ -ojE hub channel
```

Downgrade Steps

Downgrade may be possible - depending on source(s), destination(s) and HVR settings - for a limited time without being forced to refresh tables or introduce data inconistencies. Always contact support for help and advice before downgrading an HVR installation.

Following are the steps for downgrading the HVR Hub System on Linux to before the upgrade:

Stop HVR hub server
Create backup
Keep a backup of HVR_CONFIG representing the state of data movement at the moement you start the downgrade.
Restore pre-upgrade backup
- the HVR_HOME (installation files) and HVR_CONFIG (HVR state) directories from before the upgrade.
- the repository database by using the DBMS's native backup utilities. If you must recover with only a hub snapshot then you must import the snapshot into a new empty repository database.
Adjust channel settings as needed
The backup restored replication state to before the upgrade. If changes were replicated following the upgrade then targets are ahead of the restored state. With access to log backups and/or archivelog files you may want to replay the changes with Resilient mode enabled on the Integrate action, followed by hvractivate. Alternatively, you may be able to reuse state from the upgraded system, or use hvractivate to reset the capture time based on state tables in the destination.
Start hub server

Resuming replication based on the recovered state from before the upgrade may no longer possible, or a suitable starting point for capture cannot be determined. In such cases hvrrefresh must be used to resync data.