Project: StarRocks (App Definition and Development / Database)
File: downgrade.md

displayed_sidebar: "English" This topic describes how to downgrade your StarRocks cluster. If an exception occurs after you upgrade a StarRocks cluster, you can downgrade it to the earlier version to quickly recover the cluster. Review the information in this section before downgrading. Perform any recommended actions. For patch version downgrade You can downgrade your StarRocks cluster across patch versions, for example, from v2.2.11 directly to v2.2.6. For minor version downgrade For compatibility and safety reasons, we strongly recommend you downgrade your StarRocks cluster consecutively from one minor version to another. For example, to downgrade a StarRocks v2.5 cluster to v2.2, you need to downgrade it in the following order: v2.5.x --> v2.4.x --> v2.3.x --> v2.2.x. For major version downgrade You can only downgrade your StarRocks v3.0 cluster to v2.5.3 and later versions. StarRocks upgrades the BDB library in v3.0. However, BDBJE cannot be rolled back. You must use BDB library of v3.0 after a downgrade. The new RBAC privilege system is used by default after you upgrade to v3.0. You can only use the RBAC privilege system after a downgrade. StarRocks' downgrade procedure is the reverse order of the . Therefore, you need to downgrade FEs first and then BEs and CNs. Downgrading them in the wrong order may lead to incompatibility between FEs and BEs/CNs, and thereby cause the service to crash. For FE nodes, you must first downgrade all Follower FE nodes before downgrading the Leader FE node. During preparation, you must perform the compatibility configuration if you are up for a minor or major version downgrade. You also need to perform the downgrade availability test on one of the FEs or BEs before downgrading all nodes in the cluster. If you want to downgrade your StarRocks cluster to an earlier minor or major version, you must perform the compatibility configuration. In addition to the universal compatibility configuration, detailed configurations vary depending on the version of the StarRocks cluster you downgrade from. Universal compatibility configuration Before downgrading your StarRocks cluster, you must disable tablet clone. ```SQL ADMIN SET FRONTEND CONFIG ("tabletschedmaxschedulingtablets" = "0"); ADMIN SET FRONTEND CONFIG ("tabletschedmaxbalancingtablets" = "0"); ADMIN SET FRONTEND CONFIG ("disable_balance"="true"); ADMIN SET FRONTEND CONFIG ("disablecolocatebalance"="true"); ``` After the downgrade, you can enable tablet clone again if the status of all BE nodes becomes `Alive`. ```SQL ADMIN SET FRONTEND CONFIG ("tabletschedmaxschedulingtablets" = "10000"); ADMIN SET FRONTEND CONFIG ("tabletschedmaxbalancingtablets" = "500"); ADMIN SET FRONTEND CONFIG ("disable_balance"="false"); ADMIN SET FRONTEND CONFIG ("disablecolocatebalance"="false"); ``` If you downgrade from v2.2 and later versions Set the FE configuration item `ignoreunknownlog_id` to `true`. Because it is a static parameter, you must modify it in the FE configuration file fe.conf and restart the node to allow the modification to take effect. After the downgrade and the first checkpoint are completed, you can reset it to `false` and restart the node. If you have enabled FQDN access If you have enabled FQDN access (supported from v2.4 onwards) and need to downgrade to versions earlier than

you must switch to IP address access before downgrading. See for detailed instructions. After the compatibility configuration and the availability test, you can downgrade the FE nodes. You must first downgrade the Follower FE nodes and then the Leader FE node. Create a metadata snapshot. a. Run to create a meatedata snapshot. b. You can check whether the image file has been synchronized by viewing the log file fe.log of the Leader FE. A record of log like "push image.* from subdir [] to other nodes. totally xx nodes, push successful xx nodes" suggests that the image file has been successfully synchronized. > CAUTION > > The ALTER SYSTEM CREATE IMAGE statement is supported in v2.5.3 and later. In earlier versions, you need to create a meatadata snapshot by restarting the Leader FE. Navigate to the working directory of the FE node and stop the node. ```Bash cd <fe_dir>/fe ./bin/stop_fe.sh ``` Replace the original deployment files under bin, lib, and spark-dpp with the ones of the earlier version. ```Bash mv lib lib.bak mv bin bin.bak mv spark-dpp spark-dpp.bak cp -r /tmp/StarRocks-x.x.x/fe/lib . cp -r /tmp/StarRocks-x.x.x/fe/bin . cp -r /tmp/StarRocks-x.x.x/fe/spark-dpp . ``` > CAUTION > > If you are downgrading StarRocks v3.0 to v2.5, you must follow these steps after you replace the deployment files: > > 1. Copy the file fe/lib/starrocks-bdb-je-18.3.13.jar of the v3.0 deployment to the directory fe/lib of the v2.5 deployment. > 2. Delete the file fe/lib/je-7.\*.jar. Start the FE node. ```Bash sh bin/start_fe.sh --daemon ``` Check if the FE node is started successfully. ```Bash ps aux | grep StarRocksFE ``` Repeat the above Step 2 to Step 5 to downgrade other Follower FE nodes, and finally the Leader FE node. > CAUTION > > Suppose you have downgraded your cluster after a failed upgrade and you want to upgrade the cluster again, for example, 2.5->3.0->2.5->3.0. To prevent metadata upgrade failure for some Follower FEs, repeat Step 1 to trigger a new snapshot before upgrading. Having downgraded the FE nodes, you can then downgrade the BE nodes in the cluster. Navigate to the working directory of the BE node and stop the node. ```Bash cd <be_dir>/be ./bin/stop_be.sh ``` Replace the original deployment files under bin and lib with the ones of the earlier version. ```Bash mv lib lib.bak mv bin bin.bak cp -r /tmp/StarRocks-x.x.x/be/lib . cp -r /tmp/StarRocks-x.x.x/be/bin . ``` Start the BE node. ```Bash sh bin/start_be.sh --daemon ``` Check if the BE node is started successfully. ```Bash ps aux | grep starrocks_be ``` Repeat the above procedures to downgrade other BE nodes. Navigate to the working directory of the CN node and stop the node gracefully. ```Bash cd <cn_dir>/be ./bin/stop_cn.sh --graceful ``` Replace the original deployment files under bin and lib with the ones of the earlier version. ```Bash mv lib lib.bak mv bin bin.bak cp -r /tmp/StarRocks-x.x.x/be/lib . cp -r /tmp/StarRocks-x.x.x/be/bin . ``` Start the CN node. ```Bash sh bin/start_cn.sh --daemon ``` Check if the CN node is started successfully. ```Bash ps aux | grep starrocks_be ``` Repeat the above procedures to downgrade other CN nodes.