Merge branch 'master' of github.com:qiancai/docs

Author: qiancai

.github/workflows/dispatch.yml

@@ -18,6 +18,7 @@ on:
       - release-5.0
       - release-4.0
       - release-3.0
+      - i18n-zh-release-8.5
 
 jobs:
   trigger:

.github/workflows/translation-zh.yaml

@@ -2,6 +2,13 @@ name: Translation(zh) by AI
 
 on:
   workflow_dispatch:
+    inputs:
+      file_names:
+        description: 'Specify file names to translate (comma-separated list)'
+        required: false
+        type: string
+        default: ''
+
 
 env:
   CN_CLOUD_BRANCH: i18n-zh-release-8.5
@@ -35,7 +42,11 @@ jobs:
           export GH_TOKEN=${{github.token}}
           cd docs
           npm i
-          node scripts/filterUpdateFiles.js --cloud
+          if [ -n "${{ inputs.file_names }}" ]; then
+            node scripts/fetchFiles.js --files "${{ inputs.file_names }}"
+          else
+            node scripts/filterUpdateFiles.js --cloud
+          fi
           tree tmp
           cd ..
       - name: Copy new files to translator folder

.lycheeignore

@@ -35,3 +35,4 @@ https://centminmod\.com/mydumper\.html
 https://docs\.pingcap\.com/tidb/v6\.6/system-variables#tidb_pessimistic_txn_aggressive_locking-new-in-v660
 https://docs\.pingcap\.com/tidb/v7\.6/system-variables#tidb_ddl_version-new-in-v760
 https://developers\.redhat\.com/blog/2021/01/05/building-red-hat-enterprise-linux-9-for-the-x86-64-v2-microarchitecture-level
+https://.*github.*/%7B%7B%7B%20.tidb_operator_version%20%7D%7D%7D

TOC.md

@@ -436,6 +436,7 @@
   - [Use TiDB](/best-practices/tidb-best-practices.md)
   - [Manage DDL](/ddl-introduction.md)
   - [Optimize Multi-Column Indexes](/best-practices/multi-column-index-best-practices.md)
+  - [Manage Indexes and Identify Unused Indexes](/best-practices/index-management-best-practices.md)
   - [Handle Millions of Tables in SaaS Multi-Tenant Scenarios](/best-practices/saas-best-practices.md)
   - [Use UUIDs as Primary Keys](/best-practices/uuid.md)
   - [Develop Java Applications](/best-practices/java-app-best-practices.md)
@@ -1084,6 +1085,7 @@
   - [Schedule Replicas by Topology Labels](/schedule-replicas-by-topology-labels.md)
   - [URI Formats of External Storage Services](/external-storage-uri.md)
   - [TiDB Workload Repository](/workload-repository.md)
+  - [Interaction Test on Online Workloads and `ADD INDEX` Operations](/benchmark/online-workloads-and-add-index-operations.md)
 - FAQs
   - [FAQ Summary](/faq/faq-overview.md)
   - [TiDB FAQs](/faq/tidb-faq.md)

best-practices-for-security-configuration.md

