Handle DDL exceptions for PolarDB-X 1.0 - PolarDB

PolarDB-X 1.0 distributes data definition language (DDL) operations across all table shardings for parallel execution. When a DDL command fails or stalls, use this guide to diagnose the cause and restore schema consistency.

How DDL works in PolarDB-X 1.0

Each DDL command fans out to all database shardings simultaneously. This parallel model has one important property:

A failure in one sharding does not affect the others. Each sharding executes independently.

Because failed DDL operations can be retried, and errors on shardings that already completed the operation do not affect other shardings, you only need to ensure that all table shardings ultimately share the same schema.

Use the CHECK TABLE command to verify that all shardings share the same schema after any DDL issue.

DDL failure types

DDL failures fall into two categories:

Execution errors — The DDL statement fails on one or more database shardings. Common causes include conflicts (the table or column already exists) and insufficient disk space. This may leave table sharding schemas in an inconsistent state.

Long-running operations — The DDL statement runs for an unusually long time with no response. This happens when a sharding takes a long time to complete the operation, which is typical for Copy Table operations on large tables.

Determine whether a DDL operation is fast or slow

MySQL executes DDL in two modes:

In-Place — Modifies metadata directly. Fast, with no data copied.
Copy Table — Reconstructs the entire table, including all data rows, logs, and buffer operations. Slow on large tables.

Check the rows affected value after a DDL operation completes to identify which mode was used:

Example operation	Output	Mode
Change column default value	`Query OK, 0 rows affected (0.07 sec)`	In-Place
Add an index	`Query OK, 0 rows affected (21.42 sec)`	In-Place
Change column data type	`Query OK, 1671168 rows affected (1 min 35.54 sec)`	Copy Table

For a complete reference of which operations use In-Place versus Copy Table, see Online DDL Operations in the MySQL documentation.

Test before running DDL on large tables:

Clone the table schema to generate a test table.
Insert representative data.
Run the DDL operation on the cloned table.
Check the rows affected value. A non-zero value means the operation will reconstruct the entire table — schedule it during off-peak hours.

Diagnose and recover from DDL failures

Use this decision flow to handle DDL failures:

Run CHECK TABLE
   |
Schema consistent? --> Yes --> Run SHOW CREATE TABLE
                                 |
                        Schema as expected? --> Yes --> Done (DDL succeeded)
                                             |
                                             No
                                             |
                          <-- <-- <-- <-- <--+
   |
   No
Run SHOW PROCESSLIST
   |
DDL still running? --> Yes --> Wait for completion --> Return to CHECK TABLE
   |
   No
Retry DDL
   |
Lock conflict error? --> Yes --> Run RELEASE DBLOCK --> Retry DDL
   |
   No
Return to SHOW PROCESSLIST

Step 1: Check schema consistency

Run CHECK TABLE to verify all table shardings share the same schema:

mysql> check table `xxxx`;

Note If CHECK TABLE returns no output in Data Management Service (DMS), run it from the command line instead.

A consistent schema returns a single row with OK status:

+----------------------------+-------+----------+----------+
| TABLE                      | OP    | MSG_TYPE | MSG_TEXT |
+----------------------------+-------+----------+----------+
| TDDL5_APP.xxxx             | check | status   | OK       |
+----------------------------+-------+----------+----------+
1 row in set (0.05 sec)

If the result contains more than one row or the status is not OK, the shardings have inconsistent schemas. Continue to step 2.

Step 2: Verify the schema content

Run SHOW CREATE TABLE to check the actual schema:

mysql> show create table `xxxx`;

Example output:

