From 0c161de66ab4a46eb34b921d91f6184011e8273d Mon Sep 17 00:00:00 2001 From: xhe Date: Thu, 30 Apr 2026 11:11:21 +0800 Subject: [PATCH 1/4] sysvar: add tidb_enable_strict_not_null_check Signed-off-by: xhe --- system-variables.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/system-variables.md b/system-variables.md index f030c70c3795..e60f7d453539 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2479,6 +2479,16 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - 默认值：`ON` - 这个变量用来控制是否开启 statement summary 功能。如果开启，SQL 的耗时等执行信息将被记录到系统表 `information_schema.STATEMENTS_SUMMARY` 中，用于定位和排查 SQL 性能问题。 +### `tidb_enable_strict_not_null_check` 从 v9.0.0 版本开始引入 + +- 作用域：SESSION | GLOBAL +- 是否持久化到集群：是 +- 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 +- 类型：布尔型 +- 默认值：`ON` +- 这个变量用来控制是否可以插入 `null` 到非空列，关闭时允许此类插入。该设置的目的是提供一个从 TiDB 早期版本升级的方法，因为早期版本在验证类型方面不太严格。 +- 该变量的默认值 `ON` 与 MySQL 兼容。 + ### `tidb_enable_strict_double_type_check` 从 v5.0 版本开始引入 - 作用域：SESSION | GLOBAL From 9fb7b39999970307d9d221d8d5699321df57834d Mon Sep 17 00:00:00 2001 From: xhe Date: Wed, 6 May 2026 22:09:10 +0800 Subject: [PATCH 2/4] Update system-variables.md Co-authored-by: Frank945946 <108602632+Frank945946@users.noreply.github.com> Signed-off-by: xhe --- system-variables.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/system-variables.md b/system-variables.md index e60f7d453539..be6332810ef5 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2486,8 +2486,13 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 类型：布尔型 - 默认值：`ON` -- 这个变量用来控制是否可以插入 `null` 到非空列，关闭时允许此类插入。该设置的目的是提供一个从 TiDB 早期版本升级的方法，因为早期版本在验证类型方面不太严格。 -- 该变量的默认值 `ON` 与 MySQL 兼容。 +- 该变量用于控制在向定义为 NOT NULL 的列插入 NULL 值时的校验行为。 + +MySQL 兼容性： +- ON (默认值)：与 MySQL 8.0 的标准行为保持一致。对于 NOT NULL 约束执行严格校验，插入 NULL 值将直接触发错误。 +- OFF：模拟 MySQL 5.7 及其早期版本在非严格模式下的行为。允许向非空列插入 NULL，此时系统不会报错，而是自动赋予该列对应数据类型的隐式默认值（例如数字类型填充 0，字符串类型填充空字符串 ""）。 + +TiDB 在早期版本中对非空约束的校验相对宽松。当从低版本 TiDB（如 v6.x、v7.x 等）升级至 v8.5 或更高版本时，如果存量业务逻辑依赖于这种“隐式赋默认值”的行为，开启此变量可能会导致原有 SQL 报错。如果从 MySQL 5.7 迁移至 TiDB，或从 TiDB 早期版本平滑升级至高版本且无法立即修改业务逻辑，可将此变量设置为 `OFF` 。 ### `tidb_enable_strict_double_type_check` 从 v5.0 版本开始引入 @@ -2770,7 +2775,7 @@ v5.0 后，用户仍可以单独修改以上系统变量（会有废弃警告） - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 类型：布尔型 - 默认值：`OFF` -- 该变量用于控制在悲观事务中，外键约束检查对父表中的行加锁时是否使用共享锁（而非排他锁）。开启后，多个并发事务可以同时对同一父表行执行外键检查而不互相阻塞，从而降低锁冲突并提升子表并发写入性能。 +- 该变量用于控制在悲观事务中，外键约束检查对父表中的行加锁时是否使用共享锁（而非排他锁）。开启后，多个并发事务可以同时对同一父表行执行外键检查而不互相阻塞，从而降低锁冲突并提升子表并发写入性能。 ### `tidb_gc_concurrency` 从 v5.0 版本开始引入 From f787c4c7e135f70ee7c785c9628299c36b5f444e Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 7 May 2026 17:15:38 +0800 Subject: [PATCH 3/4] Apply suggestions from code review --- system-variables.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/system-variables.md b/system-variables.md index be6332810ef5..fdbb71c647d6 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2486,13 +2486,19 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - 是否受 Hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value) 控制：否 - 类型：布尔型 - 默认值：`ON` -- 该变量用于控制在向定义为 NOT NULL 的列插入 NULL 值时的校验行为。 +- 该变量用于控制 TiDB 在执行 `INSERT` 语句时，是否对显式写入 `NOT NULL` 列的 `NULL` 值进行严格校验。 -MySQL 兼容性： -- ON (默认值)：与 MySQL 8.0 的标准行为保持一致。对于 NOT NULL 约束执行严格校验，插入 NULL 值将直接触发错误。 -- OFF：模拟 MySQL 5.7 及其早期版本在非严格模式下的行为。允许向非空列插入 NULL，此时系统不会报错，而是自动赋予该列对应数据类型的隐式默认值（例如数字类型填充 0，字符串类型填充空字符串 ""）。 +- 取值说明： + - `ON`：启用严格的 `NOT NULL` 校验。该行为更接近 MySQL 8.0 的标准语义。 + - 在严格 SQL 模式下，如果向 `NOT NULL` 列插入 `NULL` 值，TiDB 会返回错误。 + - 在非严格 SQL 模式下：对于单行 `INSERT` 语句，如果向 `NOT NULL` 列插入 `NULL` 值，TiDB 会返回错误；对于多行 `INSERT` 语句，如果向 `NOT NULL` 列插入 `NULL` 值，TiDB 会将该错误降级为 warning，并写入该列数据类型对应的隐式默认值。 + - `OFF`：关闭严格的 `NOT NULL` 校验，用于兼容 TiDB 早期版本中较宽松的行为。关闭后，当向 `NOT NULL` 列插入 `NULL` 值时，TiDB 会将该错误降级为 warning，并写入该列数据类型对应的隐式默认值。例如，数字类型写入 `0`，字符串类型写入空字符串 `''`。 -TiDB 在早期版本中对非空约束的校验相对宽松。当从低版本 TiDB（如 v6.x、v7.x 等）升级至 v8.5 或更高版本时，如果存量业务逻辑依赖于这种“隐式赋默认值”的行为，开启此变量可能会导致原有 SQL 报错。如果从 MySQL 5.7 迁移至 TiDB，或从 TiDB 早期版本平滑升级至高版本且无法立即修改业务逻辑，可将此变量设置为 `OFF` 。 +> **注意：** +> +> - TiDB 早期版本对 `NOT NULL` 约束的校验相对宽松，向 `NOT NULL` 列插入 `NULL` 值时，可能会自动写入该列数据类型对应的隐式默认值。从 v8.5.0 起，TiDB 收紧了这类校验：即使在非严格 SQL 模式下，向 `NOT NULL` 列插入 `NULL` 值也可能直接返回错误。该行为更接近 MySQL 8.0 语义，但可能影响依赖 TiDB 早期宽松行为的存量业务。 +> +> - 如果从 TiDB 早期版本升级到启用了严格 `NOT NULL` 校验的版本，并且现有业务逻辑依赖向 `NOT NULL` 列写入 `NULL` 后自动使用隐式默认值的行为，升级后相关 SQL 语句可能会返回错误。在无法立即修改业务逻辑的情况下，可以临时将该变量设置为 `OFF`，以降低升级兼容性风险。建议后续修改应用逻辑，避免向 `NOT NULL` 列显式写入 `NULL` 值。 ### `tidb_enable_strict_double_type_check` 从 v5.0 版本开始引入 From d0a999adb72446c84a5d0c80f18f5cd9e75d1bcf Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 7 May 2026 17:15:49 +0800 Subject: [PATCH 4/4] Update system-variables.md --- system-variables.md | 1 - 1 file changed, 1 deletion(-) diff --git a/system-variables.md b/system-variables.md index fdbb71c647d6..5b088e45aa2e 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2487,7 +2487,6 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - 类型：布尔型 - 默认值：`ON` - 该变量用于控制 TiDB 在执行 `INSERT` 语句时，是否对显式写入 `NOT NULL` 列的 `NULL` 值进行严格校验。 - - 取值说明： - `ON`：启用严格的 `NOT NULL` 校验。该行为更接近 MySQL 8.0 的标准语义。 - 在严格 SQL 模式下，如果向 `NOT NULL` 列插入 `NULL` 值，TiDB 会返回错误。