From 167e5c00b0151146fe74ade234da13dac1a071ac 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 39ea282088d4f..6278d1f47b5c7 100644 --- a/get-started-with-tidb-lightning.md +++ b/get-started-with-tidb-lightning.md @@ -50,10 +50,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 @@ -95,11 +95,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 f2afceff11ebc..c8751896fd3cd 100644 --- a/tidb-lightning/deploy-tidb-lightning.md +++ b/tidb-lightning/deploy-tidb-lightning.md @@ -20,17 +20,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 b37f531a9cb45..dd4e3236965ec 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -9,7 +9,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)? @@ -26,7 +26,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 20880a475fbb3..ce80bca0c3f33 100644 --- a/tidb-lightning/troubleshoot-tidb-lightning.md +++ b/tidb-lightning/troubleshoot-tidb-lightning.md @@ -36,7 +36,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 35c1ff3bb8a55..1a3f9529b40a0 100644 --- a/tidb-troubleshooting-map.md +++ b/tidb-troubleshooting-map.md @@ -454,7 +454,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 5fe167464419bf17f195dfe7332a4d8af249be60 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 dd4e3236965ec..7e01681012089 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -7,9 +7,9 @@ summary: Learn about the frequently asked questions (FAQs) and answers about TiD 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 56e19194b69dd61058aa0c9219254b31995cb0ca 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 6278d1f47b5c7..9ad1fd85393a0 100644 --- a/get-started-with-tidb-lightning.md +++ b/get-started-with-tidb-lightning.md @@ -50,7 +50,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: @@ -95,7 +95,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 375acbf9fbab6..e8ecc86ba4e57 100644 --- a/import-example-data.md +++ b/import-example-data.md @@ -67,8 +67,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 b1ae86f7b67bc..05c25f1f7cd9f 100644 --- a/migrate-from-sql-files-to-tidb.md +++ b/migrate-from-sql-files-to-tidb.md @@ -73,12 +73,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 c8751896fd3cd..0b1c138653e1a 100644 --- a/tidb-lightning/deploy-tidb-lightning.md +++ b/tidb-lightning/deploy-tidb-lightning.md @@ -20,7 +20,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 7e01681012089..5bf892f4b30a3 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -26,7 +26,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 ce80bca0c3f33..7da58a91b3603 100644 --- a/tidb-lightning/troubleshoot-tidb-lightning.md +++ b/tidb-lightning/troubleshoot-tidb-lightning.md @@ -36,7 +36,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 1a3f9529b40a0..c25e74d654b4f 100644 --- a/tidb-troubleshooting-map.md +++ b/tidb-troubleshooting-map.md @@ -454,7 +454,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`.