+---------+------------------------------------------------------------------------------------------------------------------+
| Table   | Create Table                                                                                                     |
+---------+------------------------------------------------------------------------------------------------------------------+
|  xxxx   | CREATE TABLE `xxxx` (
`id` int(11) NOT NULL DEFAULT '0',
`NAME` varchar(1024) NOT NULL DEFAULT '',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 dbpartition by hash(`id`) tbpartition by hash(`id`) tbpartitions 3                      |
+---------+------------------------------------------------------------------------------------------------------------------+
1 row in set (0.05 sec)

If the schema matches what you expect after the DDL operation, the DDL completed successfully. If not, continue to step 3.

Step 3: Check for running DDL operations

Some DDL operations run slowly and do not produce immediate output. Run SHOW PROCESSLIST to see all active SQL statements:

mysql> SHOW PROCESSLIST WHERE COMMAND != 'Sleep';

Example output:

+---------------+-----------+--------------------+-------------+---------+-----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+-----------+---------------+-----------+
| ID            | USER      | DB                 | COMMAND     | TIME    | STATE                                                                 | INFO                                                                                                 | ROWS_SENT | ROWS_EXAMINED | ROWS_READ |
+---------------+-----------+--------------------+-------------+---------+-----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+-----------+---------------+-----------+
| 0-0-352724126 | ifisibhk0 | test_123_wvvp_0000 | Query       |      15 | Sending data                                                          | /*DRDS /42.120.74.88/ac47e5a72801000/ */select `t_item`.`detail_url`,SUM(`t_item`.`price`) from `t_i |      NULL |          NULL |      NULL |
| 0-0-352864311 | cowxhthg0 | NULL               | Binlog Dump |      13 | Master has sent all binlog to slave; waiting for binlog to be updated | NULL                                                                                                 |      NULL |          NULL |      NULL |
| 0-0-402714566 | ifisibhk0 | test_123_wvvp_0005 | Query       |      14 | Sending data                                                          | /*DRDS /42.120.74.88/ac47e5a72801000/ */select `t_item`.`detail_url`,`t_item`.`price` from `t_i      |      NULL |          NULL |      NULL |
| 0-0-402714795 | ifisibhk0 | test_123_wvvp_0005 | Alter       |     114 | Sending data                                                          | /*DRDS /42.120.74.88/ac47e5a72801000/ */ALTER TABLE `Persons` ADD `Birthday` date                    |      NULL |          NULL |      NULL |
......
+---------------+-----------+--------------------+-------------+---------+-----------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+-----------+---------------+-----------+
12 rows in set (0.03 sec)

Key columns for DDL troubleshooting:

Column	What to look for
`ID`	The command ID — use this to cancel a specific operation
`TIME`	Seconds the command has been running — large values indicate a slow operation
`INFO`	The full SQL statement — use this to identify which logical DDL a sharding command belongs to

If you find a DDL operation that has been running too long, cancel it with:

KILL '0-0-402714795';

Note

One logical DDL statement in PolarDB-X 1.0 maps to multiple database sharding commands. To stop a logical DDL operation, you may need to cancel multiple commands. Use the INFO column to identify which commands belong to the same logical statement.

After canceling, return to step 1 to check schema consistency.

Step 4: Retry the DDL operation

If no DDL is running and the schema is still inconsistent, retry the DDL operation on PolarDB-X 1.0. Errors reported on shardings where the operation already completed successfully do not affect the re-execution on other shardings.

If the retry succeeds, return to step 1 to verify consistency.

If you see a Lock conflict error, continue to step 5.

Step 5: Release the DDL lock

What causes a lock conflict

PolarDB-X 1.0 acquires a DDL lock before executing any DDL operation and releases it when the operation completes. If you cancel a DDL operation with KILL before it finishes, the lock may not be released automatically. Any subsequent DDL attempt on the same table will fail with:

Lock conflict , maybe last DDL is still running

Release the lock

Run the following command to release the DDL lock:

RELEASE DBLOCK;

After releasing the lock, retry the DDL operation (step 4). To minimize risk, run the DDL during off-peak hours or when the service is stopped.

FAQ

Why does DMS or another client not show the updated schema?

PolarDB-X 1.0 maintains a shadow database in RDS at database sharding 0. The shadow database has the same name as the PolarDB-X 1.0 logical database and stores all logical database metadata, including schemas. Clients like DMS read the schema from this shadow database rather than directly from the shardings.

If the DDL operation updated the sharding schemas but not the shadow database, clients will display the old schema. To fix this, connect to the shadow database directly and run the same DDL operation on the table.

Note CHECK TABLE does not verify whether the shadow database schema is consistent with the PolarDB-X 1.0 logical database schema. If DMS shows an unexpected schema after CHECK TABLE returns OK, the shadow database is likely out of sync.

How do I handle DDL error codes like TDDL-4500 ERR_PARSER?

See Error codes for a full list of PolarDB-X 1.0 error codes and their solutions.