*: remove alter-primary-key configuration

auto-random.md

@@ -142,7 +142,7 @@ This attribute supports forward compatibility, namely, downgrade compatibility.
 
 Pay attention to the following restrictions when you use `AUTO_RANDOM`:
 
-- Specify this attribute for the primary key column **ONLY** of integer type. Otherwise, an error might occur. In addition, when the value of `alter-primary-key` is `true`, `AUTO_RANDOM` is not supported even on the integer primary key.
+- Specify this attribute for the primary key column **ONLY** of integer type. Otherwise, an error might occur. In addition, when the attribute of the primary key is `NONCLUSTERED`, `AUTO_RANDOM` is not supported even on the integer primary key. For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
 - You cannot use `ALTER TABLE` to modify the `AUTO_RANDOM` attribute, including adding or removing this attribute.
 - You cannot change the column type of the primary key column that is specified with `AUTO_RANDOM` attribute.
 - You cannot specify `AUTO_RANDOM` and `AUTO_INCREMENT` for the same column at the same time.

constraints.md

@@ -245,9 +245,31 @@ Query OK, 0 rows affected (0.10 sec)
 * Table `t3` failed to be created, because a table can only have one primary key.
 * Table `t4` was created successfully, because even though there can be only one primary key, TiDB supports defining multiple columns as the composite primary key.
 
-In addition to the rules above, by default, TiDB has an additional restriction that once a table is successfully created, its primary key cannot be changed. If you need to add/remove the primary key, you need to set  `alter-primary-key`  to  `true`  in the TiDB configuration file, and restart the TiDB instance to make it effective.
+In addition to the rules above, TiDB currently only supports adding and deleting the primary keys of the `NONCLUSTERED` type. For example:
 
-When the add/delete primary key feature is enabled, TiDB allows adding/deleting primary key to the table. However, it should be noted that, if a table with an integer type primary key has been created before the feature is enabled, you cannot delete its primary key constraint even when you enable the add/delete primary key feature.
+{{< copyable "sql" >}}
+
+```sql
+CREATE TABLE t5 (a INT NOT NULL, b INT NOT NULL, PRIMARY KEY (a,b) CLUSTERED);
+ALTER TABLE t5 DROP PRIMARY KEY;
+```
+
+```
+ERROR 8200 (HY000): Unsupported drop primary key when the table is using clustered index
+```
+
+{{< copyable "sql" >}}
+
+```sql
+CREATE TABLE t5 (a INT NOT NULL, b INT NOT NULL, PRIMARY KEY (a,b) NONCLUSTERED);
+ALTER TABLE t5 DROP PRIMARY KEY;
+```
+
+```
+Query OK, 0 rows affected (0.10 sec)
+```
+
+For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
 
 ## FOREIGN KEY
 

dynamic-config.md

@@ -33,7 +33,6 @@ show config;
 | Type | Instance        | Name                                                      | Value                                                                                                                                                                                                                                                                            |
 +------+-----------------+-----------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | tidb | 127.0.0.1:4001  | advertise-address                                         | 127.0.0.1                                                                                                                                                                                                                                                                        |
-| tidb | 127.0.0.1:4001  | alter-primary-key                                         | false                                                                                                                                                                                                                                                                            |
 | tidb | 127.0.0.1:4001  | binlog.binlog-socket                                      |                                                                                                                                                                                                                                                                                  |
 | tidb | 127.0.0.1:4001  | binlog.enable                                             | false                                                                                                                                                                                                                                                                            |
 | tidb | 127.0.0.1:4001  | binlog.ignore-error                                       | false                                                                                                                                                                                                                                                                            |

mysql-compatibility.md

@@ -93,7 +93,7 @@ In TiDB, all supported DDL changes are performed online. Compared with DDL opera
 
 * Multiple operations cannot be completed in a single `ALTER TABLE` statement. For example, it is not possible to add multiple columns or indexes in a single statement. Otherwise, the `Unsupported multi schema change` error might be output.
 * Different types of indexes (`HASH|BTREE|RTREE|FULLTEXT`) are not supported, and will be parsed and ignored when specified.
