pingcap · qiancai · Feb 4, 2026 · Feb 5, 2026 · Feb 5, 2026
diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md
@@ -836,7 +836,7 @@
       - [Overview of TiDB Node Group](/tidb-cloud/tidb-node-group-overview.md)
       - [Manage TiDB Node Groups](/tidb-cloud/tidb-node-group-management.md)
   - [URI Formats of External Storage Services](/external-storage-uri.md)
-  - [DDL Execution Principles and Best Practices](/ddl-introduction.md)
+  - [DDL Execution Principles and Best Practices](/best-practices/ddl-introduction.md)
   - [Troubleshoot Inconsistency Between Data and Indexes](/troubleshoot-data-inconsistency-errors.md)
   - [Notifications](/tidb-cloud/notifications.md)
   - [Glossary](/tidb-cloud/tidb-cloud-glossary.md)

diff --git a/TOC.md b/TOC.md
diff --git a/best-practices-on-public-cloud.md → ...actices/best-practices-on-public-cloud.md b/best-practices-on-public-cloud.md → ...actices/best-practices-on-public-cloud.md
diff --git a/ddl-introduction.md → best-practices/ddl-introduction.md b/ddl-introduction.md → best-practices/ddl-introduction.md
diff --git a/develop/dev-guide-connection-parameters.md b/develop/dev-guide-connection-parameters.md
@@ -9,7 +9,7 @@ This document describes how to configure connection pools and connection paramet
 
 <CustomContent platform="tidb">
 
