From 0c84b0730787b2a6bd86368c6649f3180d0836f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Mon, 8 Apr 2024 17:18:55 +0200 Subject: [PATCH 1/6] ebnf user variable --- sql-statements/sql-statement-set-variable.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/sql-statements/sql-statement-set-variable.md b/sql-statements/sql-statement-set-variable.md index 6fb9326754b5d..f998eba597b43 100644 --- a/sql-statements/sql-statement-set-variable.md +++ b/sql-statements/sql-statement-set-variable.md @@ -6,7 +6,11 @@ aliases: ['/docs/dev/sql-statements/sql-statement-set-variable/','/docs/dev/refe # `SET [GLOBAL|SESSION] ` -The statement `SET [GLOBAL|SESSION]` modifies one of TiDB's built in variables, of either `SESSION` or `GLOBAL` scope. +The statement `SET [GLOBAL|SESSION]` modifies one of TiDB's built in variables. These variables can be [system variables](/system-variables.md) of either `SESSION` or `GLOBAL` scope or [user variables](/user-defined-variables.md). + +> **Warning:** +> +> User-defined variables are still an experimental feature. It is **NOT** recommended that you use them in the production environment. > **Note:** > @@ -14,13 +18,14 @@ The statement `SET [GLOBAL|SESSION]` modifies one of TiDB's built in variables, ## Synopsis -**SetStmt:** - -![SetStmt](/media/sqlgram/SetStmt.png) +```ebnf+diagram +SetVariableStmt ::= + "SET" Variable "=" Expression ("," Variable "=" Expression )* -**VariableAssignment:** - -![VariableAssignment](/media/sqlgram/VariableAssignment.png) +Variable ::= + ("GLOBAL" | "SESSION") SystemVariable +| UserVariable +``` ## Examples From 47aec13bc1ffdefb47f3b56a715e6de2cb4efcc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Mon, 8 Apr 2024 17:24:51 +0200 Subject: [PATCH 2/6] Add note about SET PERSIST --- sql-statements/sql-statement-set-variable.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sql-statements/sql-statement-set-variable.md b/sql-statements/sql-statement-set-variable.md index f998eba597b43..2d850ac9a5e57 100644 --- a/sql-statements/sql-statement-set-variable.md +++ b/sql-statements/sql-statement-set-variable.md @@ -94,6 +94,7 @@ The following behavior differences apply: * Changes made with `SET GLOBAL` will be propagated to all TiDB instances in the cluster. This differs from MySQL, where changes do not propagate to replicas. * TiDB presents several variables as both readable and settable. This is required for MySQL compatibility, because it is common for both applications and connectors to read MySQL variables. For example: JDBC connectors both read and set query cache settings, despite not relying on the behavior. * Changes made with `SET GLOBAL` will persist through TiDB server restarts. This means that `SET GLOBAL` in TiDB behaves more similar to `SET PERSIST` as available in MySQL 8.0 and above. +* TiDB doesn't support `SET PERSIST` and `SET PERSIST_ONLY` as TiDB persists global variables. ## See also From 37c39d4241ccab8104a5725d3d1135afbc571c0b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Mon, 8 Apr 2024 17:27:05 +0200 Subject: [PATCH 3/6] Add uservar example --- sql-statements/sql-statement-set-variable.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/sql-statements/sql-statement-set-variable.md b/sql-statements/sql-statement-set-variable.md index 2d850ac9a5e57..7e4c4a95a42a3 100644 --- a/sql-statements/sql-statement-set-variable.md +++ b/sql-statements/sql-statement-set-variable.md @@ -87,6 +87,21 @@ mysql> SHOW SESSION VARIABLES LIKE 'sql_mode'; 1 row in set (0.00 sec) ``` +User variables start with a `@`. + +```sql +mysql> SET @myvar := 5; +Query OK, 0 rows affected (0.00 sec) + +mysql> SELECT @myvar, @myvar + 1; ++--------+------------+ +| @myvar | @myvar + 1 | ++--------+------------+ +| 5 | 6 | ++--------+------------+ +1 row in set (0.00 sec) +``` + ## MySQL compatibility The following behavior differences apply: From f2637b965002798604b3d5b98d063c612bf66ef1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= Date: Mon, 8 Apr 2024 17:42:27 +0200 Subject: [PATCH 4/6] Link uservar docs to set stmt docs --- user-defined-variables.md | 28 ++-------------------------- 1 file changed, 2 insertions(+), 26 deletions(-) diff --git a/user-defined-variables.md b/user-defined-variables.md index 5a18349c13dd7..3f2ebe74c8ea8 100644 --- a/user-defined-variables.md +++ b/user-defined-variables.md @@ -18,48 +18,36 @@ The user-defined variables are session-specific, which means a user variable def ## Set the user-defined variables -You can use the `SET` statement to set a user-defined variable, and the syntax is `SET @var_name = expr [, @var_name = expr] ...;`. For example: - -{{< copyable "sql" >}} +You can use the [`SET` statement](/sql-statements/sql-statement-set-variable.md) to set a user-defined variable, and the syntax is `SET @var_name = expr [, @var_name = expr] ...;`. For example: ```sql SET @favorite_db = 'TiDB'; ``` -{{< copyable "sql" >}} - ```sql SET @a = 'a', @b = 'b', @c = 'c'; ``` For the assignment operator, you can also use `:=`. For example: -{{< copyable "sql" >}} - ```sql SET @favorite_db := 'TiDB'; ``` The content to the right of the assignment operator can be any valid expression. For example: -{{< copyable "sql" >}} - ```sql SET @c = @a + @b; ``` -{{< copyable "sql" >}} - ```sql -set @c = b'1000001' + b'1000001'; +SET @c = b'1000001' + b'1000001'; ``` ## Read the user-defined variables To read a user-defined variable, you can use the `SELECT` statement to query: -{{< copyable "sql" >}} - ```sql SELECT @a1, @a2, @a3 ``` @@ -90,16 +78,12 @@ Before the variable `@a4` is modified or the connection is closed, its value is If a hexadecimal literal or binary literal is used when setting the user-defined variable, TiDB will treat it as a binary string. If you want to set it to a number, you can manually add the `CAST` conversion, or use the numeric operator in the expression: -{{< copyable "sql" >}} - ```sql SET @v1 = b'1000001'; SET @v2 = b'1000001'+0; SET @v3 = CAST(b'1000001' AS UNSIGNED); ``` -{{< copyable "sql" >}} - ```sql SELECT @v1, @v2, @v3; ``` @@ -114,8 +98,6 @@ SELECT @v1, @v2, @v3; If you refer to a user-defined variable that has not been initialized, it has a value of NULL and a type of string. -{{< copyable "sql" >}} - ```sql SELECT @not_exist; ``` @@ -130,8 +112,6 @@ SELECT @not_exist; In addition to using the `SELECT` statement to read the user-defined variables, another common usage is the `PREPARE` statement. For example: -{{< copyable "sql" >}} - ```sql SET @s = 'SELECT SQRT(POW(?,2) + POW(?,2)) AS hypotenuse'; PREPARE stmt FROM @s; @@ -150,8 +130,6 @@ EXECUTE stmt USING @a, @b; The contents of the user-defined variables are not recognized as identifiers in the SQL statements. For example: -{{< copyable "sql" >}} - ```sql SELECT * from t; ``` @@ -164,8 +142,6 @@ SELECT * from t; +---+ ``` -{{< copyable "sql" >}} - ```sql SET @col = "`a`"; SELECT @col FROM t; From e23ff38914c721cfd182bc6af016dbbd8ba88c64 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Fri, 12 Apr 2024 11:44:21 +0800 Subject: [PATCH 5/6] Update sql-statements/sql-statement-set-variable.md --- sql-statements/sql-statement-set-variable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sql-statements/sql-statement-set-variable.md b/sql-statements/sql-statement-set-variable.md index 7e4c4a95a42a3..7fd28be9c7848 100644 --- a/sql-statements/sql-statement-set-variable.md +++ b/sql-statements/sql-statement-set-variable.md @@ -109,7 +109,7 @@ The following behavior differences apply: * Changes made with `SET GLOBAL` will be propagated to all TiDB instances in the cluster. This differs from MySQL, where changes do not propagate to replicas. * TiDB presents several variables as both readable and settable. This is required for MySQL compatibility, because it is common for both applications and connectors to read MySQL variables. For example: JDBC connectors both read and set query cache settings, despite not relying on the behavior. * Changes made with `SET GLOBAL` will persist through TiDB server restarts. This means that `SET GLOBAL` in TiDB behaves more similar to `SET PERSIST` as available in MySQL 8.0 and above. -* TiDB doesn't support `SET PERSIST` and `SET PERSIST_ONLY` as TiDB persists global variables. +* TiDB does not support `SET PERSIST` and `SET PERSIST_ONLY`, because TiDB persists global variables. ## See also From 6aef8443daf0efd8a2a44bc34ea98fba5747a51f Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 15 Apr 2024 12:48:42 +0800 Subject: [PATCH 6/6] Update sql-statements/sql-statement-set-variable.md Co-authored-by: Grace Cai --- sql-statements/sql-statement-set-variable.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sql-statements/sql-statement-set-variable.md b/sql-statements/sql-statement-set-variable.md index 7fd28be9c7848..72f443fe160d0 100644 --- a/sql-statements/sql-statement-set-variable.md +++ b/sql-statements/sql-statement-set-variable.md @@ -90,10 +90,10 @@ mysql> SHOW SESSION VARIABLES LIKE 'sql_mode'; User variables start with a `@`. ```sql -mysql> SET @myvar := 5; +SET @myvar := 5; Query OK, 0 rows affected (0.00 sec) -mysql> SELECT @myvar, @myvar + 1; +SELECT @myvar, @myvar + 1; +--------+------------+ | @myvar | @myvar + 1 | +--------+------------+