faq, sysvars: add tidb_multi_statement_mode (#4741)

* faq, sysvars: add tidb_multi_statement_mode * Correct "prevent" to "reduce impact" * Add table to show full behaviors * Update faq/tidb-faq.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> * Update system-variables.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> * Update system-variables.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> * rename multi-statements to multiple-statements for consistency. Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>
pingcap · Mar 1, 2021 · e047be6 · e047be6
1 parent 48f8700
commit e047be6
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 7 deletions.
diff --git a/faq/tidb-faq.md b/faq/tidb-faq.md
@@ -140,15 +140,11 @@ update mysql.tidb set variable_value='30m' where variable_name='tikv_gc_life_tim
 
 Check whether `tidb_disable_txn_auto_retry` is set to `on`. If so, set it to `off`; if it is already `off`, increase the value of `tidb_retry_limit` until the error no longer occurs.
 
-#### ERROR 1105 (HY000): client has multi-statement capability disabled
+#### ERROR 8130 (HY000): client has multi-statement capability disabled
 
-This error might occur after upgrading from an earlier version of TiDB. To prevent against SQL injection attacks, TiDB now prevents multiple queries being executed in the same `COM_QUERY` call by default.
+This error might occur after upgrading from an earlier version of TiDB. To reduce the impact of SQL injection attacks, TiDB now prevents multiple queries from being executed in the same `COM_QUERY` call by default.
 
-Check the documentation for your client driver for instructions on how to enable multiple statements. i.e:
-
-* [go-sql-driver](https://github.com/go-sql-driver/mysql#multistatements) (`multiStatements`)
-* [Connector/J](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-configuration-properties.html) (`allowMultiQueries`)
-* PHP [mysqli](https://dev.mysql.com/doc/apis-php/en/apis-php-mysqli.quickstart.multiple-statement.html) (`mysqli_multi_query`)
+The system variable [`tidb_multi_statement_mode`](/system-variables.md#tidb_multi_statement_mode-new-in-v4011) can be used to control this behavior.
 
 ### MySQL native error messages
 

diff --git a/system-variables.md b/system-variables.md
@@ -711,6 +711,31 @@ For a system upgraded to v5.0.0-rc from an earlier version, if you have not modi
 - Default value: 60
 - This variable is used to set the step of the Prometheus statement generated when querying `METRIC_SCHEMA`. The unit is second.
 
+## tidb_multi_statement_mode <span class="version-mark">New in v4.0.11</span>
+
+- Scope: SESSION | GLOBAL
+- Default value: OFF
+- Permitted values: OFF, ON, WARN
+- This variable controls whether to allow multiple queries to be executed in the same `COM_QUERY` call.
+- To reduce the impact of SQL injection attacks, TiDB now prevents multiple queries from being executed in the same `COM_QUERY` call by default. This variable is intended to be used as part of an upgrade path from earlier versions of TiDB. The following behaviors apply:
+
+| Client setting         | `tidb_multi_statement_mode` value | Multiple statements permitted? |
+|------------------------|-----------------------------------|--------------------------------|
+| Multiple Statements = ON  | OFF                               | Yes                            |
+| Multiple Statements = ON  | ON                                | Yes                            |
+| Multiple Statements = ON  | WARN                              | Yes                            |
+| Multiple Statements = OFF | OFF                               | No                             |
+| Multiple Statements = OFF | ON                                | Yes                            |
+| Multiple Statements = OFF | WARN                              | Yes (+warning returned)        |
+
+> **Note:**
+>
+> Only the default value of `OFF` can be considered safe. Setting `tidb_multi_statement_mode=ON` might be required if your application was specifically designed for an earlier version of TiDB. If your application requires multiple statement support, it is recommended to use the setting provided by your client library instead of the `tidb_multi_statement_mode` option. For example:
+>
+> * [go-sql-driver](https://github.com/go-sql-driver/mysql#multistatements) (`multiStatements`)
+> * [Connector/J](https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-configuration-properties.html) (`allowMultiQueries`)
+> * PHP [mysqli](https://dev.mysql.com/doc/apis-php/en/apis-php-mysqli.quickstart.multiple-statement.html) (`mysqli_multi_query`)
+
 ### tidb_opt_agg_push_down
 
 - Scope: SESSION