-If you are interested in more tips about Java application development, see [Best Practices for Developing Java Applications with TiDB](/best-practices/java-app-best-practices.md#connection-pool)
+If you are interested in more tips about Java application development, see [Best Practices for Developing Java Applications with TiDB](/develop/java-app-best-practices.md#connection-pool)
 
 </CustomContent>
 

diff --git a/develop/dev-guide-optimize-sql-best-practices.md b/develop/dev-guide-optimize-sql-best-practices.md
@@ -167,7 +167,7 @@ For how to locate and resolve transaction conflicts, see [Troubleshoot Lock Conf
 
 <CustomContent platform="tidb">
 
-See [Best Practices for Developing Java Applications with TiDB](/best-practices/java-app-best-practices.md).
+See [Best Practices for Developing Java Applications with TiDB](/develop/java-app-best-practices.md).
 
 </CustomContent>
 

diff --git a/best-practices/java-app-best-practices.md → develop/java-app-best-practices.md b/best-practices/java-app-best-practices.md → develop/java-app-best-practices.md
diff --git a/faq/sql-faq.md b/faq/sql-faq.md
@@ -247,7 +247,7 @@ SELECT column_name FROM table_name USE INDEX（index_name）WHERE where_conditio
 
 ## DDL Execution
 
-This section lists issues related to DDL statement execution. For detailed explanations on the DDL execution principles, see [Execution Principles and Best Practices of DDL Statements](/ddl-introduction.md).
+This section lists issues related to DDL statement execution. For detailed explanations on the DDL execution principles, see [Execution Principles and Best Practices of DDL Statements](/best-practices/ddl-introduction.md).
 
 ### How long does it take to perform various DDL operations?
 

diff --git a/performance-tuning-practices.md b/performance-tuning-practices.md
@@ -13,7 +13,7 @@ This document describes how to use these features together to analyze and compar
 >
 > [Top SQL](/dashboard/top-sql.md) and [Continuous Profiling](/dashboard/continuous-profiling.md) are not enabled by default. You need to enable them in advance.
 
-By running the same application with different JDBC configurations in these scenarios, this document shows you how the overall system performance is affected by different interactions between applications and databases, so that you can apply [Best Practices for Developing Java Applications with TiDB](/best-practices/java-app-best-practices.md) for better performance.
+By running the same application with different JDBC configurations in these scenarios, this document shows you how the overall system performance is affected by different interactions between applications and databases, so that you can apply [Best Practices for Developing Java Applications with TiDB](/develop/java-app-best-practices.md) for better performance.
 
 ## Environment description
 

diff --git a/releases/release-7.0.0.md b/releases/release-7.0.0.md
@@ -86,7 +86,7 @@ In v7.0.0-DMR, the key new features and improvements are as follows:
 
     Starting from TiDB v7.0.0, Fast Online DDL and PITR are fully compatible. When restoring cluster data through PITR, the index operations added via Fast Online DDL during log backup will be automatically replayed to achieve compatibility.
 
-    For more information, see [documentation](/ddl-introduction.md).
+    For more information, see [documentation](/best-practices/ddl-introduction.md).
 
 * TiFlash supports null-aware semi join and null-aware anti semi join operators [#6674](https://github.com/pingcap/tiflash/issues/6674) @[gengliqi](https://github.com/gengliqi)
 
@@ -142,7 +142,7 @@ In v7.0.0-DMR, the key new features and improvements are as follows:
 
     TiDB v6.5.0 supports creating ordinary secondary indexes via Fast Online DDL. TiDB v7.0.0 supports creating unique indexes via Fast Online DDL. Compared to v6.1.0, adding unique indexes to large tables is expected to be several times faster with improved performance.
 
-    For more information, see [documentation](/ddl-introduction.md).
+    For more information, see [documentation](/best-practices/ddl-introduction.md).
 
 ### Reliability
 
@@ -168,7 +168,7 @@ In v7.0.0-DMR, the key new features and improvements are as follows:
 
     TiDB v7.0.0 introduces a checkpoint mechanism for [Fast Online DDL](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630), which significantly improves its fault tolerance and automatic recovery capabilities. By periodically recording and synchronizing the DDL progress, ongoing DDL operations can continue to be executed in Fast Online DDL mode even if there is a TiDB DDL Owner failure or switch. This makes the execution of DDL more stable and efficient.
 
-    For more information, see [documentation](/ddl-introduction.md).
+    For more information, see [documentation](/best-practices/ddl-introduction.md).
 
 * TiFlash supports spilling to disk [#6528](https://github.com/pingcap/tiflash/issues/6528) @[windtalker](https://github.com/windtalker)
 

diff --git a/releases/release-7.1.0.md b/releases/release-7.1.0.md
@@ -156,7 +156,7 @@ Compared with the previous LTS 6.5.0, 7.1.0 not only includes new features, impr
 
 * Support the checkpoint mechanism for Fast Online DDL to improve fault tolerance and automatic recovery capability [#42164](https://github.com/pingcap/tidb/issues/42164) @[tangenta](https://github.com/tangenta)
 
-    TiDB v7.1.0 introduces a checkpoint mechanism for [Fast Online DDL](/ddl-introduction.md), which significantly improves the fault tolerance and automatic recovery capability of Fast Online DDL. Even if the TiDB owner node is restarted or changed due to failures, TiDB can still recover progress from checkpoints that are automatically updated on a regular basis, making the DDL execution more stable and efficient.
+    TiDB v7.1.0 introduces a checkpoint mechanism for [Fast Online DDL](/best-practices/ddl-introduction.md), which significantly improves the fault tolerance and automatic recovery capability of Fast Online DDL. Even if the TiDB owner node is restarted or changed due to failures, TiDB can still recover progress from checkpoints that are automatically updated on a regular basis, making the DDL execution more stable and efficient.
 
     For more information, see [documentation](/system-variables.md#tidb_ddl_enable_fast_reorg-new-in-v630).
 

diff --git a/releases/release-7.2.0.md b/releases/release-7.2.0.md
@@ -146,7 +146,7 @@ Quick access: [Quick start](https://docs-archive.pingcap.com/tidb/v7.2/quick-sta
     ADMIN RESUME DDL JOBS 1,2;
     ```
 
-    For more information, see [documentation](/ddl-introduction.md#ddl-related-commands).
+    For more information, see [documentation](/best-practices/ddl-introduction.md#ddl-related-commands).
 
 ### Data migration
 

diff --git a/releases/release-7.5.0.md b/releases/release-7.5.0.md
@@ -108,7 +108,7 @@ Compared with the previous LTS 7.1.0, 7.5.0 includes new features, improvements,
     ADMIN RESUME DDL JOBS 1,2;
     ```
 
-    For more information, see [documentation](/ddl-introduction.md#ddl-related-commands).
+    For more information, see [documentation](/best-practices/ddl-introduction.md#ddl-related-commands).
 
 * BR supports backing up and restoring statistics [#48008](https://github.com/pingcap/tidb/issues/48008) @[Leavrth](https://github.com/Leavrth)
 

diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md
@@ -71,7 +71,7 @@ The `ADMIN SHOW DDL JOBS` statement is used to view all the results in the curre
     - `add index /* txn-merge */`: transactional backfilling with a temporary index that gets merged with the original index when the backfilling is finished.
 - `SCHEMA_STATE`: the current state of the schema object that the DDL operates on. If `JOB_TYPE` is `ADD INDEX`, it is the state of the index; if `JOB_TYPE` is `ADD COLUMN`, it is the state of the column; if `JOB_TYPE` is `CREATE TABLE`, it is the state of the table. Common states include the following:
     - `none`: indicates that it does not exist. Generally, after the `DROP` operation or after the `CREATE` operation fails and rolls back, it will become the `none` state.
-    - `delete only`, `write only`, `delete reorganization`, `write reorganization`: these four states are intermediate states. For their specific meanings, see [How the Online DDL Asynchronous Change Works in TiDB](/ddl-introduction.md#how-the-online-ddl-asynchronous-change-works-in-tidb). As the intermediate state conversion is fast, these states are generally not visible during operation. Only when performing `ADD INDEX` operation can the `write reorganization` state be seen, indicating that index data is being added.
+    - `delete only`, `write only`, `delete reorganization`, `write reorganization`: these four states are intermediate states. For their specific meanings, see [How the Online DDL Asynchronous Change Works in TiDB](/best-practices/ddl-introduction.md#how-the-online-ddl-asynchronous-change-works-in-tidb). As the intermediate state conversion is fast, these states are generally not visible during operation. Only when performing `ADD INDEX` operation can the `write reorganization` state be seen, indicating that index data is being added.
     - `public`: indicates that it exists and is available to users. Generally, after `CREATE TABLE` and `ADD INDEX` (or `ADD COLUMN`) operations are completed, it will become the `public` state, indicating that the newly created table, column, and index can be read and written normally.
 - `SCHEMA_ID`: the ID of the database where the DDL operation is performed.
 - `TABLE_ID`: the ID of the table where the DDL operation is performed.
@@ -239,7 +239,7 @@ This statement is a TiDB extension to MySQL syntax.
 
 ## See also
 
-* [DDL introduction](/ddl-introduction.md)
+* [DDL introduction](/best-practices/ddl-introduction.md)
 * [ADMIN CANCEL DDL](/sql-statements/sql-statement-admin-cancel-ddl.md)
 * [ADMIN PAUSE DDL](/sql-statements/sql-statement-admin-pause-ddl.md)
 * [ADMIN RESUME DDL](/sql-statements/sql-statement-admin-resume-ddl.md)

diff --git a/telemetry.md b/telemetry.md
@@ -16,7 +16,7 @@ When the telemetry feature is enabled, TiUP and TiSpark collect usage informatio
 
 ## What is shared when telemetry is enabled?
 
-The following sections describe the shared usage information in detail for TiUP and TiSpark. The usage details that get shared might change over time. These changes (if any) will be announced in [release notes](/releases/release-notes.md).
+The following sections describe the shared usage information in detail for TiUP and TiSpark. The usage details that get shared might change over time. These changes (if any) will be announced in [release notes](https://docs.pingcap.com/releases/tidb-self-managed/).
 
 > **Note:**
 >

diff --git a/tidb-distributed-execution-framework.md b/tidb-distributed-execution-framework.md
@@ -121,7 +121,7 @@ As shown in the preceding diagram, the execution of tasks in the DXF is mainly h
 
 <CustomContent platform="tidb">
 
-* [Execution Principles and Best Practices of DDL Statements](/ddl-introduction.md)
+* [Execution Principles and Best Practices of DDL Statements](/best-practices/ddl-introduction.md)
 
 </CustomContent>
 <CustomContent platform="tidb-cloud">

diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md
@@ -63,7 +63,7 @@ This document is targeted for the following upgrade paths:
     4. Upgrade the cluster to v8.1.2 according to this document.
 - Support upgrading the versions of TiDB Binlog, TiCDC, TiFlash, and other components.
 - When upgrading TiFlash from versions earlier than v6.3.0 to v6.3.0 and later versions, note that the CPU must support the AVX2 instruction set under the Linux AMD64 architecture and the ARMv8 instruction set architecture under the Linux ARM64 architecture. For details, see the description in [v6.3.0 Release Notes](/releases/release-6.3.0.md#others).
-- For detailed compatibility changes of different versions, see the [Release Notes](/releases/release-notes.md) of each version. Modify your cluster configuration according to the "Compatibility Changes" section of the corresponding release notes.
+- For detailed compatibility changes of different versions, see the [Release Notes](https://docs.pingcap.com/releases/tidb-self-managed/) of each version. Modify your cluster configuration according to the "Compatibility Changes" section of the corresponding release notes.
 - When updating clusters from versions earlier than v5.3 to v5.3 or later versions, note that there is a time format change in the alerts generated by the default deployed Prometheus. This format change is introduced starting from Prometheus v2.27.1. For more information, see [Prometheus commit](https://github.com/prometheus/prometheus/commit/7646cbca328278585be15fa615e22f2a50b47d06).
 
 ## Preparations
@@ -74,7 +74,7 @@ This section introduces the preparation works needed before upgrading your TiDB
 
 Review compatibility changes in TiDB release notes. If any changes affect your upgrade, take actions accordingly.
 
-The following provides compatibility changes you need to know when you upgrade from v8.0.0 to the current version (v8.1.2). If you are upgrading from v7.6.0 or earlier versions to the current version, you might also need to check the compatibility changes introduced in intermediate versions in the corresponding [release notes](/releases/release-notes.md).
+The following provides compatibility changes you need to know when you upgrade from v8.0.0 to the current version (v8.1.2). If you are upgrading from v7.6.0 or earlier versions to the current version, you might also need to check the compatibility changes introduced in intermediate versions in the corresponding [release notes](https://docs.pingcap.com/releases/tidb-self-managed/).
 
 - TiDB v8.1.0 [compatibility changes](/releases/release-8.1.0.md#compatibility-changes)
 - TiDB v8.1.1 [compatibility changes](/releases/release-8.1.1.md#compatibility-changes)
@@ -330,7 +330,7 @@ Re-execute the `tiup cluster upgrade` command to resume the upgrade. The upgrade
 
 ### How to fix the issue that the upgrade gets stuck when upgrading to v6.2.0 or later versions?
 
-Starting from v6.2.0, TiDB enables the [concurrent DDL framework](/ddl-introduction.md#how-the-online-ddl-asynchronous-change-works-in-tidb) by default to execute concurrent DDLs. This framework changes the DDL job storage from a KV queue to a table queue. This change might cause the upgrade to get stuck in some scenarios. The following are some scenarios that might trigger this issue and the corresponding solutions:
+Starting from v6.2.0, TiDB enables the [concurrent DDL framework](/best-practices/ddl-introduction.md#how-the-online-ddl-asynchronous-change-works-in-tidb) by default to execute concurrent DDLs. This framework changes the DDL job storage from a KV queue to a table queue. This change might cause the upgrade to get stuck in some scenarios. The following are some scenarios that might trigger this issue and the corresponding solutions:
 
 - Upgrade gets stuck due to plugin loading