📘

Minimum Tamr Version

If upgrading from Tamr version 0.37.0 or earlier, please first upgrade to 0.37.0 (see upgrade procedure at Version 0.37.0 Upgrading).

🚧

Major ElasticSearch Upgrade

v2019.002 has a major version upgrade for ElasticSearch. As such, Tamr must reindex all projects and datasets after upgrading. Expect upgrading from any version pre-v2019.002 to v2019.002 or greater to take longer than a normal upgrade. Additionally, best practices are to first upgrade to v2019.001, take a backup, and then proceed to upgrade to the desired version.

v.2019.019 included an upgrade for ElasticSearch from v.6.4.2 to v.6.8.2. If you upgrade from earlier versions, expect the upgrade process to v.2019.019 to take longer due to this change.

Upgrading Tamr

Checklist before proceeding

• Current Tamr version is at least 0.37.0.
• Current user is the functional user, e.g. tamr.
• The Tamr software bundle unify.zip of the target version.

Upgrade options

• --backup [multi-node, single-node] [optional] Set the system to backup before upgrading.
• --healthcheckTimeout <healthcheckTimeout> [optional] Set how long to wait for the healthchecks to time out.
• --help [optional] Print out the help message
• --installDir <installDir> [single-node] The current installation on disk.
• --nobackup [multi-node, single-node] [optional] Set the system not to backup before upgrading.
• --options <options> [multi-node] [optional] The options used to build the marathon application configuration.
• --rerun [multi-node, single-node] [optional] Re-run the upgrade against the current version of the product. Useful for when an error occurs during upgrade and the user wants to re-attempt the upgrade.
• --upgradeDir <upgradeDir> [single-node] [optional] The directory where the upgrade version of Tamr exists, if the upgrade zip file has been extracted.
• --zipFile <zipFile> [single-node] [optional] The path to the target upgrade zip file.
• --tempDir <tempDir> [single-node] [optional] A path to unzip the zip file to. If not specified, will default to system temp directory.
• --zookeeper <full-zk-conf-node-url> [single-node] The ZooKeeper URL of the Tamr configuration node, e.g. zk://localhost:21281/tamr/unify001/conf

Multi-Node Upgrade Options

The following options are also available when performing upgrade, but should not be used during a single-node upgrade.

• --applicationName <applicationName> [multi-node] The name of the marathon application to upgrade.
• --licenseKey <licenseKey> [multi-node] [optional] New license key for the application
• --marathonUrl <marathonUrl> [multi-node] The URL to the marathon instance being upgraded.
• --upgradeTag <upgradeTag> [multi-node] The tag to the target upgrade version.

Upgrade Procedure

1. Backup Tamr by following the backup procedure of the source version. For example, for information about upgrading from Tamr version 0.41.0, see Version 0.41.0 Backup.

2. If you are using any Auxiliary Services, disable them before proceeding with the Tamr upgrade. See Disabling an Auxiliary Service.

3. If upgrading from version 0.37.0 or later, run the admin utility unify-admin.sh with the command upgrade and the arguments --zipFile, --installDir and --zookeeper. Optionally include --tempDir. For example:

cd <tamr-home-directory>/tamr/utils
./unify-admin.sh --upgrade --zipFile <full-path-to-target-version-unify-zip>  --installDir <full-path-to-tamr-unify-home>  --zookeeper zk://localhost:21281/tamr/unify001/conf --tempDir <full-path-to-target-unzip-directory>

else if upgrading from version 0.36.0, run the admin utility unify-admin.sh with the command upgrade and the argument of the full path to the Tamr software bundle unify.zip of the target version.

cd <tamr-home-directory>/tamr/utils
./unify-admin.sh --upgrade <full-path-to-target-version-unify-zip>

4. If you are using any Auxiliary Services, install the version that matched your upgraded Tamr instance. See Installing an Auxiliary Service.

5. All users must clear their web browser cache before logging into Tamr.

Post-Upgrade Steps

After upgrading, you may need to rerun some materialization jobs.

1. Due to changes in the schema mapping model, if you are upgrading from v0.37.0 or earlier, you must rerun the Learn from mappings job before using the Generate mapping suggestions job on the Schema Mapping page.
2. If upgrading from v0.37.0 or earlier, mapped source attributes may show up when the unmapped filter is enabled. If this occurs, run POST /schema-mapping/unified-attributes/{UnifiedDatasetName}/calculate-attr-mappings to update the metadata.
3. There is an issue for mastering projects when upgrading from v0.39.0 or earlier to v0.49.0 or later (where a metadata change was introduced). Pair generation jobs may fail with the error java.lang.IllegalStateException: Expected schema. The workaround is to label a pair then resubmit the job.

📘

Clusters Stats Schema Change

If upgrading from Tamr version 0.46.0 or later, and the derived dataset <unified-dataset-name>_published_clusters_stats already exists, you must execute Update Results before publishing clusters.