tidb-lightning: recommend matching TiDB Lightning and TiDB versions

get-started-with-tidb-lightning.md

@@ -51,10 +51,10 @@ For the steps on deploying a TiDB cluster, refer to the [Quick Start with TiDB S
 
 ## Step 3: Install TiDB Lightning
 
-Run the following command to install the latest version of TiDB Lightning:
+It is recommended to use the same version of TiDB Lightning as the target TiDB cluster. Run the following command to install TiDB Lightning, replacing `<version>` with the version of the target TiDB cluster (for example, `v{{{ .tidb-version }}}`):
 
 ```shell
-tiup install tidb-lightning
+tiup install tidb-lightning:<version>
 ```
 
 ## Step 4: Start TiDB Lightning
@@ -96,11 +96,11 @@ tiup install tidb-lightning
     pd-addr = "172.16.31.3:2379,56.78.90.12:3456"
     ```
 
-2. Run `tidb-lightning`. To avoid the program exiting due to the `SIGHUP` signal when starting the program directly in the command line using `nohup`, it is recommended to put the `nohup` command in a script. For example:
+2. Run `tidb-lightning`. To avoid the program exiting due to the `SIGHUP` signal when starting the program directly in the command line using `nohup`, it is recommended to put the `nohup` command in a script. In the following example, replace `<version>` with the TiDB Lightning version installed in [Step 3](#step-3-install-tidb-lightning):
 
     ```shell
     #!/bin/bash
-    nohup tiup tidb-lightning -config tidb-lightning.toml > nohup.out &
+    nohup tiup tidb-lightning:<version> -config tidb-lightning.toml > nohup.out &
     ```
 
 ## Step 5: Check data integrity

import-example-data.md

@@ -68,8 +68,8 @@ You can import the system data into TiDB using the following method.
     password = "very_secret"
     ```
 
-4. Run the following command.
+4. Run the following command. It is recommended to use the same version of TiDB Lightning as the target TiDB cluster. Replace `<version>` with the version of your target TiDB cluster.
 
     ```shell
-    tiup tidb-lightning -c tidb-lightning.toml
+    tiup tidb-lightning:<version> -c tidb-lightning.toml
     ```

migrate-from-sql-files-to-tidb.md

@@ -74,12 +74,14 @@ To start the import, run `tidb-lightning`. If you launch the program in the comm
 
 If you import the data from S3, you need to pass in `SecretKey` and `AccessKey` of the account as environment variables. The account has the permission to access the S3 backend storage.
 
+It is recommended to use the same version of TiDB Lightning as the target TiDB cluster. Replace `<version>` with the version of your target TiDB cluster.
+
 {{< copyable "shell-regular" >}}
 
 ```shell
 export AWS_ACCESS_KEY_ID=${access_key}
 export AWS_SECRET_ACCESS_KEY=${secret_key}
-nohup tiup tidb-lightning -config tidb-lightning.toml > nohup.out 2>&1 &
+nohup tiup tidb-lightning:<version> -config tidb-lightning.toml > nohup.out 2>&1 &
 ```
 
 TiDB Lightning also supports reading credential files from `~/.aws/credentials`.

migrate-large-mysql-to-tidb.md

@@ -144,11 +144,13 @@ The target TiKV cluster must have enough disk space to store the imported data.
 
     If you import data from S3, pass the SecretKey and AccessKey that have access to the S3 storage path as environment variables to the TiDB Lightning node. You can also read the credentials from `~/.aws/credentials`.
 
+    It is recommended to use the same version of TiDB Lightning as the target TiDB cluster. Replace `<version>` with the version of your target TiDB cluster.
+
     ```shell
     #!/bin/bash
     export AWS_ACCESS_KEY_ID=${access_key}
     export AWS_SECRET_ACCESS_KEY=${secret_key}
-    nohup tiup tidb-lightning -config tidb-lightning.toml > nohup.out 2>&1 &
+    nohup tiup tidb-lightning:<version> -config tidb-lightning.toml > nohup.out 2>&1 &
     ```
 
     Then use the script to start TiDB Lightning.

tidb-lightning/deploy-tidb-lightning.md

@@ -21,17 +21,17 @@ This document describes the hardware requirements of using TiDB Lightning to imp
 
     This command automatically adds TiUP to the `PATH` environment variable. You need to start a new terminal session or run `source ~/.bashrc` before you can use TiUP. (According to your environment, you may need to run `source ~/.profile`. For the specific command, check the output of TiUP.)
 
-2. Install TiDB Lightning using TiUP:
+2. Install TiDB Lightning using TiUP. It is recommended to use the same version of TiDB Lightning as the target TiDB cluster. Replace `<version>` with the version of the target TiDB cluster (for example, `v{{{ .tidb-version }}}`):
 
     ```shell
-    tiup install tidb-lightning
+    tiup install tidb-lightning:<version>
     ```
 
 ## Manual deployment
 
 ### Download TiDB Lightning binaries
 
-Refer to [Download TiDB Tools](/download-ecosystem-tools.md) and download TiDB Lightning binaries. TiDB Lightning is completely compatible with early versions of TiDB. It is recommended to use the latest version of TiDB Lightning.
+Refer to [Download TiDB Tools](/download-ecosystem-tools.md) and download TiDB Lightning binaries. It is recommended to use the same version of TiDB Lightning as the target TiDB cluster.
 
 Unzip the TiDB Lightning binary package to obtain the `tidb-lightning` executable file:
 

tidb-lightning/tidb-lightning-faq.md

@@ -8,9 +8,9 @@ aliases: ['/docs/dev/tidb-lightning/tidb-lightning-faq/','/docs/dev/faq/tidb-lig
 
 This document lists the frequently asked questions (FAQs) and answers about TiDB Lightning.
 
-## What is the minimum TiDB/TiKV/PD cluster version supported by TiDB Lightning?
+## Which TiDB Lightning version should I use?
 
-The version of TiDB Lightning should be the same as the cluster. If you use the Local-backend mode, the earliest available version is 4.0.0. If you use the Importer-backend mode or the TiDB-backend mode, the earliest available version is 2.0.9, but it is recommended to use the 3.0 stable version.
+It is recommended to use the same version of TiDB Lightning as the target TiDB cluster.
 
 ## Does TiDB Lightning support importing multiple schemas (databases)?
 
@@ -27,7 +27,7 @@ If only one table has an error encountered, the rest will still be processed nor
 ## How to properly restart TiDB Lightning?
 
 1. [Stop the `tidb-lightning` process](#how-to-stop-the-tidb-lightning-process).
-2. Start a new `tidb-lightning` task: execute the previous start command, such as `nohup tiup tidb-lightning -config tidb-lightning.toml`.
+2. Start a new `tidb-lightning` task by rerunning the command used to start the original task, such as `nohup tiup tidb-lightning:<version> -config tidb-lightning.toml`. Replace `<version>` with the TiDB Lightning version used by the original task.
 
 ## How to ensure the integrity of the imported data?
 

tidb-lightning/troubleshoot-tidb-lightning.md

@@ -37,7 +37,7 @@ strict-format = true
 
 **Cause 4**: TiDB Lightning is too old.
 
-Try the latest version. Maybe there is new speed improvement.
+A newer TiDB Lightning version might improve import performance. When upgrading, it is recommended to use a TiDB Lightning version that matches the target TiDB cluster version.
 
 ## The `tidb-lightning` process suddenly quits while running in background
 

tidb-troubleshooting-map.md

@@ -455,7 +455,7 @@ Check the specific cause for busy by viewing the monitor **Grafana** -> **TiKV**
         - If there is a quota on CPU (for example, limited by Kubernetes settings), TiDB Lightning might not be able to read this out. In this case, `region-concurrency` must also be manually reduced.
 
     - Every additional index introduces a new KV pair for each row. If there are N indices, the actual size to be imported would be approximately (N+1) times the size of the [Dumpling](/dumpling-overview.md) output. If the indices are negligible, you may first remove them from the schema, and add them back via `CREATE INDEX` after the import is complete.
-    - The version of TiDB Lightning is old. Try the latest version, which might improve the import speed.
+    - The version of TiDB Lightning is old. A newer TiDB Lightning version might improve import performance. When upgrading, it is recommended to use a TiDB Lightning version that matches the target TiDB cluster version.
 
 - 6.2.3 `checksum failed: checksum mismatched remote vs local`.