PolarDB:Considerations and limits

Completed DDL tasks are automatically deleted from the task queue. Once a DDL statement finishes executing, ignore the task status — the task is gone.

After a DDL task completes, run CHECK TABLE immediately to verify that the corresponding logical tables are consistent.

After you resume, roll back, or delete a DDL task using a task management statement, run CHECK TABLE to verify logical table consistency.

If a DDL statement fails, an error code and error message are returned. Run SHOW DDL to see the failure cause in the REMARK field of the pending task.

If a DDL task fails and enters the pending state, the affected table becomes inaccessible for security reasons. Statements such as SHOW TABLES return no results, and DML statements may return errors like the table is unknown or does not exist. The table becomes accessible again only after the pending DDL task is resumed or rolled back, which restores it to a consistent state.

If you use IF NOT EXISTS in a CREATE TABLE statement or IF EXISTS in a DROP TABLE statement, some errors during execution do not cause the statement to fail — instead, they are recorded as warnings. After executing such a statement, check whether the output includes a warning count (for example, 1 warning). Run SHOW WARNINGS to review the details and avoid missing important information.

On clients such as Data Management (DMS), set PURE_ASYNC_DDL_MODE to run DDL statements asynchronously. This prevents client-side timeout from interrupting long-running DDL operations. Use this when the execution time of a DDL statement cannot be estimated and the client has a connection timeout configured for PolarDB-X 1.0. After the statement is submitted, run SHOW DDL to check the task status.

Only CREATE TABLE and RENAME TABLE operations can be rolled back.

RECOVER DDL and ROLLBACK DDL cannot be combined or repeated for the same pending DDL task. For example, rolling back a task with ROLLBACK DDL and then attempting RECOVER DDL after the rollback fails may cause logical table inconsistency. If your scenario requires combining these operations, contact technical support.

Run REMOVE DDL only when the database security is ensured. Running REMOVE DDL on a database in an uncertain state may expose DDL task intermediate states and leave logical tables inconsistent. If data integrity issues occur due to misuse of REMOVE DDL, contact technical support.

By default, each physical database supports a maximum of 128 table shards. Exceeding this limit returns an error:

mysql> CREATE TABLE test_mdb_mtb (c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY, c2 VARCHAR(10), c3 DATE)
    ->   DBPARTITION BY HASH(c1) TBPARTITION BY HASH(c1) TBPARTITIONS 129;
ERROR 4647 (HY000): [f5bd90594800000][30.25.86.55:8527][JICHEN_LOCAL_APP]ERR-CODE: [TDDL-4647][ERR_TABLE_PARTITIONS_EXCEED_LIMIT] The number of table partitions '129' exceeds the upper limit '128'. Please specify less table partitions or adjust the value of the parameter MAX_TABLE_PARTITIONS_PER_DB.

To increase the limit, pass MAX_TABLE_PARTITIONS_PER_DB as a hint:

mysql> /*+TDDL:cmd_extra(MAX_TABLE_PARTITIONS_PER_DB=400)*/CREATE TABLE test_mdb_mtb (c1 INT NOT NULL AUTO_INCREMENT PRIMARY KEY, c2 VARCHAR(10), c3 DATE)
    ->   DBPARTITION BY HASH(c1) TBPARTITION BY HASH(c1) TBPARTITIONS 129;
Query OK, 0 rows affected (2.64 sec)

The DDL execution engine task queue holds a maximum of 65,535 pending DDL tasks. If this limit is reached, no new DDL statements can be executed. To free up space, first list pending tasks to identify the ones to remove, then remove them:

SHOW DDL;

REMOVE DDL <task_id>;

This limit cannot be changed by modifying parameters.