Upgrading an Existing Installation

Before you begin

Check release notes for changes in functionality

Always check the TigerGraph DB Release Notes for all the versions between your current version and your target version, for deprecated features, known issues, new reserved words, or other behavioral changes. You may need to make migration changes to your TigerGraph application either before or after the upgrade. For example, change the name of schema elements and refactor queries if a new reserved word was introduced. If you have any questions or uncertainty, please contact TigerGraph Support.

User-defined function (UDF) compatibility

TigerGraph version 3.9 introduced changes in the way user-defined functions are accepted by the system.

  • Some UDFs may no longer be accepted due to increased security screening.

  • UDFs may no longer be called to_string(). This is now a built-in GSQL function.

  • UDF names may no longer use the tg_ prefix.

If any UDFs do not satisfy these restrictions, then they will not be installed. GSQL will return these errors:

Reserved tg_ prefix error
The following function name(s) contain errors:
  [reserved 'tg_']: tg_myFunction

Please rename the corresponding functions in: ExprFunctions.hpp
Reserved to_string() function name
Following GSQL built-in function name(s): [to_string] can not be used again for user defined function name(s)!
GSQL built-in functions are case-insensitive. Please rename corresponding user defined functions in ExprFunctions.hpp.

Any user-defined function previously used in an older TigerGraph version that does not comply with these requirements must be renamed or removed in ExprFunctions.hpp.

Make a Backup

As a precaution, it is always a good idea to make a full backup before performing a major system change like an upgrade. System upgrade does not support version rollback at this time.

Prepare a pre-3.2 database

  1. First perform a backup using GBAR (Graph Backup and Restore) on your existing installation.

  2. Restore your installation with GBAR to rebuild it. This step is necessary because TigerGraph 3.2 made major changes to the Graph Storage Engine and a restore is needed to remove certain files that would make the upgrade operation fail.

  3. Ensure that the restore is completely finished and there are no pending graph modifications (schema change, insert, update, or delete) before starting the upgrade. You can do this by calling the /rebuildnow endpoint and waiting until there are no more PullDelta messages being printed in the logs.

Ensure that the database is inactive

Ensure that the database will be inactive throughout the upgrade process.

  1. Stop any new database requests.

  2. Ensure that all previous operations such as queries, loading jobs, schema changes, and data updates and deletions are completely finished. Check the appropriate logs. Call the /rebuildnow endpoint to force the data store to consume all pending updates and then wait until there are no more PullDelta messages being printed in the logs.

Upgrading a CRR system

To upgrade the TigerGraph software on a CRR system, follow this sequence of steps.

  1. Disable CRR on your DR cluster.

    $ gadmin config set System.CrossRegionReplication.Enabled false
$ gadmin config apply -y
$ gadmin restart all -y

  2. Upgrade both the primary cluster and DR cluster, according to the instructions on this page.

  3. Enable CRR on the DR cluster.

Rolling Upgrade (Preview)

A rolling upgrade allows you to upgrade your TigerGraph installation with minimal downtime by upgrading nodes in batches, ensuring that at least one full replica of the cluster is online throughout the process.

Rolling Upgrade is only available for HA clusters (High Availability) and when making a maintenance update (e.g., 4.2.0 to 4.2.1, 4.3.1 to 4.3.3). Upgrading from 4.2.0 to 4.3.0 or any other major version is not supported.

Blocked Operations During Rolling Upgrade

To ensure a smooth upgrade, the following operations are blocked during a rolling upgrade:

  • Install query

  • Run schema change

  • Drop all

  • Run gsql --reset

  • Create graph

  • Clear graph store

  • Export or import graph

  • Install function

Operations to Avoid

Avoid these operations during a rolling upgrade, as they can disrupt the process or may not work as expected:

  • Backup and restore

  • Cluster reszie (expansion, shrink, or removal)

  • Configuration changes using gadmin config set or gadmin config apply

  • Starting, stopping, or restarting services using gadmin start, gadmin stop, or gadmin restart

  • Setting up Cross-Region Replication (CRR). Note: Existing CRR configurations will continue to function.

  • Cluster initialization using gadmin init

  • Resetting services with gadmin reset

