From 9146c0654bdc363b9ea398b64e051da731ed2c1b Mon Sep 17 00:00:00 2001 From: doc-claw-bot Date: Wed, 14 Oct 2026 02:15:44 +0000 Subject: [PATCH 1/5] docs: fix TiUP deployment doc inconsistencies --- check-before-deployment.md | 12 ++++++------ post-installation-check.md | 6 ++++++ production-deployment-using-tiup.md | 2 +- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/check-before-deployment.md b/check-before-deployment.md index 7e6ddf5691adc..ae24de5ff6f36 100644 --- a/check-before-deployment.md +++ b/check-before-deployment.md @@ -108,17 +108,17 @@ Take the `/dev/nvme0n1` data disk as an example: TiDB needs a sufficient amount of memory for operation. If the memory that TiDB uses gets swapped out and later gets swapped back in, this can cause latency spikes. If you want to maintain stable performance, it is recommended that you permanently disable the system swap, but it might trigger OOM issues when there is insufficient memory. If you want to avoid such OOM issues, you can just decrease the swap priority, instead of permanently disabling it. -- Enabling and using swap might introduce performance jitter issues. It is recommended that you permanently disable the operating system tier swap for low-latency and stability-critical database services. To permanently disable swap, you can use the following method: +- Enabling and using swap might introduce performance jitter issues. It is recommended that you permanently disable the operating system tier swap for low-latency and stability-critical database services. To disable swap, you can use the following method: - During the initialization phase of the operating system, do not partition the swap partition disk separately. - - If you have already partitioned a separate swap partition disk during the initialization phase of the operating system and enabled swap, run the following command to disable it: + - If you have already partitioned a separate swap partition disk during the initialization phase of the operating system and enabled swap, run the following command to disable it immediately: ```bash - echo "vm.swappiness = 0">> /etc/sysctl.conf - sysctl -p - swapoff -a && swapon -a + swapoff -a ``` + - To keep swap disabled after a reboot, remove or comment out the corresponding swap entry in `/etc/fstab`. + - If the host memory is insufficient, disabling the system swap might be more likely to trigger OOM issues. You can run the following command to decrease the swap priority instead of disabling it permanently: ```bash @@ -794,7 +794,7 @@ sudo yum -y install numactl 1. Follow [Deploy a TiDB Cluster Using TiUP](/production-deployment-using-tiup.md) to deploy a cluster `tidb-test`. If you have installed a TiDB cluster, you can skip this step. ```bash - tiup cluster deploy tidb-test v6.1.0 ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa] + tiup cluster deploy tidb-test v{{{ .tidb-version }}} ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa] ``` 2. Run the `tiup cluster exec` command using the `sudo` privilege to install NUMA on all the target machines in the `tidb-test` cluster: diff --git a/post-installation-check.md b/post-installation-check.md index 8e991786dc586..3461448c5e447 100644 --- a/post-installation-check.md +++ b/post-installation-check.md @@ -56,6 +56,12 @@ Log in to the database by running the following command: mysql -u root -h ${tidb_server_host_IP_address} -P 4000 ``` +If you started the cluster using `tiup cluster start tidb-test --init`, append `-p` and enter the generated password: + +```shell +mysql -u root -p -h ${tidb_server_host_IP_address} -P 4000 +``` + `${tidb_server_host_IP_address}` is one of the IP addresses set for `tidb_servers` when you [initialize the cluster topology file](/production-deployment-using-tiup.md#step-3-initialize-the-cluster-topology-file), such as `10.0.1.7`. The following information indicates successful login: diff --git a/production-deployment-using-tiup.md b/production-deployment-using-tiup.md index e008bc48aa6d6..106fac27872db 100644 --- a/production-deployment-using-tiup.md +++ b/production-deployment-using-tiup.md @@ -250,7 +250,7 @@ alertmanager_servers: - host: 10.0.1.4 ``` -The following examples cover six common scenarios. You need to modify the configuration file (named `topology.yaml`) according to the topology description and templates in the corresponding links. For other scenarios, edit the configuration template accordingly. +The following examples cover five common scenarios. You need to modify the configuration file (named `topology.yaml`) according to the topology description and templates in the corresponding links. For other scenarios, edit the configuration template accordingly. | Application | Configuration task | Configuration file template | Topology description | | :-- | :-- | :-- | :-- | From 2c11fcdd9286551d83e092a3220b2b86c9360ee0 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 2 Nov 2026 16:43:04 +0800 Subject: [PATCH 2/5] docs: clarify swap and root login guidance --- check-before-deployment.md | 31 ++++++++++++++++++++++++------- post-installation-check.md | 10 +++++----- 2 files changed, 29 insertions(+), 12 deletions(-) diff --git a/check-before-deployment.md b/check-before-deployment.md index ae24de5ff6f36..6be8eb4e22766 100644 --- a/check-before-deployment.md +++ b/check-before-deployment.md @@ -106,20 +106,37 @@ Take the `/dev/nvme0n1` data disk as an example: ## Check and disable system swap -TiDB needs a sufficient amount of memory for operation. If the memory that TiDB uses gets swapped out and later gets swapped back in, this can cause latency spikes. If you want to maintain stable performance, it is recommended that you permanently disable the system swap, but it might trigger OOM issues when there is insufficient memory. If you want to avoid such OOM issues, you can just decrease the swap priority, instead of permanently disabling it. +Swapping TiDB memory out to disk and back can cause latency spikes. For stable performance, it is recommended that you permanently disable system swap. However, disabling swap can increase the risk of out-of-memory (OOM) issues when memory is insufficient. Choose one of the following options based on your memory capacity and latency requirements: -- Enabling and using swap might introduce performance jitter issues. It is recommended that you permanently disable the operating system tier swap for low-latency and stability-critical database services. To disable swap, you can use the following method: +- Disable swap for latency-sensitive workloads: - - During the initialization phase of the operating system, do not partition the swap partition disk separately. - - If you have already partitioned a separate swap partition disk during the initialization phase of the operating system and enabled swap, run the following command to disable it immediately: + 1. When installing the operating system, do not create swap partitions or swap files. If swap is already enabled, run the following command to disable it immediately: ```bash swapoff -a ``` - - To keep swap disabled after a reboot, remove or comment out the corresponding swap entry in `/etc/fstab`. + 2. To prevent swap from being enabled at boot, remove or comment out all swap entries in `/etc/fstab`. -- If the host memory is insufficient, disabling the system swap might be more likely to trigger OOM issues. You can run the following command to decrease the swap priority instead of disabling it permanently: + On hosts that use `systemd-gpt-auto-generator`, GPT swap partitions on the same disk as the root partition can be activated automatically even without an `/etc/fstab` entry. On these hosts, list the swap units: + + ```bash + systemctl list-units --type=swap --all + ``` + + For each corresponding swap unit, run the following command to prevent automatic activation. Replace `` with the actual unit name from the output, such as `dev-sda2.swap`: + + ```bash + systemctl mask + ``` + + For more information, see [systemd-gpt-auto-generator](https://www.freedesktop.org/software/systemd/man/latest/systemd-gpt-auto-generator.html) and [systemctl mask](https://www.freedesktop.org/software/systemd/man/latest/systemctl.html). + + 3. After disabling swap, and again after the next reboot, run `cat /proc/swaps`. If swap is disabled, the output contains only the header row. + +- Keep swap enabled when memory is insufficient: + + Set `vm.swappiness=0` to reduce the kernel's tendency to swap. This setting does not disable swap: the kernel can still use it under memory pressure. Run the following commands to save the setting in `/etc/sysctl.conf` and apply it immediately: ```bash echo "vm.swappiness = 0">> /etc/sysctl.conf @@ -794,7 +811,7 @@ sudo yum -y install numactl 1. Follow [Deploy a TiDB Cluster Using TiUP](/production-deployment-using-tiup.md) to deploy a cluster `tidb-test`. If you have installed a TiDB cluster, you can skip this step. ```bash - tiup cluster deploy tidb-test v{{{ .tidb-version }}} ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa] + tiup cluster deploy tidb-test {{{ .tidb-version }}} ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa] ``` 2. Run the `tiup cluster exec` command using the `sudo` privilege to install NUMA on all the target machines in the `tidb-test` cluster: diff --git a/post-installation-check.md b/post-installation-check.md index 3461448c5e447..a8bf8dcbcfed0 100644 --- a/post-installation-check.md +++ b/post-installation-check.md @@ -26,7 +26,7 @@ Expected output: If the `Status` information of each node is `Up`, the cluster r ### Use TiDB Dashboard -1. Log in to TiDB Dashboard at `${pd-ip}:${pd-port}/dashboard`. The username and password is the same as that of the TiDB `root` user. If you have modified the `root` password, enter the modified password. The password is empty by default. +1. Log in to TiDB Dashboard at `${pd-ip}:${pd-port}/dashboard` with the TiDB `root` username and current password. The initial password is generated by TiUP if you started the cluster with `--init`; otherwise, it is empty. ![TiDB-Dashboard](/media/tiup/tidb-dashboard.png) @@ -48,18 +48,18 @@ Expected output: If the `Status` information of each node is `Up`, the cluster r > > Install the MySQL client before you log in to the database. -Log in to the database by running the following command: +To log in with a root password, run the following command and enter the password when prompted. If you used the recommended [safe start method](/production-deployment-using-tiup.md#step-7-start-a-tidb-cluster) (`tiup cluster start tidb-test --init`), use the password displayed in the TiUP command output, unless you have since changed it: {{< copyable "shell-regular" >}} ```shell -mysql -u root -h ${tidb_server_host_IP_address} -P 4000 +mysql -u root -p -h ${tidb_server_host_IP_address} -P 4000 ``` -If you started the cluster using `tiup cluster start tidb-test --init`, append `-p` and enter the generated password: +If you started the cluster without `--init` and have not set a root password, omit `-p`: ```shell -mysql -u root -p -h ${tidb_server_host_IP_address} -P 4000 +mysql -u root -h ${tidb_server_host_IP_address} -P 4000 ``` `${tidb_server_host_IP_address}` is one of the IP addresses set for `tidb_servers` when you [initialize the cluster topology file](/production-deployment-using-tiup.md#step-3-initialize-the-cluster-topology-file), such as `10.0.1.7`. From 6651418d8256a153abea4fe77ed7fc0085f4555f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 2 Nov 2026 16:49:27 +0800 Subject: [PATCH 3/5] Apply suggestions from code review --- check-before-deployment.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/check-before-deployment.md b/check-before-deployment.md index 6be8eb4e22766..f41ecaba5e619 100644 --- a/check-before-deployment.md +++ b/check-before-deployment.md @@ -108,7 +108,7 @@ Take the `/dev/nvme0n1` data disk as an example: Swapping TiDB memory out to disk and back can cause latency spikes. For stable performance, it is recommended that you permanently disable system swap. However, disabling swap can increase the risk of out-of-memory (OOM) issues when memory is insufficient. Choose one of the following options based on your memory capacity and latency requirements: -- Disable swap for latency-sensitive workloads: +- Option 1: Disable swap for latency-sensitive workloads: 1. When installing the operating system, do not create swap partitions or swap files. If swap is already enabled, run the following command to disable it immediately: @@ -134,7 +134,7 @@ Swapping TiDB memory out to disk and back can cause latency spikes. For stable p 3. After disabling swap, and again after the next reboot, run `cat /proc/swaps`. If swap is disabled, the output contains only the header row. -- Keep swap enabled when memory is insufficient: +- Option 2: Keep swap enabled when memory is insufficient: Set `vm.swappiness=0` to reduce the kernel's tendency to swap. This setting does not disable swap: the kernel can still use it under memory pressure. Run the following commands to save the setting in `/etc/sysctl.conf` and apply it immediately: From 239caf8ffc45a88b9037d0299665458cbcc2b4d1 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 2 Nov 2026 16:55:53 +0800 Subject: [PATCH 4/5] Update post-installation-check.md --- post-installation-check.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/post-installation-check.md b/post-installation-check.md index a8bf8dcbcfed0..3d23a6c84ceee 100644 --- a/post-installation-check.md +++ b/post-installation-check.md @@ -26,7 +26,13 @@ Expected output: If the `Status` information of each node is `Up`, the cluster r ### Use TiDB Dashboard -1. Log in to TiDB Dashboard at `${pd-ip}:${pd-port}/dashboard` with the TiDB `root` username and current password. The initial password is generated by TiUP if you started the cluster with `--init`; otherwise, it is empty. +1. Log in to TiDB Dashboard at `${pd-ip}:${pd-port}/dashboard` using the TiDB `root` account and its current password. + + > **Note:** + > + > If you initialized the cluster with `--init`, TiUP generates the initial root password. Otherwise, the initial password is empty. + > + > If you have changed the password, use the updated password. Restarting the cluster without `--init` does not reset an existing password. ![TiDB-Dashboard](/media/tiup/tidb-dashboard.png) @@ -56,7 +62,7 @@ To log in with a root password, run the following command and enter the password mysql -u root -p -h ${tidb_server_host_IP_address} -P 4000 ``` -If you started the cluster without `--init` and have not set a root password, omit `-p`: +If the cluster was initially started without `--init` and no root password has been set, omit `-p`: ```shell mysql -u root -h ${tidb_server_host_IP_address} -P 4000 From 57685d61bf0182e812d220e72b6e6de7ed788934 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 2 Nov 2026 17:15:46 +0800 Subject: [PATCH 5/5] docs: clarify swap prerequisites and unit discovery --- check-before-deployment.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/check-before-deployment.md b/check-before-deployment.md index f41ecaba5e619..37db0decf8da7 100644 --- a/check-before-deployment.md +++ b/check-before-deployment.md @@ -110,7 +110,7 @@ Swapping TiDB memory out to disk and back can cause latency spikes. For stable p - Option 1: Disable swap for latency-sensitive workloads: - 1. When installing the operating system, do not create swap partitions or swap files. If swap is already enabled, run the following command to disable it immediately: + 1. When installing the operating system, do not create swap partitions or swap files. If swap is already enabled, first ensure that enough memory is available to reload the swapped-out data, then run the following command to disable swap: ```bash swapoff -a @@ -118,13 +118,13 @@ Swapping TiDB memory out to disk and back can cause latency spikes. For stable p 2. To prevent swap from being enabled at boot, remove or comment out all swap entries in `/etc/fstab`. - On hosts that use `systemd-gpt-auto-generator`, GPT swap partitions on the same disk as the root partition can be activated automatically even without an `/etc/fstab` entry. On these hosts, list the swap units: + On hosts that use `systemd-gpt-auto-generator`, GPT swap partitions on the same disk as the root partition can be activated automatically even without an `/etc/fstab` entry. On these hosts, list the swap unit files: ```bash - systemctl list-units --type=swap --all + systemctl list-unit-files --type=swap ``` - For each corresponding swap unit, run the following command to prevent automatic activation. Replace `` with the actual unit name from the output, such as `dev-sda2.swap`: + For each swap unit you want to disable permanently, run the following command to prevent automatic activation. Replace `` with the actual unit name from the output, such as `dev-sda2.swap`: ```bash systemctl mask @@ -134,7 +134,7 @@ Swapping TiDB memory out to disk and back can cause latency spikes. For stable p 3. After disabling swap, and again after the next reboot, run `cat /proc/swaps`. If swap is disabled, the output contains only the header row. -- Option 2: Keep swap enabled when memory is insufficient: +- Option 2: For hosts with limited memory, keep swap enabled and reduce the kernel's tendency to swap: Set `vm.swappiness=0` to reduce the kernel's tendency to swap. This setting does not disable swap: the kernel can still use it under memory pressure. Run the following commands to save the setting in `/etc/sysctl.conf` and apply it immediately: