Skip to content

docs: add tidb_dml_max_execution_time system variable- #21929 #23825

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gengliqi wants to merge 2 commits into
base: master
Choose a base branch
from
+32 −0
Open

docs: add tidb_dml_max_execution_time system variable- #21929 #23825

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7d6b7f6
u
gengliqi Sep 10, 2026
e9f3899
add 8.5.9
gengliqi Sep 10, 2026
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
2 changes: 2 additions & 0 deletions develop/dev-guide-timeouts-in-tidb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,8 @@ SQL statements such as `INSERT INTO t10 SELECT * FROM t1` are not affected by GC

TiDB also provides a system variable (`max_execution_time`, `0` by default, indicating no limit) to limit the execution time of a single SQL statement. Currently, the system variable only takes effect for `SELECT` statements (including `SELECT ... FOR UPDATE`). The unit of `max_execution_time` is `ms`, but the actual precision is at the `100ms` level instead of the millisecond level.

Starting from v8.5.9 and v9.0.0, to limit the execution time of transactional `INSERT`, `REPLACE`, `UPDATE`, and `DELETE` statements, and `COMMIT` statements, use [`tidb_dml_max_execution_time`](/system-variables.md#tidb_dml_max_execution_time-new-in-v859-and-v900). Its default value is `0` (no limit), and its unit is milliseconds. For autocommit DML, the limit includes the commit phase. The limit does not apply to non-transactional DML, Pipelined DML, or certain batch operations. For the complete scope and limitations, see the variable description.

## JDBC query timeout

Starting from v6.1.0, when the [`enable-global-kill`](/tidb-configuration-file.md#enable-global-kill-new-in-v610) configuration item is set to its default value `true`, you can use the `setQueryTimeout()` method provided by MySQL JDBC to control the query timeout.
Expand Down
7 changes: 7 additions & 0 deletions system-variable-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1344,6 +1344,13 @@ Referenced in:
- [TiDB 5.0 Release Notes](/releases/release-5.0.0.md)
- [TiDB 4.0 Beta Release Notes](/releases/release-4.0.0-beta.md)

### tidb_dml_max_execution_time

Referenced in:

- [System Variables](/system-variables.md#tidb_dml_max_execution_time-new-in-v859-and-v900)
- [Timeouts in TiDB](/develop/dev-guide-timeouts-in-tidb.md)

### tidb_dml_type

Referenced in:
Expand Down
23 changes: 23 additions & 0 deletions system-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1945,6 +1945,29 @@ Assume that you have a cluster with 4 TiDB nodes and multiple TiKV nodes. In thi
>
> Starting from v7.0.0, `tidb_dml_batch_size` no longer takes effect on the [`LOAD DATA` statement](/sql-statements/sql-statement-load-data.md).

### tidb_dml_max_execution_time <span class="version-mark">New in v8.5.9 and v9.0.0</span>

- Scope: SESSION | GLOBAL
- Persists to cluster: Yes
- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): Yes
- Type: Integer
- Default value: `0`
- Range: `[0, 2147483647]`
- Unit: Milliseconds
- This variable limits the maximum execution time of transactional `INSERT`, `REPLACE`, `UPDATE`, and `DELETE` statements, and `COMMIT` statements. The default value `0` means no limit from this variable.
- For an autocommit DML statement, the limit includes the time spent committing the transaction. In an explicit transaction, the limit applies separately to each DML statement and to `COMMIT`, rather than to the total duration of the transaction.
- This variable does not apply to the following operations:
- [Non-transactional DML statements](/non-transactional-dml.md).
- DML statements executed using the deprecated batch-dml feature, or DML and `COMMIT` statements when [`tidb_batch_commit`](#tidb_batch_commit) is enabled.
- Statements executed using [Pipelined DML](/pipelined-dml.md). If `tidb_dml_type = 'bulk'` is set but the statement falls back to ordinary DML execution, this variable still applies.
- `EXPLAIN ANALYZE` statements and statement types other than those listed above, such as `LOAD DATA` and `IMPORT INTO`.
- To limit the execution time of `SELECT` statements, use [`max_execution_time`](#max_execution_time) or the [`MAX_EXECUTION_TIME`](/optimizer-hints.md#max_execution_timen) hint. These settings do not override `tidb_dml_max_execution_time` for DML statements.

> **Note:**
>
> - The precision of timeout detection is roughly 100ms. A statement might not be terminated at the exact time specified by this variable.
> - Set a value that allows sufficient time for normal DML execution. After TiDB interrupts a statement, requests already sent to TiKV might continue running. An excessively short timeout combined with frequent application retries might increase cluster load.

### tidb_dml_type <span class="version-mark">New in v8.0.0</span>

> **Warning:**
Expand Down