While the rolling upgrade is in progress, loading jobs and running queries will continue to function; however, queries requiring all replicas to be online may fail, in which case you can retry them in a round-robin manner. Please note that occasional slowdowns in Queries Per Second (QPS) may occur during the upgrade. Additionally, services like Zookeeper (ZK), Kafka, and ETCD will not be upgraded during this process.

Rolling Upgrade Process

Before starting the upgrade, always review the general prerequisites for all versions between your current and target version.

Download and Extract Latest Version

  • Download the latest maintenance release of TigerGraph.

  • Extract the tar file on your system.

Run Installation Script with Rolling Upgrade Flag

To perform a rolling upgrade, run the installation script with the upgrade flag (-U) and the rolling upgrade option (-r).

$ ./install.sh -Ur

Switching to New Version

After the binaries and configuration files are installed, the following prompt message will appear on the console:

"Do you want to switch platform to the new version now (it can be delayed to a later time): y/N"

n/N option

Selecting n/N will guide the user through the manual steps to switch to version 4.2.1, assuming the user is upgrading from 4.2.0.

To switch platform to new version, please run 'gadmin upgrade 4.2.1'

y/Y Option

If users selects `y/Y' the installer will automatically switch TigerGraph to the latest maintenance version. If any errors occur, the upgrade process will terminate immediately. Follow the instructions in the prompts to manually continue the upgrade or revert to the original version.

Option -n

If the user wants to skip manual input during the upgrade, they can use the -n flag, which automatically switches to the new version without requiring any interaction.

$ ./install.sh -Ur -n
Example:
./install.sh -Ur -n

   _______                 ______                 __
  /_  __(_)___ ____  _____/ ____/________ _____  / /_
   / / / / __ `/ _ \/ ___/ / __/ ___/ __ `/ __ \/ __ \
  / / / / /_/ /  __/ /  / /_/ / /  / /_/ / /_/ / / / /
 /_/ /_/\__, /\___/_/   \____/_/   \__,_/ .___/_/ /_/
       /____/                          /_/


Welcome to the TigerGraph platform installer!

[PROGRESS]: 08:10:44 Upgrade TigerGraph platform from existing one ...
[NOTE    ]: Obtained version of exist platform: 4.2.0 [OK]
[NOTE    ]: Obtained version of new platform: 4.2.1 [OK]
...
[PROGRESS]: 08:13:37 Performing pre-upgrade check between version 4.2.0 and 4.2.1 successfully...
[NOTE    ]: Switching to new version 4.2.1 by rolling upgrade...
[NOTE    ]: This may take a significant amount of time, and you can reconnect by running 'gadmin upgrade --resume' if the connection is lost.
[   Info] performing pre-check for rolling upgrade...
[   Info] initial version check passed, target version: 4.2.1
[   Info] [Wed Mar 19 08:13:37 UTC 2025] [Rolling Upgrade]: rolling upgrade begins...
.
.
[   Info] [Wed Mar 19 08:20:32 UTC 2025] [Rolling Upgrade]: unblocking GSQL operations ...
[   Info] [Wed Mar 19 08:20:32 UTC 2025] [Rolling Upgrade]: GSQL operations are unblocked
[   Info] Stopping CTRL
[   Info] Starting CTRL
[   Info] Rolling upgrade completes!
[PROGRESS]: 08:20:33 Switching to new version 4.2.1 successfully...

During a rolling upgrade, the TigerGraph service may experience brief disruptions but should automatically resume.

Handling an Incomplete Rolling Upgrade

Resuming a Rolling Upgrade

If your connection to the upgrade process is lost unexpectedly, you can reconnect and continue the upgrade by running:

gadmin upgrade --resume

Rolling Upgrade Failed with an Error

If the rolling upgrade fails with an error, the error message will contain instructions on how to proceed. Follow those instructions to complete the upgrade or revert to the previous version. Here is an example of the instructions you may see in the error message:

# You may try to manually finish the upgrade following below instructions in that order (NOTE: these instructions may cause downtime):
* gadmin restart GUI#1 ADMIN#1 NGINX#1 EXE_1 IFM#1 KAFKASTRM-LL_1 RESTPP#1 DICT#1 KAFKACONN#1 GSE_1#1 GPE_1#1 CTRL#1 DICT#2 KAFKACONN#2 RESTPP#2 IFM#2 GUI#2 EXE_2 ADMIN#2 KAFKASTRM-LL_2 CTRL#2 GSE_1#2 NGINX#2 GPE_1#2 NGINX#3 GPE_1#3 GUI#3 KAFKASTRM-LL_3 DICT#3 KAFKACONN#3 RESTPP#3 EXE_3 ADMIN#3 CTRL#3 GSE_1#3 IFM#3 --no-dep -y
* Open another shell, run 'watch -n 2 gadmin status -v', and wait for all services to go online
* The upgrade is complete when all services are online

To revert, run these commands(NOTE: reverting will cause downtime):
# Replace <old version> with your previous TigerGraph version (for example, 4.2.0).
1. gadmin config set System.AppRoot /home/tigergraph/tigergraph/app/4.2.0
2. gadmin config apply -y
3. gadmin restart all -y

For further assistance, please contact support@tigergraph.com

Silent Failure During Rolling Upgrade

If the CTRL service restarts unexpectedly during the rolling upgrade, the upgrade process will fail silently. You will lose both the upgrade status and your connection, as if the upgrade was never started.

If you try to resume the upgrade using gadmin upgrade --resume, you will see this message:

$ gadmin upgrade --resume
[   Info] no rolling upgrade is underway

When this happens, you can either manually switch to the new version or revert to the old version.

Both options will cause downtime.

Switch to the New Version

# Replace <new version> with the actual version number, for example, 4.2.1
gadmin config set System.AppRoot /home/tigergraph/tigergraph/app/<new version>
gadmin config apply -y
gadmin restart all -y

Revert to the Previous Version

# Replace <old version> with the actual version number, for example, 4.2.0
gadmin config set System.AppRoot /home/tigergraph/tigergraph/app/<old version>
gadmin config apply -y
gadmin restart all -y

Upgrading from v3.x

When switching to a new version of TigerGraph it will stop the current services which will make the cluster temporarily unavailable.

Any 3.x version of TigerGraph can be upgraded to another v3.x version by running the installation script with the upgrade(-U) flag.

  1. Download the latest version of TigerGraph to your system.

  2. Extract the tar file.

  3. Run the installation script under the Linux user created during installation with the upgrade flag (-U) that was extracted from the tar file:

$ ./install.sh -U

Please upgrade from the most recent maintenance version in any minor release. If you are upgrading from a version that does not have the most recent patches applied to its minor version, upgrade to the most recent patches first before upgrading to another minor or major version. For example, if you are upgrading from 3.5.0 to 3.10.x, upgrade to 3.5.3 first using the installation script and then upgrade to 3.10.x.

Additionally, versions upgrading from 3.0 or 3.1 must first go through 3.2.4. For example, if you are running version 3.1.3, you must first upgrade to 3.1.6, then 3.2.4, then to 3.10.x.

Once binaries and config files are installed on local machine and also distributed to all the other machines, a message will be prompted to user:

“Do you want to switch platform to the new version now(it can be delayed to a later time): y/N”.

n/N option

If users selects n/N, now it is listing a list of scripts taking the same parameters as gadmin/gsql commands.

Ex.
[NOTE    ]: To switch platform to new version, please follow the instructions:
1.  pre_upgrade_check_infra.sh 3.6.5 3.10.0
2.  pre_upgrade_check_engine.sh 3.6.5 3.10.0
3.  pre_upgrade_check_gsql.sh 3.6.5 3.10.0
4.  pre_upgrade_check_gus.sh 3.6.5 3.10.0
5.  gadmin config set System.AppRoot /home/graphsql/tigergraph/app/3.10.0
6.  gadmin config apply -y
7.  switch_version_infra.sh 3.6.5 3.10.0
8.  switch_version_engine.sh 3.6.5 3.10.0
9.  switch_version_gsql.sh 3.6.5 3.10.0
10. switch_version_gus.sh 3.6.5 3.10.0
11. post_upgrade_check_infra.sh 3.6.5 3.10.0
12. post_upgrade_check_engine.sh 3.6.5 3.10.0
13. post_upgrade_check_gsql.sh 3.6.5 3.10.0
14. post_upgrade_check_gus.sh 3.6.5 3.10.0

These scripts are located in “/home/<user>/tigergraph/app/<version>/upgrade_script folder.

y/Y Option

If users selects y/Y the installer will automatically switch TigerGraph to the latest version.

A new message will prompt to user, saying TigerGraph has been upgraded.

If there’s any error, the upgrade process will be terminated immediately. Following the instructions in the prompts from the console, the user can tell the progress of the upgrade and manually re-run the failed and the leftover steps to complete the upgrading process.

Option -n

Users can use option -n to avoid input y/n to switch to the new version. When it is given, the upgrade flow will switch to the new version automatically without input from the user.

$ ./install.sh -U -n
Example:
./install.sh -U -n

   _______                 ______                 __
  /_  __(_)___ ____  _____/ ____/________ _____  / /_
   / / / / __ `/ _ \/ ___/ / __/ ___/ __ `/ __ \/ __ \
  / / / / /_/ /  __/ /  / /_/ / /  / /_/ / /_/ / / / /
 /_/ /_/\__, /\___/_/   \____/_/   \__,_/ .___/_/ /_/
       /____/                          /_/


Welcome to the TigerGraph platform installer!

[PROGRESS]: 20:02:38 Upgrade TigerGraph platform from existing one ...
[NOTE    ]: Obtained version of exist platform: 3.10.0 [OK]

Upgrading from v2.x

Please contact TigerGraph Support to coordinate upgrading to TigerGraph version 4.2 if you are currently using a 2.x version of TigerGraph. Even though all the steps are documented, it is strongly recommended that you review the process with the TigerGraph Support team.

Upgrading the Developer Edition or migrating to another edition are not supported.

For detailed upgrade procedures, see our support article on the 2.6.x to 3.x upgrade flow

Upgrading Cloud Marketplace Images

Upgrading from 3.x

  1. Back up your TigerGraph instance using GBAR.

  2. Start a new instance from the latest cloud marketplace listing.

  3. Use the backup files you generated earlier to restore the new instance.

Upgrading from 2.x

If you want to upgrade your Cloud Marketplace image from v2.x on any cloud platform, please open a support ticket. for instructions and assistance.

Known Issues and Workarounds

Several things may have changed between your current release and 3.9.x and these steps should help to upgrade the UDF file before starting the upgrade process or prepare users to address anything that may come up as a result of the upgrade.

to_string() is Now a Built-in Function:

In previous releases, to_string() was included in the default ExprFunctions file and is a common utility function added to the ExprFunctions file.

What to do:

Users need to rename or remove UDFs that are called to_string(). Now, that it is added as a built-in function users are no longer needing to include it in the ExprFunctions file.

For more reference on how to prepare for an upgrade please refer back to the section: Before You Begin.

tg_ is Now a Reserved Keyword

TigerGraph uses the tg_ prefix to denote functions provided by TigerGraph.

What to do:

Users can either rename, remove, or comment out any functions in their ExprFunctions file that contain this prefix. Additionally, users should avoid prefixing future functions with this reserved prefix. This is to avoid naming collisions with queries.

For more reference on how to prepare for an upgrade please refer back to the section: Before You Begin.

UDF File Policy

There is some UDF enforcement taking place. The UDF files are scanned to make sure they comply with the file policy. This is to ensure there are none of the following:

  1. Macros with a replacement.

    Example:
    #define TABLE_SIZE 100
    Notice the macro without replacement is allowed
    #define EXPRFUNCTIONS_HPP_

  2. Headers and Includes from potentially vulnerable C++ features

    If the header file is not included in our default allowlist, users can, at their own discretion, add C++ headers to an allowlist. Users are free to edit the allowlist via gadmin config set GSQL.UDF.Policy.HeaderAllowlist.

    Additionally, users can also disable a file policy after an upgrade with this command:

    gadmin config set GSQL.UDF.Policy.Enable false

    This is so the restrictions will not take effect.

What to do:

It is recommended that users consult with the entire policy and adjust the UDF files to comply with the file policy.

For more reference please see: UDF File Scanning.

File Output Policy

GSQL restricts where a query can produce output to files through a file output policy. Sometimes users can encounter a issue with this policy after an upgrade.

What to do:

Before (recommended) or after an upgrade users should change or use different constant paths for queries and loading jobs that do not violate policy.

For more on file policy see File Output Policy and/or File Input Policy.

Other issues

For any other issues encountered please contact support@tigergraph.com.