tencent cloud

Non-blocking DDL
Last updated:2026-03-26 15:21:26
Non-blocking DDL
Last updated: 2026-03-26 15:21:26

Feature Overview

TDSQL Boundless provides the non-blocking DDL feature to resolve the issue where DDL operations, while waiting for MDL exclusive locks, block all new transactions on the target table, leading to accumulation of business connections or even system crashes.
After non-blocking DDL is enabled, when a DDL operation cannot immediately acquire an MDL exclusive lock, the system temporarily releases the lock request, allowing new transactions to access the target table normally. It then retries lock acquisition with timeouts until the DDL operation ultimately completes.

Background Information

DDL-wait-induced cascading blocking of MDL locks

In TDSQL Boundless, DDL operations (such as ALTER TABLE) need to obtain the MDL exclusive lock (MDL-X) on the target table. When there are uncommitted long-running transactions or large queries on the target table, these sessions hold the MDL shared read lock on the table, and the DDL operation will enter a waiting state.
In the default mechanism, the MDL exclusive lock takes precedence. Once a DDL operation enters the waiting queue, all subsequent new transactions on the table (including regular SELECT, INSERT, and UPDATE operations) will be blocked—they can neither acquire an MDL shared lock (because a higher-priority exclusive lock request exists in the waiting queue) nor bypass the exclusive lock request to execute directly.
This chain blocking can lead to severe consequences:
1. Business connections accumulate rapidly, exhausting the database connection pool.
2. Numerous timeout errors occur at the application layer, resulting in service unavailability.
3. In severe cases, it may lead to a complete breakdown of the business system.

The solution approach for non-blocking DDL

Non-blocking DDL changes the acquisition strategy for MDL exclusive locks:
Default behavior: The DDL operation persistently waits after an exclusive lock request is submitted, blocking all new transactions during this period.
Non-blocking behavior: The DDL operation attempts to acquire the exclusive lock within a short period. If the acquisition fails, it voluntarily relinquishes the current lock request, allowing new transactions to proceed normally. After a waiting interval, it retries the acquisition. This cycle repeats until the lock is successfully acquired or the maximum number of retries is reached.
This "attempt - yield - retry" mechanism ensures that business traffic will not be continuously blocked even if the DDL operation cannot be completed immediately.

The difference from preemptive DDL

Level
Preemptive DDL
Non-blocking DDL
Problems solved
DDL execution fails due to long transaction blocking 
DDL blocks all new transactions during the waiting period 
Handling method
After timeout, terminate the session blocking DDL.
After timeout, DDL voluntarily yields, allowing new transactions to proceed.
Impact on Existing Sessions
Sessions holding locks will be forcibly terminated.
Existing sessions are not affected.
DDL Execution Result
DDL is guaranteed to succeed.
DDL may fail due to exhausted retry attempts.
Use Cases
Long transactions can be interrupted, and DDL must succeed.
Business sessions cannot be interrupted, requiring zero awareness from the business.
The two features can be used individually according to business needs or work in conjunction.

Limitations

Increased Probability of DDL Failure: After non-blocking DDL is enabled, the lock priority of DDL operations is degraded. If there are continuous active transactions on the target table, the DDL operation may fail to obtain the lock after exhausting all retry attempts, ultimately resulting in execution failure.
Prolonged DDL Execution Time: Due to the retry mechanism, the total DDL execution time = actual DDL duration + retry waiting time. In scenarios with severe lock conflicts, the DDL completion time may increase significantly.

Parameter Description

The behavior of non-blocking DDL can be controlled via the following parameters, which can be dynamically set before DDL is executed.
Parameter
Level
Description
Value Range
Default Value
tdsql_ddl_block_mode
Session
The non-blocking DDL feature switch enables non-blocking DDL logic when set to nonblock.
preemptive
nonblock
default
preemptive
tdsql_ddl_recovery_block_mode
Global
Controls the non-blocking DDL behavior of the recovery thread; takes effect when set to nonblock. Only GLOBAL-level settings are valid; Session-level settings are invalid.
preemptive
nonblock
default
preemptive
tdsql_ddl_nonblock_lock_wait_timeout
Session
The timeout duration for a single attempt to obtain an MDL-X lock. If the lock is not acquired within this duration, the DDL operation will proactively abort the current request and allow new transactions to proceed. Unit: seconds.
1 ~ 102410241024
1
tdsql_ddl_nonblock_retry_interval
Session
The wait interval between two lock acquisition attempts. Unit: seconds
0 ~ 60
4
tdsql_ddl_nonblock_retry_times
Session
The maximum number of retries to obtain an MDL-X lock. Exceeding this limit will cause the DDL operation to fail.
0 ~ ULONG_MAX
10
Relationship Among Parameters:
The maximum total wait time for DDL is approximately:
Total duration ≈ tdsql_ddl_nonblock_retry_times × (tdsql_ddl_nonblock_lock_wait_timeout + tdsql_ddl_nonblock_retry_interval)

Usage

