*: add schema related FAQ and description of `tidb_max_delta_schema_c…

…ount` (#1584)
pingcap · Nov 11, 2019 · 22fa4ca · 22fa4ca
1 parent 4e7eb57
commit 22fa4ca
Show file tree

Hide file tree

Showing 8 changed files with 58 additions and 6 deletions.
diff --git a/dev/faq/tidb.md b/dev/faq/tidb.md
@@ -598,6 +598,13 @@ Now, there are still a few reasons for this error reporting (the latter two are
 > + For each DDL operation, the number of `schema` version changes is the same with the number of corresponding `schema state` version changes.
 > + Different DDL operations cause different number of `schema` version changes. For example, the `CREATE TABLE` statement causes one `schema` version change while the `ADD COLUMN` statement causes four.
 
+#### What are the causes of the "Information schema is out of date" error?
+
+When executing a DML statement, if TiDB fails to load the latest schema within a DDL lease (45s by default), the `Information schema is out of date` error might occur. Possible causes are:
+
+- The TiDB instance that executed this DML was killed, and the transaction execution corresponding to this DML statement took longer than a DDL lease. When the transaction was committed, the error occurred.
+- TiDB failed to connect to PD or TiKV while executing this DML statement. As a result, TiDB failed to load schema within a DDL lease or disconnected from PD due to the keepalive setting.
+
 #### Error is reported when executing DDL statements under high concurrency?
 
 When you execute DDL statements (such as creating tables in batches) under high concurrency, a very few of these statements might fail because of key conflicts during the concurrent execution.

diff --git a/dev/reference/configuration/tidb-server/tidb-specific-variables.md b/dev/reference/configuration/tidb-server/tidb-specific-variables.md
@@ -338,6 +338,12 @@ set @@global.tidb_distsql_scan_concurrency = 10
 - Default value: 512
 - This variable is used to set the number of retries when the DDL operation fails. When the number of retries exceeds the parameter value, the wrong DDL operation is canceled.
 
+### tidb_max_delta_schema_count <span class="version-mark">New in v2.1.18 and v3.0.5</span>
+
+- Scope: GLOBAL
+- Default value: 1024
+- This variable is used to set the maximum number of schema versions (the table IDs modified for corresponding versions) allowed to be cached. The value range is 100 ~ 16384.
+
 ### tidb_force_priority
 
 - Scope: SESSION
@@ -527,4 +533,4 @@ set tidb_query_log_max_len = 20
 
 - Scope: SESSION | GLOBAL
 - Default value: 0
-- This variable is used to enable or disable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statement_summary_by_digest` table to identify and troubleshoot SQL performance issues.
+- This variable is used to enable or disable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statement_summary_by_digest` table to identify and troubleshoot SQL performance issues.
diff --git a/v2.1/faq/tidb.md b/v2.1/faq/tidb.md
@@ -600,6 +600,13 @@ Now, there are still a few reasons for this error reporting (the latter two are
 > + For each DDL operation, the number of `schema` version changes is the same with the number of corresponding `schema state` version changes.
 > + Different DDL operations cause different number of `schema` version changes. For example, the `CREATE TABLE` statement causes one `schema` version change while the `ADD COLUMN` statement causes four.
 
+#### What are the causes of the "Information schema is out of date" error
+
+When executing a DML statement, if TiDB fails to load the latest schema within a DDL lease (45s by default), the `Information schema is out of date` error might occur. Possible causes are:
+
+- The TiDB instance that executed this DML was killed, and the transaction execution corresponding to this DML statement took longer than a DDL lease. When the transaction was committed, the error occurred.
+- TiDB failed to connect to PD or TiKV while executing this DML statement. As a result, TiDB failed to load schema within a DDL lease or disconnected from PD due to the keepalive setting.
+
 #### Error is reported when executing DDL statements under high concurrency?
 
 When you execute DDL statements (such as creating tables in batches) under high concurrency, a very few of these statements might fail because of key conflicts during the concurrent execution.

diff --git a/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md b/v2.1/reference/configuration/tidb-server/tidb-specific-variables.md
@@ -306,6 +306,12 @@ set @@global.tidb_distsql_scan_concurrency = 10
 - This variable is used to set the priority of executing the `ADD INDEX` operation in the `re-organize` phase.
 - You can set the value of this variable to `PRIORITY_LOW`, `PRIORITY_NORMAL` or `PRIORITY_HIGH`.
 
+### tidb_max_delta_schema_count <span class="version-mark">New in v2.1.18</span>
+
+- Scope: GLOBAL
+- Default value: 1024
+- This variable is used to set the maximum number of schema versions (the table IDs modified for corresponding versions) allowed to be cached. The value range is 100-16384. This variable is supported in TiDB 2.1.18 and later versions.
+
 ### tidb_force_priority
 
 - Scope: SESSION
@@ -362,4 +368,4 @@ set tidb_query_log_max_len = 20
 
 - Scope: SESSION
 - Default value: 0
-- This variable is used to set whether the `auto_increment` property of a column is allowed to be removed by executing `ALTER TABLE MODIFY` or `ALTER TABLE CHANGE` statements. It is not allowed by default.
+- This variable is used to set whether the `auto_increment` property of a column is allowed to be removed by executing `ALTER TABLE MODIFY` or `ALTER TABLE CHANGE` statements. It is not allowed by default.
diff --git a/v3.0/faq/tidb.md b/v3.0/faq/tidb.md
@@ -599,6 +599,13 @@ Now, there are still a few reasons for this error reporting (the latter two are
 > + For each DDL operation, the number of `schema` version changes is the same with the number of corresponding `schema state` version changes.
 > + Different DDL operations cause different number of `schema` version changes. For example, the `CREATE TABLE` statement causes one `schema` version change while the `ADD COLUMN` statement causes four.
 
+#### What are the causes of the "Information schema is out of date" error
+
+When executing a DML statement, if TiDB fails to load the latest schema within a DDL lease (45s by default), the `Information schema is out of date` error might occur. Possible causes are:
+
+- The TiDB instance that executed this DML was killed, and the transaction execution corresponding to this DML statement took longer than a DDL lease. When the transaction was committed, the error occurred.
+- TiDB failed to connect to PD or TiKV while executing this DML statement. As a result, TiDB failed to load schema within a DDL lease or disconnected from PD due to the keepalive setting.
+
 #### Error is reported when executing DDL statements under high concurrency?
 
 When you execute DDL statements (such as creating tables in batches) under high concurrency, a very few of these statements might fail because of key conflicts during the concurrent execution.

diff --git a/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md b/v3.0/reference/configuration/tidb-server/tidb-specific-variables.md
@@ -338,6 +338,12 @@ set @@global.tidb_distsql_scan_concurrency = 10
 - Default value: 512
 - This variable is used to set the number of retries when the DDL operation fails. When the number of retries exceeds the parameter value, the wrong DDL operation is canceled.
 
+### tidb_max_delta_schema_count <span class="version-mark">New in v3.0.5</span>
+
+- Scope: GLOBAL
+- Default value: 1024
+- This variable is used to set the maximum number of schema versions (the table IDs modified for corresponding versions) allowed to be cached. The value range is 100 ~ 16384.
+
 ### tidb_force_priority
 
 - Scope: SESSION
@@ -527,4 +533,4 @@ set tidb_query_log_max_len = 20
 
 - Scope: SESSION | GLOBAL
 - Default value: 0
-- This variable is used to enable or disable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statement_summary_by_digest` table to identify and troubleshoot SQL performance issues.
+- This variable is used to enable or disable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statement_summary_by_digest` table to identify and troubleshoot SQL performance issues.
diff --git a/v3.1/faq/tidb.md b/v3.1/faq/tidb.md
@@ -598,6 +598,13 @@ Now, there are still a few reasons for this error reporting (the latter two are
 > + For each DDL operation, the number of `schema` version changes is the same with the number of corresponding `schema state` version changes.
 > + Different DDL operations cause different number of `schema` version changes. For example, the `CREATE TABLE` statement causes one `schema` version change while the `ADD COLUMN` statement causes four.
 
+#### What are the causes of the "Information schema is out of date" error
+
+When executing a DML statement, if TiDB fails to load the latest schema within a DDL lease (45s by default), the `Information schema is out of date` error might occur. Possible causes are:
+
+- The TiDB instance that executed this DML was killed, and the transaction execution corresponding to this DML statement took longer than a DDL lease. When the transaction was committed, the error occurred.
+- TiDB failed to connect to PD or TiKV while executing this DML statement. As a result, TiDB failed to load schema within a DDL lease or disconnected from PD due to the keepalive setting.
+
 #### Error is reported when executing DDL statements under high concurrency?
 
 When you execute DDL statements (such as creating tables in batches) under high concurrency, a very few of these statements might fail because of key conflicts during the concurrent execution.

diff --git a/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md b/v3.1/reference/configuration/tidb-server/tidb-specific-variables.md
@@ -338,6 +338,12 @@ set @@global.tidb_distsql_scan_concurrency = 10
 - Default value: 512
 - This variable is used to set the number of retries when the DDL operation fails. When the number of retries exceeds the parameter value, the wrong DDL operation is canceled.
 
+### tidb_max_delta_schema_count
+
+- Scope: GLOBAL
+- Default value: 1024
+- This variable is used to set the maximum number of schema versions (the table IDs modified for corresponding versions) allowed to be cached. The value range is 100 ~ 16384.
+
 ### tidb_force_priority
 
 - Scope: SESSION
@@ -517,14 +523,14 @@ set tidb_query_log_max_len = 20
 - Default value: 0
 - By default, Regions are split for a new table when it is being created in TiDB. After this variable is enabled, the newly split Regions are scattered immediately during the execution of the `CREATE TABLE` statement. This applies to the scenario where data need to be written in batches right after the tables are created in batches, because the newly split Regions can be scattered in TiKV beforehand and do not have to wait to be scheduled by PD. To ensure the continuous stability of writing data in batches, the `CREATE TABLE` statement returns success only after the Regions are successfully scattered. This makes the statement's execution time multiple times longer than that when you disable this variable.
 
-### tidb_allow_remove_auto_inc <span class="version-mark">New in v3.0.4</span>
+### tidb_allow_remove_auto_inc
 
 - Scope: SESSION
 - Default value: 0
 - This variable is used to set whether the `auto_increment` property of a column is allowed to be removed by executing `ALTER TABLE MODIFY` or `ALTER TABLE CHANGE` statements. It is not allowed by default.
 
-### tidb_enable_stmt_summary <span class="version-mark">New in v3.0.4</span>
+### tidb_enable_stmt_summary
 
 - Scope: SESSION | GLOBAL
 - Default value: 0
-- This variable is used to enable or disable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statement_summary_by_digest` table to identify and troubleshoot SQL performance issues.
+- This variable is used to enable or disable the statement summary feature. If enabled, SQL execution information like time consumption is recorded to the `performance_schema.events_statement_summary_by_digest` table to identify and troubleshoot SQL performance issues.