2.6.x to 3.x upgrade flow


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). You MUST be running the latest 2.x version (which is 2.6.6) before upgrading to 3.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

a.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>"
b.Verify that the GPE has caught up by checking all GPE logs are not printing "PullDelta" anymore.
tail -f /<PATH>/<TO>/<GPE LOG>/log.INFO | grep PullDelta
c.Check the lowest 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
d.Ensure that the GPE could be restarted successfully. *Please do not post any data*
gadmin restart gpe -y
e.Commit staging configs
gadmin config-apply
f.If upgrading to 3.2.x, a backup and restore must be run
gbar backup -t YOUR_TAG
gbar list
gbar restore TAG_FROM_LIST
g.Stop all services on 2.x
gadmin stop all admin ts3 -y
h.Open up the following new ports for 3.x: 14240, 9166, 9177, 9188
   ●This include local OS firewall, network firewall, etc

2.Installing 3.x with the same cluster configs and HA options as previously installed 2.6.x version under the same user a.First, modify install_conf.json

i.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
ii.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
iii.Please provide a valid license key
b.Next, start the installation by running:
./install.sh -n
c.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.
d.Note: after the upgrade finishes `gadmin status` will show GPE and GSE in warmup. This is expected

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

a.Download the attached migration_tool.zip
b.Make sure the gsql.cfg file of 2.6.x version is at~/.gsql/gsql.cfg
c.Run the migration tool
unzip migration_tool.zip
cd  migration_tool
./migration_tool.sh ~/.gsql/gsql.cfg
d.If any error occurs, please check the error message, as well as debug.log under migration tool folder
e.If you don’t activate a valid license when installing 3.x, you might fail in the end with these two commands.
f.Please make sure to run these three commands once after you activate a valid license.
gsql recompile loading job
gsql --precompile       //use -u <username> -p <password> if they changed default
gsql install query -force all
g.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

a.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.
b.Note: if after upgrade you encounter issues logging in (i.e. java.lang.IllegalArgumentException: Input byte array has incorrect ending byte at 28)...then you will need to re-grant roles for users/service accounts.

5.Enable GSQL/GUI HA

a.If you would like to enable GSQL and GUI high availability after upgrading, please follow the instructions here:

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

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