1. Enable non-blocking DDL.
SET tdsql_ddl_block_mode = 'nonblock';
2. (Optional) Configure retry parameters.
For example, set the single lock wait to 2 seconds, the retry interval to 5 seconds, and the maximum retries to 20:
SET tdsql_ddl_nonblock_lock_wait_timeout = 2;
SET tdsql_ddl_nonblock_retry_interval = 5;
SET tdsql_ddl_nonblock_retry_times = 20;
3. (Optional) Configure recovery-thread non-blocking DDL.
SET GLOBAL tdsql_ddl_recovery_block_mode = 'nonblock';
4. Execute DDL operations.
ALTER TABLE orders ADD INDEX idx_status (status);
During DDL execution, if an MDL lock conflict is encountered, the system performs "attempt-yield-retry" cycles according to the configured parameters, while business traffic remains unaffected.

Usage Examples

The following will use an example to demonstrate the impact difference on business TPS before and after non-blocking DDL is enabled.

Preparations

CREATE TABLE sbtest1 (
id INT PRIMARY KEY,
k INT NOT NULL DEFAULT 0,
c CHAR(120) NOT NULL DEFAULT '',
pad CHAR(60) NOT NULL DEFAULT ''
);
-- Insert 1 million rows of test data (can be generated using tools such as SysBench)
Use SysBench to simulate continuous business load:
sysbench oltp_read_write \\
--mysql-host="connection address" \\
--mysql-port=3306 \\
--mysql-user="username" \\
--mysql-password="password" \\
--mysql-db="test" \\
--tables=1 \\
--table-size=1000000 \\
--threads=8 \\
--time=600 \\
--report-interval=1 \\
run

Simulate lock conflict

Session 1 (simulating an uncommitted long transaction):
BEGIN;
SELECT * FROM sbtest1 LIMIT 1;
-- Uncommitted, holding a shared read MDL lock on sbtest1

Scenario 1: Disable non-blocking DDL (default behavior)

Session 2 (executing DDL):
ALTER TABLE sbtest1 ADD COLUMN d INT;
-- DDL enters the MDL lock wait queue
-- At this point, all new transactions are also blocked → business TPS drops to zero
Manifestation: From the moment the DDL is submitted, SysBench's TPS continuously drops to zero until the long transaction ends or the DDL times out. Business is completely interrupted.

Scenario 2: Enable non-blocking DDL

Session 2 (executed after non-blocking DDL is enabled):
SET tdsql_nonblock_ddl_mode = ON;
SET tdsql_nonblock_ddl_lock_wait_timeout = 1;
SET tdsql_nonblock_ddl_retry_interval = 5;
SET tdsql_nonblock_ddl_retry_times = 50;

ALTER TABLE sbtest1 ADD COLUMN d INT;
-- DDL attempts to obtain the lock → aborts after 1 second → releases new transactions → waits 5 seconds → retries...
-- When the transaction in Session 1 ended, the DDL successfully obtained the lock on the next retry attempt
-- Query OK, 0 rows affected (23.15 sec)
Manifestation: SysBench's TPS exhibits periodic brief declines (lasting approximately 1 second each time the DDL attempts to obtain the lock), but does not drop to zero. The overall business remains available.

Results comparison

Scenario
TPS performance
Business Impacts
Disable non-blocking DDL
TPS continuously drops to zero until the lock is released.
Severe, business is completely interrupted.
Enable non-blocking DDL
TPS exhibits periodic brief declines and does not drop to zero.
Minor, business remains available.

Best Practices

Scenario 1: Urgently add an index during peak business hours

During business peak hours, there is an urgent need to add an index for slow queries, but the table has a large number of active transactions:
-- Enable non-blocking DDL to avoid impacting online business operations
SET tdsql_ddl_block_mode = 'nonblock';
SET tdsql_ddl_nonblock_lock_wait_timeout = 1;
SET tdsql_ddl_nonblock_retry_interval = 3;
SET tdsql_ddl_nonblock_retry_times = 100;

ALTER TABLE orders ADD INDEX idx_create_time (create_time);

Scenario 2: Used in conjunction with Preemptive DDL

For critical table structure changes, you can first attempt non-blocking DDL. If it cannot be completed within a prolonged period, then enable preemptive DDL for force execution:
-- First attempt: non-blocking mode, without affecting business operations
SET tdsql_ddl_block_mode = 'nonblock';
SET tdsql_ddl_nonblock_retry_times = 10;
ALTER TABLE orders ADD COLUMN remark VARCHAR(255);
-- If retry attempts are exhausted and it still fails...

-- Second attempt: preemptive mode, force completion
SET tdsql_ddl_block_mode = 'preemptive';
SET tdsql_ddl_preempt_after_wait_seconds = 5;
ALTER TABLE orders ADD COLUMN remark VARCHAR(255);
Summary:
1. Non-blocking DDL is enabled by setting tdsql_ddl_block_mode (for regular threads) / tdsql_ddl_recovery_block_mode (for recovery threads) to nonblock, with supporting parameters controlling retry policies;
2. Non-blocking DDL employs an "attempt-yield-retry" logic to avoid blocking business transactions, making it suitable for high-concurrency scenarios with stringent availability requirements.
3. It can be used in combination with preemptive DDL, prioritizing business continuity through non-blocking mode while switching to preemptive mode to forcibly complete DDL when necessary.

References

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback