This page describes the upgrade flow from TigerGraph 2.6.x version to TigerGraph 3.x version. You may use this process to upgrade to any 3.x version (for example 3.0.5 and 3.1.1 in addition 3.0.0). The 2.x version MUST be 2.6.x

Note: Please do a backup before performing the upgrade steps. 

1. Before upgrading, please perform the following steps on TigerGraph 2.6.x version.

  • Force GPE rebuild with the rebuildnow API (specify any graph name):
    curl -X GET "localhost:9000/rebuildnow/<GRAPH_NAME>"

    If authentication is turned on, use:

    curl -H "Authorization: Bearer <ACCESS_TOKEN>" -X GET "localhost:9000/rebuildnow/<GRAPH_NAME>"

  • Verify that the GPE has caught up by checking all gpe log are not printing "PullDelta" anymore.

    tail -f /<PATH>/<TO>/<GPE LOG>/log.INFO | grep PullDelta

  • Check the least offset in all segments and make sure it's larger than the beginning offset of Kafka:

    # lowest segment offset:
    grep -rin PostQueuePos ~/tigergraph/gstore/0/part/[0-9]*/segmentconfig.yaml | awk -F ':' '{print $4}' | sort -nr | tail -1
    # Kafka beginning offset
    ls -ltr /home/tigergraph/tigergraph/kafka/log_dir/deltaQ_GPE* | awk -F ' ' '{print $9}' | awk -F '.' '{print $1}' | sort | uniq

  • Ensure that the GPE could be restarted successfully. *Please do not post any data* 

    gadmin restart gpe -y

  • Commit staging configs

    gadmin config-apply

  • Stop all services on 2.x

    gadmin stop all admin ts3 -y
  • Open up the following new ports for 3.x: 14240, 9166, 9177, 9188


2. Installing the 3.x with the same cluster configs and HA option as installed 2.6.x version under the same user

  • For HA, if you enable the HA in 2.6.x version, you should specify the ReplicationFactor to be 2. Otherwise, leave it as 1.

  • If your old 2.6.x system is installed in the cluster node set [m1, m2, m3, m4], you can only install 3.x in the same node set [m1, m2, m3, m4]. Moreover,  please make sure that the IP of m1 is the same as in 2.x version

  • Please provide a valid license key.

  • After installing, login as tigergraph user. The "gadmin version" command should show your chosen 3.x version. If not, please check your 3.x installation again. Sometimes, the installation is successful but you need to logout and login again to make sure the correct version is showing up.

3. Migration (steps should be performed under tigergraph user)

  • Download the migration_tool.tar.gz below.

  • Make sure the gsql.cfg file of 2.6.x version is at ~/.gsql/gsql.cfg

  • Run the migration tool.

    tar -zxvf migration_tool.tar.gz
    cd  migration_tool
    ./ ~/.gsql/gsql.cfg

  • If any error occurs, please check the error message, as well as debug.log under migration tool folder

  • If you don’t activate a valid license when installing 3.x, you might fail in the end with these two commands.

    gsql recompile loading job
    gsql install query -force all
  • Please make sure to run these two commands once after you activate a valid license.
  • Note: if after the upgrade you cannot see the query from the UI. You need to drop all the queries and reinstall them again fresh. Go to each graph and use "gsql show query *" to show all the queries before dropping them.

4. Post-migration verification 

  • Now the migration should be done. You can perform a few verification steps such as running an existing query to verify that everything looks good.

5. Enable GSQL/GUI HA

Update 5/11/21: Migration tool now migrates GUI metadata if upgrading to 3.2.0 or greater.

Update 6/11/21: Update to internal API used in the tool for 3.2.