@@ -20,6 +20,8 @@ To avoid this risk, it is recommended to set a root password during deployment:
 - For deployments using TiUP, refer to [Deploy TiDB Cluster Using TiUP](/production-deployment-using-tiup.md#step-7-start-a-tidb-cluster) to generate a random password for the root user.
 - For deployments using TiDB Operator, refer to [Set initial account and password](https://docs.pingcap.com/tidb-in-kubernetes/stable/initialize-a-cluster#set-initial-account-and-password) to set the root password.
 
+You can also use the [`--initialize-secure`](/command-line-flags-for-tidb-configuration.md#--initialize-secure) option to restrict network access for the initial root user.
+
 ## Enable password complexity checks
 
 By default, TiDB does not enforce password complexity policies, which might lead to the use of weak or empty passwords, increasing security risks.

best-practices/index-management-best-practices.md

@@ -49,7 +49,7 @@ When you start the TiDB cluster, you can use command-line options or environment
 
 ## `--initialize-secure`
 
-- Bootstraps tidb-server in secure mode
+- Controls whether to create a `root` account using the `auth_socket` authentication method during tidb-server initialization. If it is set to `true`, when connecting to TiDB for the first time, you must use a socket connection, which provides stronger security.
 - Default: `false`
 
 ## `--initialize-sql-file`

command-line-flags-for-tidb-configuration.md

@@ -6,7 +6,7 @@ global:
   deploy_dir: "/tidb-deploy"
   data_dir: "/tidb-data"
 component_versions:
-  tiproxy: "v1.2.0"
+  tiproxy: "v1.3.2"
 server_configs:
   tidb:
     graceful-wait-before-shutdown: 30

config-templates/simple-tiproxy.yaml

@@ -1,46 +1,56 @@
 ---
 title: Compatibility Catalog of TiDB Data Migration
-summary: This document describes the compatibility between DM of different versions and upstream/downstream databases.
+summary: This document describes the compatibility of TiDB Data Migration (DM) with upstream and downstream databases.
 ---
 
 # Compatibility Catalog of TiDB Data Migration
 
 DM supports migrating data from different sources to TiDB clusters. Based on the data source type, DM has four compatibility levels:
 
-- **Generally available (GA)**: The application scenario has been verified and passed the GA test.
-- **Experimental**: Although the application scenario has been verified, the test does not cover all scenarios or involves only a limited number of users. The application scenario might encounter problems occasionally.
-- **Not tested**: DM is expected to be always compatible with MySQL during iteration. However, due to resource constraints, not all MySQL forks are tested with DM. Therefore, the *not tested* source or target is technically compatible with DM, but is not fully tested, which means you need to verify its compatibility before you use.
-- **Incompatible**: DM is proved to be incompatible with the data source and the application is not recommended for use in production environments.
+- **Generally available (GA)**: The application scenario has been verified and passed GA testing.
+- **Experimental**: Common application scenarios have been verified, but coverage is limited or involves only a small number of users. Occasional issues are possible, so you need to verify compatibility in your specific scenario.
+- **Not tested**: DM aims to be compatible with the MySQL protocol and binlog. However, not all MySQL forks or versions are included in the DM test matrix. If a fork or version uses MySQL-compatible protocols and binlog formats, it is expected to work, but you must verify compatibility in your own environment before use.
+- **Incompatible**: DM has known blocking issues, so production use is not recommended.
 
 ## Data sources
 
-|Data source|Compatibility level|Remarks|
-|-|-|-|
-|MySQL ≤ 5.5|Not tested||
-|MySQL 5.6|GA||
-|MySQL 5.7|GA||
-|MySQL 8.0|GA|Does not support binlog transaction compression [Transaction_payload_event](https://dev.mysql.com/doc/refman/8.0/en/binary-log-transaction-compression.html)|
-|MariaDB < 10.1.2|Incompatible|Incompatible with binlog of the time type|
-|MariaDB 10.1.2 ~ 10.5.10|Experimental||
-|MariaDB > 10.5.10|Incompatible|Permission errors reported in the check procedure|
+| Data source | Compatibility level | Note |
+| - | - | - |
+| MySQL ≤ 5.5 | Not tested | |
+| MySQL 5.6 | GA | |
+| MySQL 5.7 | GA | |
+| MySQL 8.0 | GA | Does not support binlog transaction compression [Transaction_payload_event](https://dev.mysql.com/doc/refman/8.0/en/binary-log-transaction-compression.html). |
+| MariaDB < 10.1.2 | Incompatible | Incompatible with binlog of the time type. |
+| MariaDB 10.1.2 ~ 10.5.10 | Experimental | |
+| MariaDB > 10.5.10 | Not tested | Expected to work in most cases after bypassing the [precheck](/dm/dm-precheck.md). See [MariaDB notes](#mariadb-notes). |
+
+### Incompatibility with foreign key CASCADE operations
+
+- DM creates foreign key **constraints** on the target, but they are not enforced while applying transactions because DM sets the session variable [`foreign_key_checks=OFF`](/system-variables.md#foreign_key_checks).
+- DM does **not** support `ON DELETE CASCADE` or `ON UPDATE CASCADE` behavior by default, and enabling `foreign_key_checks` via a DM task session variable is not recommended. If your workload relies on cascades, **do not assume** that cascade effects will be replicated.
+
+### MariaDB notes
+
+- For MariaDB **10.5.11 and later**, the DM **precheck fails** due to privilege name changes (for example, `BINLOG MONITOR`, `REPLICATION SLAVE ADMIN`, `REPLICATION MASTER ADMIN`). The error appears as `[code=26005] fail to check synchronization configuration` in the replication privilege, dump privilege, and dump connection number checkers.
+- You can **bypass the precheck** by adding `ignore-checking-items: ["all"]` in the DM task. See [DM precheck](/dm/dm-precheck.md) for details.
 
 ## Target databases
 
 > **Warning:**
 >
-> DM v5.3.0 is not recommended. If you have enabled GTID replication but do not enable relay log in DM v5.3.0, data replication fails with low probability.
-
-|Target database|Compatibility level|DM version|
-|-|-|-|
-|TiDB 8.x|GA|≥ 5.3.1|
-|TiDB 7.x|GA|≥ 5.3.1|
-|TiDB 6.x|GA|≥ 5.3.1|
-|TiDB 5.4|GA|≥ 5.3.1|
-|TiDB 5.3|GA|≥ 5.3.1|
-|TiDB 5.2|GA|≥ 2.0.7, recommended: 5.4|
-|TiDB 5.1|GA|≥ 2.0.4, recommended: 5.4|
-|TiDB 5.0|GA|≥ 2.0.4, recommended: 5.4|
-|TiDB 4.x|GA|≥ 2.0.1, recommended: 2.0.7|
-|TiDB 3.x|GA|≥ 2.0.1, recommended: 2.0.7|
-|MySQL|Experimental||
-|MariaDB|Experimental||
+> DM v5.3.0 is not recommended. Enabling GTID replication without relay log in DM v5.3.0 might cause data replication to fail, although the probability is low.
+
+| Target database | Compatibility level | DM version |
+| - | - | - |
+| TiDB 8.x | GA | ≥ 5.3.1 |
+| TiDB 7.x | GA | ≥ 5.3.1 |
+| TiDB 6.x | GA | ≥ 5.3.1 |
+| TiDB 5.4 | GA | ≥ 5.3.1 |
+| TiDB 5.3 | GA | ≥ 5.3.1 |
+| TiDB 5.2 | GA | ≥ 2.0.7, recommended: 5.4 |
+| TiDB 5.1 | GA | ≥ 2.0.4, recommended: 5.4 |
+| TiDB 5.0 | GA | ≥ 2.0.4, recommended: 5.4 |
+| TiDB 4.x | GA | ≥ 2.0.1, recommended: 2.0.7 |
+| TiDB 3.x | GA | ≥ 2.0.1, recommended: 2.0.7 |
+| MySQL | Experimental | |
+| MariaDB | Experimental | |

dm/dm-compatibility-catalog.md

@@ -32,8 +32,8 @@ Default: leader
 
 This variable is used to set the expected data read mode.
 
-- When the value of `tidb_replica_read` is set to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform.
-- When the value of `tidb_replica_read` is set to `follower`, TiDB selects a follower replica of the Region to perform all read operations.
+- When you set the value of `tidb_replica_read` to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform.
+- When you set the value of `tidb_replica_read` to `follower`, TiDB selects a follower replica of the Region to perform read operations. If the Region has learner replicas, TiDB also considers them for reads with the same priority. If no available follower or learner replicas exist for the current Region, TiDB reads from the leader replica.
 - When the value of `tidb_replica_read` is set to `leader-and-follower`, TiDB can select any replicas to perform read operations. In this mode, read requests are load balanced between the leader and follower.
 - When the value of `tidb_replica_read` is set to `prefer-leader`, TiDB prefers to select the leader replica to perform read operations. If the leader replica is obviously slow in processing read operations (such as caused by disk or network performance jitter), TiDB will select other available follower replicas to perform read operations.
 - When the value of `tidb_replica_read` is set to `closest-replicas`, TiDB prefers to select a replica in the same availability zone to perform read operations, which can be a leader or a follower. If there is no replica in the same availability zone, TiDB reads from the leader replica.
@@ -42,13 +42,18 @@ This variable is used to set the expected data read mode.
     - If the estimated result of a read request is greater than or equal to the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB prefers to select a replica in the same availability zone for read operations. To avoid unbalanced distribution of read traffic across availability zones, TiDB dynamically detects the distribution of availability zones for all online TiDB and TiKV nodes. In each availability zone, the number of TiDB nodes whose `closest-adaptive` configuration takes effect is limited, which is always the same as the number of TiDB nodes in the availability zone with the fewest TiDB nodes, and the other TiDB nodes automatically read from the leader replica. For example, if TiDB nodes are distributed across 3 availability zones (A, B, and C), where A and B each contains 3 TiDB nodes and C contains only 2 TiDB nodes, the number of TiDB nodes whose `closest-adaptive` configuration takes effect in each availability zone is 2, and the other TiDB node in each of the A and B availability zones automatically selects the leader replica for read operations.
     - If the estimated result of a read request is less than the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB can only select the leader replica for read operations.
 
-- When the value of `tidb_replica_read` is set to `learner`, TiDB reads data from the learner replica. If there is no learner replica in the Region, TiDB returns an error.
+- When you set the value of `tidb_replica_read` to `learner`, TiDB reads data from the learner replica. If no learner replica is available for the current Region, TiDB reads from an available leader or follower replica.
 
 <CustomContent platform="tidb">
 
 > **Note:**
 >
-> When the value of `tidb_replica_read` is set to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data).
+> When you set `tidb_replica_read` to `closest-replicas` or `closest-adaptive`, to ensure that replicas are distributed across availability zones according to the specified configuration, you need to configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV according to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/stable/configure-a-tidb-cluster#high-availability-of-data).
+>
+> For TiDB v7.5.0 and earlier versions:
+>
+> - If you set `tidb_replica_read` to `follower` and no follower or learner replicas are available, TiDB returns an error.
+> - If you set `tidb_replica_read` to `learner` and no learner replicas are available, TiDB returns an error.
 
 </CustomContent>