From e8f0a021adefcf76fea9358b6ac89b5a3f35abca Mon Sep 17 00:00:00 2001 From: YangKeao Date: Sun, 20 Sep 2026 17:28:52 +0800 Subject: [PATCH 1/3] docs: recommend matching TiDB Lightning and TiDB versions --- get-started-with-tidb-lightning.md | 8 ++++---- tidb-lightning/deploy-tidb-lightning.md | 6 +++--- tidb-lightning/tidb-lightning-faq.md | 4 ++-- tidb-lightning/troubleshoot-tidb-lightning.md | 2 +- tidb-troubleshooting-map.md | 2 +- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/get-started-with-tidb-lightning.md b/get-started-with-tidb-lightning.md index a8519ae62e220..0ab97e5f4a623 100644 --- a/get-started-with-tidb-lightning.md +++ b/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 `` with the version of the target TiDB cluster (for example, `v8.5.0`): ```shell -tiup install tidb-lightning +tiup install tidb-lightning: ``` ## 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 `` with the version installed in Step 3: ```shell #!/bin/bash - nohup tiup tidb-lightning -config tidb-lightning.toml > nohup.out & + nohup tiup tidb-lightning: -config tidb-lightning.toml > nohup.out & ``` ## Step 5: Check data integrity diff --git a/tidb-lightning/deploy-tidb-lightning.md b/tidb-lightning/deploy-tidb-lightning.md index b2c57bbc0d3c8..40d8e415a0f98 100644 --- a/tidb-lightning/deploy-tidb-lightning.md +++ b/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 `` with the version of the target TiDB cluster (for example, `v8.5.0`): ```shell - tiup install tidb-lightning + tiup install tidb-lightning: ``` ## 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: diff --git a/tidb-lightning/tidb-lightning-faq.md b/tidb-lightning/tidb-lightning-faq.md index ff0f72bb275af..f8cd9cae315f5 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -10,7 +10,7 @@ This document lists the frequently asked questions (FAQs) and answers about TiDB ## What is the minimum TiDB/TiKV/PD cluster version supported by TiDB Lightning? -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. 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. ## 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: execute the previous start command, such as `nohup tiup tidb-lightning: -config tidb-lightning.toml`. Replace `` with the TiDB Lightning version used by the original task. ## How to ensure the integrity of the imported data? diff --git a/tidb-lightning/troubleshoot-tidb-lightning.md b/tidb-lightning/troubleshoot-tidb-lightning.md index 90bd6fe1075a7..6adb231ce0b42 100644 --- a/tidb-lightning/troubleshoot-tidb-lightning.md +++ b/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 version might improve the import speed. When upgrading, it is recommended to keep TiDB Lightning and the target TiDB cluster at the same version. ## The `tidb-lightning` process suddenly quits while running in background diff --git a/tidb-troubleshooting-map.md b/tidb-troubleshooting-map.md index 7c3e3771ff703..7514851a93c9c 100644 --- a/tidb-troubleshooting-map.md +++ b/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 version might improve the import speed. When upgrading, it is recommended to keep TiDB Lightning and the target TiDB cluster at the same version. - 6.2.3 `checksum failed: checksum mismatched remote vs local`. From 9466cd9286b0bb8692376ed8b29c666285447db9 Mon Sep 17 00:00:00 2001 From: YangKeao Date: Sun, 20 Sep 2026 18:34:46 +0800 Subject: [PATCH 2/3] docs: focus Lightning FAQ on version selection --- tidb-lightning/tidb-lightning-faq.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tidb-lightning/tidb-lightning-faq.md b/tidb-lightning/tidb-lightning-faq.md index f8cd9cae315f5..75eea6f0a781c 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/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? -It is recommended to use the same version of TiDB Lightning as the target TiDB 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. +It is recommended to use the same version of TiDB Lightning as the target TiDB cluster. ## Does TiDB Lightning support importing multiple schemas (databases)? From 84ac28e36459ea4dd7814149bca5922cd0b73797 Mon Sep 17 00:00:00 2001 From: YangKeao Date: Sun, 20 Sep 2026 18:41:54 +0800 Subject: [PATCH 3/3] docs: address Lightning version guidance review --- get-started-with-tidb-lightning.md | 4 ++-- import-example-data.md | 4 ++-- migrate-from-sql-files-to-tidb.md | 4 +++- migrate-large-mysql-to-tidb.md | 4 +++- tidb-lightning/deploy-tidb-lightning.md | 2 +- tidb-lightning/tidb-lightning-faq.md | 2 +- tidb-lightning/troubleshoot-tidb-lightning.md | 2 +- tidb-troubleshooting-map.md | 2 +- 8 files changed, 14 insertions(+), 10 deletions(-) diff --git a/get-started-with-tidb-lightning.md b/get-started-with-tidb-lightning.md index 0ab97e5f4a623..84c132c5a8565 100644 --- a/get-started-with-tidb-lightning.md +++ b/get-started-with-tidb-lightning.md @@ -51,7 +51,7 @@ For the steps on deploying a TiDB cluster, refer to the [Quick Start with TiDB S ## Step 3: Install 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 `` with the version of the target TiDB cluster (for example, `v8.5.0`): +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 `` with the version of the target TiDB cluster (for example, `v{{{ .tidb-version }}}`): ```shell tiup install tidb-lightning: @@ -96,7 +96,7 @@ 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. In the following example, replace `` with the version installed in Step 3: +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 `` with the TiDB Lightning version installed in [Step 3](#step-3-install-tidb-lightning): ```shell #!/bin/bash diff --git a/import-example-data.md b/import-example-data.md index 559e0901581a3..18eb1c10fe7b2 100644 --- a/import-example-data.md +++ b/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 `` with the version of your target TiDB cluster. ```shell - tiup tidb-lightning -c tidb-lightning.toml + tiup tidb-lightning: -c tidb-lightning.toml ``` diff --git a/migrate-from-sql-files-to-tidb.md b/migrate-from-sql-files-to-tidb.md index 583be648f38c2..de8b908e74f0b 100644 --- a/migrate-from-sql-files-to-tidb.md +++ b/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 `` 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: -config tidb-lightning.toml > nohup.out 2>&1 & ``` TiDB Lightning also supports reading credential files from `~/.aws/credentials`. diff --git a/migrate-large-mysql-to-tidb.md b/migrate-large-mysql-to-tidb.md index 2ee73b2883d06..42e97ccf564ca 100644 --- a/migrate-large-mysql-to-tidb.md +++ b/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 `` 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: -config tidb-lightning.toml > nohup.out 2>&1 & ``` Then use the script to start TiDB Lightning. diff --git a/tidb-lightning/deploy-tidb-lightning.md b/tidb-lightning/deploy-tidb-lightning.md index 40d8e415a0f98..b711e589900ad 100644 --- a/tidb-lightning/deploy-tidb-lightning.md +++ b/tidb-lightning/deploy-tidb-lightning.md @@ -21,7 +21,7 @@ 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. It is recommended to use the same version of TiDB Lightning as the target TiDB cluster. Replace `` with the version of the target TiDB cluster (for example, `v8.5.0`): +2. Install TiDB Lightning using TiUP. It is recommended to use the same version of TiDB Lightning as the target TiDB cluster. Replace `` with the version of the target TiDB cluster (for example, `v{{{ .tidb-version }}}`): ```shell tiup install tidb-lightning: diff --git a/tidb-lightning/tidb-lightning-faq.md b/tidb-lightning/tidb-lightning-faq.md index 75eea6f0a781c..e44959ac6a993 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -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`. Replace `` with the TiDB Lightning version used by the original task. +2. Start a new `tidb-lightning` task by rerunning the command used to start the original task, such as `nohup tiup tidb-lightning: -config tidb-lightning.toml`. Replace `` with the TiDB Lightning version used by the original task. ## How to ensure the integrity of the imported data? diff --git a/tidb-lightning/troubleshoot-tidb-lightning.md b/tidb-lightning/troubleshoot-tidb-lightning.md index 6adb231ce0b42..c8c680814dba9 100644 --- a/tidb-lightning/troubleshoot-tidb-lightning.md +++ b/tidb-lightning/troubleshoot-tidb-lightning.md @@ -37,7 +37,7 @@ strict-format = true **Cause 4**: TiDB Lightning is too old. -A newer version might improve the import speed. When upgrading, it is recommended to keep TiDB Lightning and the target TiDB cluster at the same version. +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 diff --git a/tidb-troubleshooting-map.md b/tidb-troubleshooting-map.md index 7514851a93c9c..8c1f64c93cbb5 100644 --- a/tidb-troubleshooting-map.md +++ b/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. A newer version might improve the import speed. When upgrading, it is recommended to keep TiDB Lightning and the target TiDB cluster at the same version. + - 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`.