Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 22 additions & 6 deletions sql-statements/sql-statement-modify-column.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,29 @@

# MODIFY COLUMN

The `ALTER TABLE.. MODIFY COLUMN` statement modifies a column on an existing table. The modification can include changing the data type and attributes. To rename at the same time, use the [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md) statement instead.
The `ALTER TABLE ... MODIFY COLUMN` statement modifies a column on an existing table. The modification can include changing the data type and attributes. To rename the column at the same time, use the [`CHANGE COLUMN`](/sql-statements/sql-statement-change-column.md) statement instead.

Since v5.1.0, TiDB has supported changes of data types for Reorg data, including but not limited to:
Starting from v5.1.0, TiDB supports column type changes that require Reorg-Data. When performing such changes, TiDB rebuilds all existing data in the table by reading the original data, converting it to the new column type, and then writing the converted data back to the table. Because all table data must be processed, Reorg-Data operations typically take a long time, and the execution time is proportional to the amount of data in the table.

The following are some common examples of column type changes that require Reorg-Data:

- Changing `VARCHAR` to `BIGINT`
- Modifying the `DECIMAL` precision
- Compressing the length of `VARCHAR(10)` to `VARCHAR(5)`
- Reducing the length of `VARCHAR(10)` to `VARCHAR(5)`

Starting from v8.5.5 and v9.0.0, TiDB optimizes some column type changes that previously required Reorg-Data. When the following conditions are met, TiDB no longer rebuilds the table data; instead, it rebuilds only the affected indexes, thereby improving execution efficiency:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Starting from v8.5.5 and v9.0.0, TiDB optimizes some column type changes that previously required Reorg-Data. When the following conditions are met, TiDB no longer rebuilds the table data; instead, it rebuilds only the affected indexes, thereby improving execution efficiency:
Starting from v8.5.5 and v9.0.0, TiDB optimizes some column type changes that previously required Reorg-Data. When the following conditions are met, TiDB rebuilds only the affected indexes instead of the entire table, thereby improving execution efficiency:


- The current session uses a strict [SQL mode](/sql-mode.md) (`sql_mode` includes `STRICT_TRANS_TABLES` or `STRICT_ALL_TABLES`).
- There is no risk of data truncation during type conversion.

This optimization applies to the following type change scenarios:

- Conversions between integer types, such as from `BIGINT` to `INT`
- Conversions between string types, such as from `VARCHAR(200)` to `VARCHAR(100)`

> **Note:**
>
> When converting from `VARCHAR` to `CHAR`, the original data must not contain trailing spaces. If the original data contains trailing spaces, TiDB still performs Reorg-Data to ensure that the converted data complies with the padding rules of the `CHAR` type.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> When converting from `VARCHAR` to `CHAR`, the original data must not contain trailing spaces. If the original data contains trailing spaces, TiDB still performs Reorg-Data to ensure that the converted data complies with the padding rules of the `CHAR` type.
> When converting from `VARCHAR` to `CHAR`, the original data must not contain trailing spaces. If the original data contains trailing spaces, TiDB still performs Reorg-Data to ensure that the converted values comply with the padding rules of the `CHAR` type.

## Synopsis

Expand Down Expand Up @@ -59,7 +75,7 @@

## Examples

### Meta-Only Change
### Meta-only change

{{< copyable "sql" >}}

Expand Down Expand Up @@ -109,7 +125,7 @@
1 row in set (0.00 sec)
```

### Reorg-Data Change
### Reorg-Data change

{{< copyable "sql" >}}

Expand Down Expand Up @@ -168,7 +184,7 @@
> ERROR 1406 (22001): Data Too Long, field len 4, data len 5
> ```
>
> - Due to the compatibility with the Async Commit feature, the DDL statement waits for a period of time (about 2.5s) before starting to process into Reorg Data.
> - Due to the compatibility with the Async Commit feature, when [Metadata lock](/metadata-lock.md) is disabled, the DDL statement waits for a period of time (about 2.5s) before starting to process into Reorg-Data.

Check failure on line 187 in sql-statements/sql-statement-modify-column.md

View workflow job for this annotation

GitHub Actions / vale

[vale] reported by reviewdog 🐶 [PingCAP.Units] Put a nonbreaking space between the number and the unit in '5s'. Raw Output: {"message": "[PingCAP.Units] Put a nonbreaking space between the number and the unit in '5s'.", "location": {"path": "sql-statements/sql-statement-modify-column.md", "range": {"start": {"line": 187, "column": 168}}}, "severity": "ERROR"}
>
> ```
> Query OK, 0 rows affected (2.52 sec)
Expand Down