-* Adding/Dropping the primary key is unsupported unless [`alter-primary-key`](/tidb-configuration-file.md#alter-primary-key) is enabled.
+* Adding/Dropping the primary key of the `CLUSTERED` type is unsupported. For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
 * Changing the field type to its superset is unsupported. For example, TiDB does not support changing the field type from `INTEGER` to `VARCHAR`, or from `TIMESTAMP` to `DATETIME`. Otherwise, the error information `Unsupported modify column: type %d not match origin %d` might be output.
 * Change/Modify data type does not currently support "lossy changes", such as changing from BIGINT to INT.
 * Change/Modify decimal columns does not support changing the precision.

sql-statements/sql-statement-add-index.md

@@ -124,7 +124,7 @@ mysql> EXPLAIN SELECT * FROM t1 WHERE c1 = 3;
 * `VISIBLE/INVISIBLE` index is not supported (currently only the master branch actually supports this feature).
 * Descending indexes are not supported (similar to MySQL 5.7).
 * Adding multiple indexes at the same time is currently not supported.
-* Adding the primary key constraint to a table is not supported by default. You can enable the feature by setting the `alter-primary-key` configuration item to `true`. For details, see [alter-primary-key](/tidb-configuration-file.md#alter-primary-key).
+* Adding the primary key of the `CLUSTERED` type to a table is not supported. For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
 
 ## See also
 

sql-statements/sql-statement-create-index.md

@@ -168,7 +168,7 @@ The global variables associated with the `CREATE INDEX` statement are `tidb_ddl_
 
 * `FULLTEXT`, `HASH` and `SPATIAL` indexes are not supported.
 * Descending indexes are not supported (similar to MySQL 5.7).
-* Adding the primary key constraint to a table is not supported by default. You can enable the feature by setting the `alter-primary-key` configuration item to `true`. For details, see [alter-primary-key](/tidb-configuration-file.md#alter-primary-key).
+* Adding the primary key of the `CLUSTERED` type to a table is not supported. For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
 
 ## See also
 

sql-statements/sql-statement-drop-index.md

@@ -72,7 +72,7 @@ Query OK, 0 rows affected (0.30 sec)
 
 ## MySQL compatibility
 
-* Removing the primary key constraint from a column is not supported by default. You can enable the feature by setting the `alter-primary-key` configuration item to `true`. For details, see [alter-primary-key](/tidb-configuration-file.md#alter-primary-key).
+* Dropping the primary key of the `CLUSTERED` type is not supported. For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
 
 ## See also
 

sql-statements/sql-statement-show-config.md

@@ -37,7 +37,6 @@ SHOW CONFIG;
 | Type | Instance       | Name                                            | Value                                                               |
 +------+----------------+-------------------------------------------------+---------------------------------------------------------------------+
 | tidb | 127.0.0.1:4000 | advertise-address                               | 127.0.0.1                                                           |
-| tidb | 127.0.0.1:4000 | alter-primary-key                               | false                                                               |
 | tidb | 127.0.0.1:4000 | binlog.binlog-socket                            |                                                                     |
 | tidb | 127.0.0.1:4000 | binlog.enable                                   | false                                                               |
 ...
@@ -74,7 +73,6 @@ SHOW CONFIG LIKE 'tidb';
 | Type | Instance       | Name                                            | Value                                                               |
 +------+----------------+-------------------------------------------------+---------------------------------------------------------------------+
 | tidb | 127.0.0.1:4000 | advertise-address                               | 127.0.0.1                                                           |
-| tidb | 127.0.0.1:4000 | alter-primary-key                               | false                                                               |
 | tidb | 127.0.0.1:4000 | binlog.binlog-socket                            |                                                                     |
 | tidb | 127.0.0.1:4000 | binlog.enable                                   | false                                                               |
 ...

tidb-configuration-file.md

@@ -88,12 +88,16 @@ The TiDB configuration file supports more options than command-line parameters.
 - Determines whether to treat the `utf8` character set in old tables as `utf8mb4`.
 - Default value: `true`
 
-### `alter-primary-key`
+### `alter-primary-key` (Deprecated)
 
 - Determines whether to add or remove the primary key constraint to or from a column.
 - Default value: `false`
 - With this default setting, adding or removing the primary key constraint is not supported. You can enable this feature by setting `alter-primary-key` to `true`. However, if a table already exists before the switch is on, and the data type of its primary key column is an integer, dropping the primary key from the column is not possible even if you set this configuration item to `true`.
 
+> **Note:**
+>
+> This configuration item has been deprecated, and currently only takes effect when the value of `@tidb_enable_clustered_index` is `INT_ONLY`.If you need to add or remove the primary key, use the `NONCLUSTERED` keyword instead when creating the table. For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
+
 ### `server-version`
 
 + Modifies the version string returned by TiDB in the following situations:

troubleshoot-hot-spot-issues.md

@@ -106,7 +106,7 @@ ALTER TABLE：ALTER TABLE t SHARD_ROW_ID_BITS = 4;
 
 The value of `SHARD_ROW_ID_BITS` can be dynamically modified. The modified value only takes effect for newly written data.
 
-When TiDB's `alter-primary-key` parameter is set to false, the table's integer primary key is used as the RowID. At this time, the `SHARD_ROW_ID_BITS` option can not be used because it changes the RowID generation rules. If the `alter-primary-key` parameter is set to true, TiDB no longer uses the integer primary key as the RowID when creating a table, and the table with the integer primary key can also use the `SHARD_ROW_ID_BITS` feature.
+For the table with a primary key of the `CLUSTERED` type, TiDB uses the primary key of the table as the RowID. At this time, the `SHARD_ROW_ID_BITS` option cannot be used because it changes the RowID generation rules. For the table with the primary key of the `NONCLUSTERED` type, TiDB uses an automatically allocated 64-bit integer as the RowID. In this case, you can use the `SHARD_ROW_ID_BITS` feature. For more details about the primary key of the `CLUSTERED` type, refer to [clustered index](/clustered-indexes.md).
 
 The following two load diagrams shows the case where two tables without primary keys use `SHARD_ROW_ID_BITS` to scatter hotspots. The first diagram shows the situation before scattering hotspots, while the second one shows the situation after scattering hotspots.