From 750a70991829dda9aedcf7e887ba96745a795c5a Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Mon, 1 Feb 2021 11:16:19 +0800 Subject: [PATCH 1/2] cherry pick #4722 to release-3.0 Signed-off-by: ti-srebot --- expression-syntax.md | 45 +++++ sql-statements/sql-statement-add-column.md | 36 ++++ sql-statements/sql-statement-add-index.md | 77 +++++++++ .../sql-statement-admin-cancel-ddl.md | 12 +- .../sql-statement-admin-check-table-index.md | 12 +- .../sql-statement-admin-checksum-table.md | 12 +- .../sql-statement-admin-show-ddl.md | 17 +- sql-statements/sql-statement-admin.md | 7 +- .../sql-statement-alter-database.md | 13 ++ sql-statements/sql-statement-alter-index.md | 154 ++++++++++++++++++ .../sql-statement-alter-instance.md | 45 +++++ sql-statements/sql-statement-alter-table.md | 41 +++-- sql-statements/sql-statement-alter-user.md | 19 ++- sql-statements/sql-statement-analyze-table.md | 17 +- 14 files changed, 453 insertions(+), 54 deletions(-) create mode 100644 sql-statements/sql-statement-alter-index.md create mode 100644 sql-statements/sql-statement-alter-instance.md diff --git a/expression-syntax.md b/expression-syntax.md index 729798c2e9f08..69fdb645f0eb1 100644 --- a/expression-syntax.md +++ b/expression-syntax.md @@ -6,6 +6,7 @@ aliases: ['/docs/v3.0/expression-syntax/','/docs/v3.0/reference/sql/language-str # Expression Syntax +<<<<<<< HEAD The following rules define the expression syntax in TiDB. You can find the definition in `parser/parser.y`. The syntax parsing in TiDB is based on Yacc. ``` @@ -65,4 +66,48 @@ PrimaryExpression: | '+' PrimaryExpression | "BINARY" PrimaryExpression | PrimaryExpression "COLLATE" StringName +======= +An expression is a combination of one or more values, operators, or functions. In TiDB, expressions are mainly used in various clauses of the `SELECT` statement, including Group by clause, Where clause, Having clause, Join condition and window function. In addition, some DDL statements also use expressions, such as the setting of the default values, columns, and partition rules when creating tables. + +The expressions can be divided into the following types: + +- Identifier. For reference, see [Schema object names](/schema-object-names.md). + +- Predicates, numeric values, strings, date expressions. The [Literal values](/literal-values.md) of these types are also expressions. + +- Function calls and window functions. For reference, see [Functions and operators overview](/functions-and-operators/functions-and-operators-overview.md) and [Window functions](/functions-and-operators/window-functions.md) + +- ParamMarker (`?`), system variables, user variables and CASE expressions. + +The following rules are the expression syntax, which is based on the [parser.y](https://github.com/pingcap/parser/blob/master/parser.y) rules of TiDB parser. For the navigable version of the following syntax diagram, refer to [TiDB SQL Syntax Diagram](https://pingcap.github.io/sqlgram/#Expression). + +```ebnf+diagram +Expression ::= + ( singleAtIdentifier assignmentEq | 'NOT' | Expression ( logOr | 'XOR' | logAnd ) ) Expression +| 'MATCH' '(' ColumnNameList ')' 'AGAINST' '(' BitExpr FulltextSearchModifierOpt ')' +| PredicateExpr ( IsOrNotOp 'NULL' | CompareOp ( ( singleAtIdentifier assignmentEq )? PredicateExpr | AnyOrAll SubSelect ) )* ( IsOrNotOp ( trueKwd | falseKwd | 'UNKNOWN' ) )? + +PredicateExpr ::= + BitExpr ( BetweenOrNotOp BitExpr 'AND' BitExpr )* ( InOrNotOp ( '(' ExpressionList ')' | SubSelect ) | LikeOrNotOp SimpleExpr LikeEscapeOpt | RegexpOrNotOp SimpleExpr )? + +BitExpr ::= + BitExpr ( ( '|' | '&' | '<<' | '>>' | '*' | '/' | '%' | 'DIV' | 'MOD' | '^' ) BitExpr | ( '+' | '-' ) ( BitExpr | "INTERVAL" Expression TimeUnit ) ) +| SimpleExpr + +SimpleExpr ::= + SimpleIdent ( ( '->' | '->>' ) stringLit )? +| FunctionCallKeyword +| FunctionCallNonKeyword +| FunctionCallGeneric +| SimpleExpr ( 'COLLATE' CollationName | pipes SimpleExpr ) +| WindowFuncCall +| Literal +| paramMarker +| Variable +| SumExpr +| ( '!' | '~' | '-' | '+' | 'NOT' | 'BINARY' ) SimpleExpr +| 'EXISTS'? SubSelect +| ( ( '(' ( ExpressionList ',' )? | 'ROW' '(' ExpressionList ',' ) Expression | builtinCast '(' Expression 'AS' CastType | ( 'DEFAULT' | 'VALUES' ) '(' SimpleIdent | 'CONVERT' '(' Expression ( ',' CastType | 'USING' CharsetName ) ) ')' +| 'CASE' ExpressionOpt WhenClause+ ElseOpt 'END' +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ``` diff --git a/sql-statements/sql-statement-add-column.md b/sql-statements/sql-statement-add-column.md index 5b043f8067488..b999df94d2aa1 100644 --- a/sql-statements/sql-statement-add-column.md +++ b/sql-statements/sql-statement-add-column.md @@ -10,6 +10,7 @@ The `ALTER TABLE.. ADD COLUMN` statement adds a column to an existing table. Thi ## Synopsis +<<<<<<< HEAD **AlterTableStmt:** ![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) @@ -29,6 +30,41 @@ The `ALTER TABLE.. ADD COLUMN` statement adds a column to an existing table. Thi **ColumnPosition:** ![ColumnPosition](/media/sqlgram/ColumnPosition.png) +======= +```ebnf+diagram +AlterTableStmt ::= + 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) + +AlterTableSpec ::= + TableOptionList +| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList +| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate +| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) +| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList +| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM +| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) +| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt +| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' +| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt +| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* +| ( 'DISABLE' | 'ENABLE' ) 'KEYS' +| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition +| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) +| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) +| LockClause +| AlgorithmClause +| 'FORCE' +| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' +| 'SECONDARY_LOAD' +| 'SECONDARY_UNLOAD' + +ColumnDef ::= + ColumnName ( Type | 'SERIAL' ) ColumnOptionListOpt + +ColumnPosition ::= + ( 'FIRST' | 'AFTER' ColumnName )? +``` +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-add-index.md b/sql-statements/sql-statement-add-index.md index 4c5bbcf72beb3..ec77075965f1f 100644 --- a/sql-statements/sql-statement-add-index.md +++ b/sql-statements/sql-statement-add-index.md @@ -10,6 +10,7 @@ The `ALTER TABLE.. ADD INDEX` statement adds an index to an existing table. This ## Synopsis +<<<<<<< HEAD **AlterTableStmt:** ![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) @@ -29,6 +30,82 @@ The `ALTER TABLE.. ADD INDEX` statement adds an index to an existing table. This **ColumnPosition:** ![ColumnPosition](/media/sqlgram/ColumnPosition.png) +======= +```ebnf+diagram +AlterTableStmt ::= + 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) + +AlterTableSpec ::= + TableOptionList +| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList +| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate +| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) +| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList +| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM +| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) +| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt +| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' +| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt +| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* +| ( 'DISABLE' | 'ENABLE' ) 'KEYS' +| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition +| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) +| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) +| LockClause +| AlgorithmClause +| 'FORCE' +| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' +| 'SECONDARY_LOAD' +| 'SECONDARY_UNLOAD' + +Constraint ::= + ConstraintKeywordOpt ConstraintElem + +ConstraintKeywordOpt ::= + ( 'CONSTRAINT' Symbol? )? + +ConstraintElem ::= + ( ( 'PRIMARY' 'KEY' | KeyOrIndex IfNotExists | 'UNIQUE' KeyOrIndexOpt ) IndexNameAndTypeOpt | 'FULLTEXT' KeyOrIndexOpt IndexName ) '(' IndexPartSpecificationList ')' IndexOptionList +| 'FOREIGN' 'KEY' IfNotExists IndexName '(' IndexPartSpecificationList ')' ReferDef +| 'CHECK' '(' Expression ')' EnforcedOrNotOpt + +IndexNameAndTypeOpt ::= + IndexName ( 'USING' IndexTypeName )? +| Identifier 'TYPE' IndexTypeName + +IndexPartSpecificationList ::= + IndexPartSpecification ( ',' IndexPartSpecification )* + +IndexPartSpecification ::= + ( ColumnName OptFieldLen | '(' Expression ')' ) Order + +IndexOptionList ::= + IndexOption* + +IndexOption ::= + 'KEY_BLOCK_SIZE' '='? LengthNum +| IndexType +| 'WITH' 'PARSER' Identifier +| 'COMMENT' stringLit +| IndexInvisible + +KeyOrIndex ::= + 'KEY' +| 'INDEX' + +IndexKeyTypeOpt ::= + ( 'UNIQUE' | 'SPATIAL' | 'FULLTEXT' )? + +IndexInvisible ::= + 'VISIBLE' +| 'INVISIBLE' + +IndexTypeName ::= + 'BTREE' +| 'HASH' +| 'RTREE' +``` +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-admin-cancel-ddl.md b/sql-statements/sql-statement-admin-cancel-ddl.md index 2cdc472fe8c2c..ee7c9c421807a 100644 --- a/sql-statements/sql-statement-admin-cancel-ddl.md +++ b/sql-statements/sql-statement-admin-cancel-ddl.md @@ -10,13 +10,13 @@ The `ADMIN CANCEL DDL` statement allows you to cancel a running DDL job. The `jo ## Synopsis -**AdminStmt:** +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) -![AdminStmt](/media/sqlgram/AdminStmt.png) - -**NumList:** - -![NumList](/media/sqlgram/NumList.png) +NumList ::= + Int64Num ( ',' Int64Num )* +``` ## Examples diff --git a/sql-statements/sql-statement-admin-check-table-index.md b/sql-statements/sql-statement-admin-check-table-index.md index cd54905600b38..921ca1f739fc9 100644 --- a/sql-statements/sql-statement-admin-check-table-index.md +++ b/sql-statements/sql-statement-admin-check-table-index.md @@ -10,13 +10,13 @@ The `ADMIN CHECK [TABLE|INDEX]` statement checks for data consistency of tables ## Synopsis -**AdminStmt:** +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) -![AdminStmt](/media/sqlgram/AdminStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) +TableNameList ::= + TableName ( ',' TableName )* +``` ## Examples diff --git a/sql-statements/sql-statement-admin-checksum-table.md b/sql-statements/sql-statement-admin-checksum-table.md index 3ecb7c6e19b13..80d1ff05028d9 100644 --- a/sql-statements/sql-statement-admin-checksum-table.md +++ b/sql-statements/sql-statement-admin-checksum-table.md @@ -10,13 +10,13 @@ The `ADMIN CHECKSUM TABLE` statement calculates a CRC64 checksum for the data an ## Synopsis -**AdminStmt:** +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) -![AdminStmt](/media/sqlgram/AdminStmt.png) - -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) +TableNameList ::= + TableName ( ',' TableName )* +``` ## Examples diff --git a/sql-statements/sql-statement-admin-show-ddl.md b/sql-statements/sql-statement-admin-show-ddl.md index 894c23e75c8c8..42c48b9522fc6 100644 --- a/sql-statements/sql-statement-admin-show-ddl.md +++ b/sql-statements/sql-statement-admin-show-ddl.md @@ -9,17 +9,16 @@ The `ADMIN SHOW DDL [JOBS|QUERIES]` statement shows information about running an ## Synopsis -**AdminStmt:** +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) -![AdminStmt](/media/sqlgram/AdminStmt.png) +NumList ::= + Int64Num ( ',' Int64Num )* -**NumList:** - -![NumList](/media/sqlgram/NumList.png) - -**WhereClauseOptional:** - -![WhereClauseOptional](/media/sqlgram/WhereClauseOptional.png) +WhereClauseOptional ::= + WhereClause? +``` ## Examples diff --git a/sql-statements/sql-statement-admin.md b/sql-statements/sql-statement-admin.md index 6e5cb5c59248a..14aa27cb21963 100644 --- a/sql-statements/sql-statement-admin.md +++ b/sql-statements/sql-statement-admin.md @@ -62,9 +62,10 @@ If the consistency check is passed, an empty result is returned. Otherwise, an e ## Synopsis -**AdminStmt:** - -![AdminStmt](/media/sqlgram/AdminStmt.png) +```ebnf+diagram +AdminStmt ::= + 'ADMIN' ( 'SHOW' ( 'DDL' ( 'JOBS' Int64Num? WhereClauseOptional | 'JOB' 'QUERIES' NumList )? | TableName 'NEXT_ROW_ID' | 'SLOW' AdminShowSlow ) | 'CHECK' ( 'TABLE' TableNameList | 'INDEX' TableName Identifier ( HandleRange ( ',' HandleRange )* )? ) | 'RECOVER' 'INDEX' TableName Identifier | 'CLEANUP' ( 'INDEX' TableName Identifier | 'TABLE' 'LOCK' TableNameList ) | 'CHECKSUM' 'TABLE' TableNameList | 'CANCEL' 'DDL' 'JOBS' NumList | 'RELOAD' ( 'EXPR_PUSHDOWN_BLACKLIST' | 'OPT_RULE_BLACKLIST' | 'BINDINGS' ) | 'PLUGINS' ( 'ENABLE' | 'DISABLE' ) PluginNameList | 'REPAIR' 'TABLE' TableName CreateTableStmt | ( 'FLUSH' | 'CAPTURE' | 'EVOLVE' ) 'BINDINGS' ) +``` ## Examples diff --git a/sql-statements/sql-statement-alter-database.md b/sql-statements/sql-statement-alter-database.md index 2718c98576797..e0848ca0344e2 100644 --- a/sql-statements/sql-statement-alter-database.md +++ b/sql-statements/sql-statement-alter-database.md @@ -8,6 +8,19 @@ aliases: ['/docs/v3.0/sql-statements/sql-statement-alter-database/','/docs/v3.0/ `ALTER DATABASE` is used to specify or modify the default character set and collation of the current database. `ALTER SCHEMA` has the same effect as `ALTER DATABASE`. +<<<<<<< HEAD +======= +## Synopsis + +```ebnf+diagram +AlterDatabaseStmt ::= + 'ALTER' 'DATABASE' DBName? DatabaseOptionList + +DatabaseOption ::= + DefaultKwdOpt ( CharsetKw '='? CharsetName | 'COLLATE' '='? CollationName | 'ENCRYPTION' '='? EncryptionOpt ) +``` + +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples ```sql diff --git a/sql-statements/sql-statement-alter-index.md b/sql-statements/sql-statement-alter-index.md new file mode 100644 index 0000000000000..bff21e3ff4fca --- /dev/null +++ b/sql-statements/sql-statement-alter-index.md @@ -0,0 +1,154 @@ +--- +title: ALTER INDEX +summary: An overview of the usage of ALTER INDEX for the TiDB database. +aliases: ['/docs/dev/sql-statements/sql-statement-alter-index/'] +--- + +# ALTER INDEX + +The `ALTER INDEX` statement is used to modify the visibility of the index to `Visible` or `Invisible`. Invisible indexes are maintained by DML statements, but will not be used by the query optimizer. This is useful in scenarios where you want to double-check before removing an index permanently. + +## Synopsis + +```ebnf+diagram +AlterTableStmt ::= + 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) + +AlterTableSpec ::= + TableOptionList +| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList +| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate +| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) +| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList +| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM +| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) +| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt +| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' +| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt +| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* +| ( 'DISABLE' | 'ENABLE' ) 'KEYS' +| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition +| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) +| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) +| LockClause +| AlgorithmClause +| 'FORCE' +| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' +| 'SECONDARY_LOAD' +| 'SECONDARY_UNLOAD' + +IndexInvisible ::= + 'VISIBLE' +| 'INVISIBLE' +``` + +## Examples + +You can modify the visibility of an index using the `ALTER TABLE ... ALTER INDEX ...` statement. + +{{< copyable "sql" >}} + +```sql +CREATE TABLE t1 (c1 INT, UNIQUE(c1)); +ALTER TABLE t1 ALTER INDEX c1 INVISIBLE; +``` + +```sql +Query OK, 0 rows affected (0.02 sec) +``` + +{{< copyable "sql" >}} + +```sql +SHOW CREATE TABLE t1; +``` + +```sql ++-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Table | Create Table + | ++-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| t1 | CREATE TABLE `t1` ( + `c1` int(11) DEFAULT NULL, + UNIQUE KEY `c1` (`c1`) /*!80000 INVISIBLE */ +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | ++-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +1 row in set (0.00 sec) +``` + +The optimizer cannot use the **invisible index** of `c1`. + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT c1 FROM t1 ORDER BY c1; +``` + +```sql ++-------------------------+----------+-----------+---------------+--------------------------------+ +| id | estRows | task | access object | operator info | ++-------------------------+----------+-----------+---------------+--------------------------------+ +| Sort_4 | 10000.00 | root | | test.t1.c1:asc | +| └─TableReader_8 | 10000.00 | root | | data:TableFullScan_7 | +| └─TableFullScan_7 | 10000.00 | cop[tikv] | table:t1 | keep order:false, stats:pseudo | ++-------------------------+----------+-----------+---------------+--------------------------------+ +3 rows in set (0.00 sec) +``` + +By comparison, `c2` is a **visible index** and can be used by the optimizer. + +{{< copyable "sql" >}} + +```sql +EXPLAIN SELECT c2 FROM t1 ORDER BY c2; +``` + +```sql ++------------------------+----------+-----------+------------------------+-------------------------------+ +| id | estRows | task | access object | operator info | ++------------------------+----------+-----------+------------------------+-------------------------------+ +| IndexReader_13 | 10000.00 | root | | index:IndexFullScan_12 | +| └─IndexFullScan_12 | 10000.00 | cop[tikv] | table:t1, index:c2(c2) | keep order:true, stats:pseudo | ++------------------------+----------+-----------+------------------------+-------------------------------+ +2 rows in set (0.00 sec) +``` + +Even if you use the `USE INDEX` SQL hint to forcibly use indexes, the optimizer still cannot use invisible indexes; otherwise, an error is returned. + +{{< copyable "sql" >}} + +```sql +SELECT * FROM t1 USE INDEX(c1); +``` + +```sql +ERROR 1176 (42000): Key 'c1' doesn't exist in table 't1' +``` + +> **Note:** +> +> "Invisible" here means invisible only to the optimizer. You can still modify or delete invisible indexes. + +{{< copyable "sql" >}} + +```sql +ALTER TABLE t1 DROP INDEX c1; +``` + +```sql +Query OK, 0 rows affected (0.02 sec) +``` + +## MySQL compatibility + +* Invisible indexes in TiDB are modeled on the equivalent feature from MySQL 8.0. +* Similiar to MySQL, TiDB does not permit `PRIMARY KEY` indexes to be made invisible. +* MySQL provides an optimizer switch `use_invisible_indexes=on` to make all invisible indexes _visible_ again. This functionality is not available in TiDB. + +## See also + +* [CREATE TABLE](/sql-statements/sql-statement-create-table.md) +* [CREATE INDEX](/sql-statements/sql-statement-create-index.md) +* [ADD INDEX](/sql-statements/sql-statement-add-index.md) +* [DROP INDEX](/sql-statements/sql-statement-drop-index.md) +* [RENAME INDEX](/sql-statements/sql-statement-rename-index.md) diff --git a/sql-statements/sql-statement-alter-instance.md b/sql-statements/sql-statement-alter-instance.md new file mode 100644 index 0000000000000..a71c46ef53b77 --- /dev/null +++ b/sql-statements/sql-statement-alter-instance.md @@ -0,0 +1,45 @@ +--- +title: ALTER INSTANCE +summary: Learn the overview of the `ALTER INSTANCE` usage in TiDB. +aliases: ['/docs/dev/sql-statements/sql-statement-alter-instance/','/docs/dev/reference/sql/statements/alter-instance/'] +--- + +# ALTER INSTANCE + +The `ALTER INSTANCE` statement is used to make changes to a single TiDB instance. Currently, TiDB only supports the `RELOAD TLS` clause. + +## RELOAD TLS + +You can execute the `ALTER INSTANCE RELOAD TLS` statement to reload the certificate ([`ssl-cert`](/tidb-configuration-file.md#ssl-cert)), the key ([`ssl-key`](/tidb-configuration-file.md#ssl-key)), and the CA ([`ssl-ca`](/tidb-configuration-file.md#ssl-ca)) from the original configuration path. + +The newly loaded certificate, key, and CA take effect on the connection that is established after the statement is successfully executed. The connection established before this statement execution is not affected. + +When an error occurs during reloading, by default, this error message is returned and the previous key and certificate continue to be used. However, if you have added the optional `NO ROLLBACK ON ERROR`, when an error occurs during reloading, the error is not returned, and the subsequent requests are handled with the TLS security connection disabled. + +## Syntax diagram + +**AlterInstanceStmt:** + +```ebnf+diagram +AlterInstanceStmt ::= + 'ALTER' 'INSTANCE' InstanceOption + +InstanceOption ::= + 'RELOAD' 'TLS' ('NO' 'ROLLBACK' 'ON' 'ERROR')? +``` + +## Example + +{{< copyable "sql" >}} + +```sql +ALTER INSTANCE RELOAD TLS; +``` + +## MySQL compatibility + +The `ALTER INSTANCE RELOAD TLS` statement only supports reloading from the original configuration path. It does not support dynamically modifying the loading path or dynamically enabling the TLS encrypted connection feature when TiDB is started. This feature is disabled by default when you restart TiDB. + +## See also + +[Enable TLS Between TiDB Clients and Servers](/enable-tls-between-clients-and-servers.md). diff --git a/sql-statements/sql-statement-alter-table.md b/sql-statements/sql-statement-alter-table.md index 30403f5ebcec2..59b6bfb5de128 100644 --- a/sql-statements/sql-statement-alter-table.md +++ b/sql-statements/sql-statement-alter-table.md @@ -13,17 +13,36 @@ This statement modifies an existing table to conform to a new table structure. T ## Synopsis -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) +```ebnf+diagram +AlterTableStmt ::= + 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) + +TableName ::= + Identifier ('.' Identifier)? + +AlterTableSpec ::= + TableOptionList +| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList +| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate +| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) +| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList +| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM +| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) +| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt +| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' +| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt +| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* +| ( 'DISABLE' | 'ENABLE' ) 'KEYS' +| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition +| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) +| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) +| LockClause +| AlgorithmClause +| 'FORCE' +| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' +| 'SECONDARY_LOAD' +| 'SECONDARY_UNLOAD' +``` ## Examples diff --git a/sql-statements/sql-statement-alter-user.md b/sql-statements/sql-statement-alter-user.md index 5869062b9a6dc..6da0612b0490b 100644 --- a/sql-statements/sql-statement-alter-user.md +++ b/sql-statements/sql-statement-alter-user.md @@ -10,17 +10,28 @@ This statement changes an existing user inside the TiDB privilege system. In the ## Synopsis -**AlterUserStmt:** +```ebnf+diagram +AlterUserStmt ::= + 'ALTER' 'USER' IfExists (UserSpecList RequireClauseOpt ConnectionOptions PasswordOrLockOptions | 'USER' '(' ')' 'IDENTIFIED' 'BY' AuthString) -![AlterUserStmt](/media/sqlgram/AlterUserStmt.png) +UserSpecList ::= + UserSpec ( ',' UserSpec )* -**UserSpecList:** +UserSpec ::= + Username AuthOption -![UserSpecList](/media/sqlgram/UserSpecList.png) +Username ::= + StringName ('@' StringName | singleAtIdentifier)? | 'CURRENT_USER' OptionalBraces +<<<<<<< HEAD **UserSpec:** ![UserSpec](/media/sqlgram/UserSpec.png) +======= +AuthOption ::= + ( 'IDENTIFIED' ( 'BY' ( AuthString | 'PASSWORD' HashString ) | 'WITH' StringName ( 'BY' AuthString | 'AS' HashString )? ) )? +``` +>>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-analyze-table.md b/sql-statements/sql-statement-analyze-table.md index d5fa15d3acd0e..100aacbef3790 100644 --- a/sql-statements/sql-statement-analyze-table.md +++ b/sql-statements/sql-statement-analyze-table.md @@ -12,17 +12,16 @@ TiDB will also automatically update its statistics over time as it discovers tha ## Synopsis -**AnalyzeTableStmt:** +```ebnf+diagram +AnalyzeTableStmt ::= + 'ANALYZE' ( 'TABLE' ( TableNameList | TableName ( 'INDEX' IndexNameList | 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? ) ) | 'INCREMENTAL' 'TABLE' TableName ( 'PARTITION' PartitionNameList )? 'INDEX' IndexNameList ) AnalyzeOptionListOpt -![AnalyzeTableStmt](/media/sqlgram/AnalyzeTableStmt.png) +TableNameList ::= + TableName (',' TableName)* -**TableNameList:** - -![TableNameList](/media/sqlgram/TableNameList.png) - -**TableName:** - -![TableName](/media/sqlgram/TableName.png) +TableName ::= + Identifier ( '.' Identifier )? +``` ## Examples From 66efe90ad402dfca180e28cc98b3123d67a08827 Mon Sep 17 00:00:00 2001 From: Charlotte Liu <37295236+CharLotteiu@users.noreply.github.com> Date: Mon, 1 Feb 2021 11:45:48 +0800 Subject: [PATCH 2/2] resolve conflicts --- expression-syntax.md | 45 ----- sql-statements/sql-statement-add-column.md | 25 +-- sql-statements/sql-statement-add-index.md | 72 +------- .../sql-statement-alter-database.md | 13 -- sql-statements/sql-statement-alter-index.md | 154 ------------------ .../sql-statement-alter-instance.md | 45 ----- sql-statements/sql-statement-alter-user.md | 12 -- 7 files changed, 9 insertions(+), 357 deletions(-) delete mode 100644 sql-statements/sql-statement-alter-index.md delete mode 100644 sql-statements/sql-statement-alter-instance.md diff --git a/expression-syntax.md b/expression-syntax.md index 69fdb645f0eb1..729798c2e9f08 100644 --- a/expression-syntax.md +++ b/expression-syntax.md @@ -6,7 +6,6 @@ aliases: ['/docs/v3.0/expression-syntax/','/docs/v3.0/reference/sql/language-str # Expression Syntax -<<<<<<< HEAD The following rules define the expression syntax in TiDB. You can find the definition in `parser/parser.y`. The syntax parsing in TiDB is based on Yacc. ``` @@ -66,48 +65,4 @@ PrimaryExpression: | '+' PrimaryExpression | "BINARY" PrimaryExpression | PrimaryExpression "COLLATE" StringName -======= -An expression is a combination of one or more values, operators, or functions. In TiDB, expressions are mainly used in various clauses of the `SELECT` statement, including Group by clause, Where clause, Having clause, Join condition and window function. In addition, some DDL statements also use expressions, such as the setting of the default values, columns, and partition rules when creating tables. - -The expressions can be divided into the following types: - -- Identifier. For reference, see [Schema object names](/schema-object-names.md). - -- Predicates, numeric values, strings, date expressions. The [Literal values](/literal-values.md) of these types are also expressions. - -- Function calls and window functions. For reference, see [Functions and operators overview](/functions-and-operators/functions-and-operators-overview.md) and [Window functions](/functions-and-operators/window-functions.md) - -- ParamMarker (`?`), system variables, user variables and CASE expressions. - -The following rules are the expression syntax, which is based on the [parser.y](https://github.com/pingcap/parser/blob/master/parser.y) rules of TiDB parser. For the navigable version of the following syntax diagram, refer to [TiDB SQL Syntax Diagram](https://pingcap.github.io/sqlgram/#Expression). - -```ebnf+diagram -Expression ::= - ( singleAtIdentifier assignmentEq | 'NOT' | Expression ( logOr | 'XOR' | logAnd ) ) Expression -| 'MATCH' '(' ColumnNameList ')' 'AGAINST' '(' BitExpr FulltextSearchModifierOpt ')' -| PredicateExpr ( IsOrNotOp 'NULL' | CompareOp ( ( singleAtIdentifier assignmentEq )? PredicateExpr | AnyOrAll SubSelect ) )* ( IsOrNotOp ( trueKwd | falseKwd | 'UNKNOWN' ) )? - -PredicateExpr ::= - BitExpr ( BetweenOrNotOp BitExpr 'AND' BitExpr )* ( InOrNotOp ( '(' ExpressionList ')' | SubSelect ) | LikeOrNotOp SimpleExpr LikeEscapeOpt | RegexpOrNotOp SimpleExpr )? - -BitExpr ::= - BitExpr ( ( '|' | '&' | '<<' | '>>' | '*' | '/' | '%' | 'DIV' | 'MOD' | '^' ) BitExpr | ( '+' | '-' ) ( BitExpr | "INTERVAL" Expression TimeUnit ) ) -| SimpleExpr - -SimpleExpr ::= - SimpleIdent ( ( '->' | '->>' ) stringLit )? -| FunctionCallKeyword -| FunctionCallNonKeyword -| FunctionCallGeneric -| SimpleExpr ( 'COLLATE' CollationName | pipes SimpleExpr ) -| WindowFuncCall -| Literal -| paramMarker -| Variable -| SumExpr -| ( '!' | '~' | '-' | '+' | 'NOT' | 'BINARY' ) SimpleExpr -| 'EXISTS'? SubSelect -| ( ( '(' ( ExpressionList ',' )? | 'ROW' '(' ExpressionList ',' ) Expression | builtinCast '(' Expression 'AS' CastType | ( 'DEFAULT' | 'VALUES' ) '(' SimpleIdent | 'CONVERT' '(' Expression ( ',' CastType | 'USING' CharsetName ) ) ')' -| 'CASE' ExpressionOpt WhenClause+ ElseOpt 'END' ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ``` diff --git a/sql-statements/sql-statement-add-column.md b/sql-statements/sql-statement-add-column.md index b999df94d2aa1..eb0b327b124fb 100644 --- a/sql-statements/sql-statement-add-column.md +++ b/sql-statements/sql-statement-add-column.md @@ -10,27 +10,6 @@ The `ALTER TABLE.. ADD COLUMN` statement adds a column to an existing table. Thi ## Synopsis -<<<<<<< HEAD -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnPosition:** - -![ColumnPosition](/media/sqlgram/ColumnPosition.png) -======= ```ebnf+diagram AlterTableStmt ::= 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) @@ -58,13 +37,15 @@ AlterTableSpec ::= | 'SECONDARY_LOAD' | 'SECONDARY_UNLOAD' +ColumnKeywordOpt ::= + 'COLUMN'? + ColumnDef ::= ColumnName ( Type | 'SERIAL' ) ColumnOptionListOpt ColumnPosition ::= ( 'FIRST' | 'AFTER' ColumnName )? ``` ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-add-index.md b/sql-statements/sql-statement-add-index.md index ec77075965f1f..f0fe0c884bb17 100644 --- a/sql-statements/sql-statement-add-index.md +++ b/sql-statements/sql-statement-add-index.md @@ -10,27 +10,6 @@ The `ALTER TABLE.. ADD INDEX` statement adds an index to an existing table. This ## Synopsis -<<<<<<< HEAD -**AlterTableStmt:** - -![AlterTableStmt](/media/sqlgram/AlterTableStmt.png) - -**AlterTableSpec:** - -![AlterTableSpec](/media/sqlgram/AlterTableSpec.png) - -**ColumnKeywordOpt:** - -![ColumnKeywordOpt](/media/sqlgram/ColumnKeywordOpt.png) - -**ColumnDef:** - -![ColumnDef](/media/sqlgram/ColumnDef.png) - -**ColumnPosition:** - -![ColumnPosition](/media/sqlgram/ColumnPosition.png) -======= ```ebnf+diagram AlterTableStmt ::= 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) @@ -58,54 +37,15 @@ AlterTableSpec ::= | 'SECONDARY_LOAD' | 'SECONDARY_UNLOAD' -Constraint ::= - ConstraintKeywordOpt ConstraintElem - -ConstraintKeywordOpt ::= - ( 'CONSTRAINT' Symbol? )? - -ConstraintElem ::= - ( ( 'PRIMARY' 'KEY' | KeyOrIndex IfNotExists | 'UNIQUE' KeyOrIndexOpt ) IndexNameAndTypeOpt | 'FULLTEXT' KeyOrIndexOpt IndexName ) '(' IndexPartSpecificationList ')' IndexOptionList -| 'FOREIGN' 'KEY' IfNotExists IndexName '(' IndexPartSpecificationList ')' ReferDef -| 'CHECK' '(' Expression ')' EnforcedOrNotOpt - -IndexNameAndTypeOpt ::= - IndexName ( 'USING' IndexTypeName )? -| Identifier 'TYPE' IndexTypeName - -IndexPartSpecificationList ::= - IndexPartSpecification ( ',' IndexPartSpecification )* - -IndexPartSpecification ::= - ( ColumnName OptFieldLen | '(' Expression ')' ) Order - -IndexOptionList ::= - IndexOption* - -IndexOption ::= - 'KEY_BLOCK_SIZE' '='? LengthNum -| IndexType -| 'WITH' 'PARSER' Identifier -| 'COMMENT' stringLit -| IndexInvisible - -KeyOrIndex ::= - 'KEY' -| 'INDEX' - -IndexKeyTypeOpt ::= - ( 'UNIQUE' | 'SPATIAL' | 'FULLTEXT' )? +ColumnKeywordOpt ::= + 'COLUMN'? -IndexInvisible ::= - 'VISIBLE' -| 'INVISIBLE' +ColumnDef ::= + ColumnName ( Type | 'SERIAL' ) ColumnOptionListOpt -IndexTypeName ::= - 'BTREE' -| 'HASH' -| 'RTREE' +ColumnPosition ::= + ( 'FIRST' | 'AFTER' ColumnName )? ``` ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples diff --git a/sql-statements/sql-statement-alter-database.md b/sql-statements/sql-statement-alter-database.md index e0848ca0344e2..2718c98576797 100644 --- a/sql-statements/sql-statement-alter-database.md +++ b/sql-statements/sql-statement-alter-database.md @@ -8,19 +8,6 @@ aliases: ['/docs/v3.0/sql-statements/sql-statement-alter-database/','/docs/v3.0/ `ALTER DATABASE` is used to specify or modify the default character set and collation of the current database. `ALTER SCHEMA` has the same effect as `ALTER DATABASE`. -<<<<<<< HEAD -======= -## Synopsis - -```ebnf+diagram -AlterDatabaseStmt ::= - 'ALTER' 'DATABASE' DBName? DatabaseOptionList - -DatabaseOption ::= - DefaultKwdOpt ( CharsetKw '='? CharsetName | 'COLLATE' '='? CollationName | 'ENCRYPTION' '='? EncryptionOpt ) -``` - ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples ```sql diff --git a/sql-statements/sql-statement-alter-index.md b/sql-statements/sql-statement-alter-index.md deleted file mode 100644 index bff21e3ff4fca..0000000000000 --- a/sql-statements/sql-statement-alter-index.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: ALTER INDEX -summary: An overview of the usage of ALTER INDEX for the TiDB database. -aliases: ['/docs/dev/sql-statements/sql-statement-alter-index/'] ---- - -# ALTER INDEX - -The `ALTER INDEX` statement is used to modify the visibility of the index to `Visible` or `Invisible`. Invisible indexes are maintained by DML statements, but will not be used by the query optimizer. This is useful in scenarios where you want to double-check before removing an index permanently. - -## Synopsis - -```ebnf+diagram -AlterTableStmt ::= - 'ALTER' IgnoreOptional 'TABLE' TableName ( AlterTableSpecListOpt AlterTablePartitionOpt | 'ANALYZE' 'PARTITION' PartitionNameList ( 'INDEX' IndexNameList )? AnalyzeOptionListOpt ) - -AlterTableSpec ::= - TableOptionList -| 'SET' 'TIFLASH' 'REPLICA' LengthNum LocationLabelList -| 'CONVERT' 'TO' CharsetKw ( CharsetName | 'DEFAULT' ) OptCollate -| 'ADD' ( ColumnKeywordOpt IfNotExists ( ColumnDef ColumnPosition | '(' TableElementList ')' ) | Constraint | 'PARTITION' IfNotExists NoWriteToBinLogAliasOpt ( PartitionDefinitionListOpt | 'PARTITIONS' NUM ) ) -| ( ( 'CHECK' | 'TRUNCATE' ) 'PARTITION' | ( 'OPTIMIZE' | 'REPAIR' | 'REBUILD' ) 'PARTITION' NoWriteToBinLogAliasOpt ) AllOrPartitionNameList -| 'COALESCE' 'PARTITION' NoWriteToBinLogAliasOpt NUM -| 'DROP' ( ColumnKeywordOpt IfExists ColumnName RestrictOrCascadeOpt | 'PRIMARY' 'KEY' | 'PARTITION' IfExists PartitionNameList | ( KeyOrIndex IfExists | 'CHECK' ) Identifier | 'FOREIGN' 'KEY' IfExists Symbol ) -| 'EXCHANGE' 'PARTITION' Identifier 'WITH' 'TABLE' TableName WithValidationOpt -| ( 'IMPORT' | 'DISCARD' ) ( 'PARTITION' AllOrPartitionNameList )? 'TABLESPACE' -| 'REORGANIZE' 'PARTITION' NoWriteToBinLogAliasOpt ReorganizePartitionRuleOpt -| 'ORDER' 'BY' AlterOrderItem ( ',' AlterOrderItem )* -| ( 'DISABLE' | 'ENABLE' ) 'KEYS' -| ( 'MODIFY' ColumnKeywordOpt IfExists | 'CHANGE' ColumnKeywordOpt IfExists ColumnName ) ColumnDef ColumnPosition -| 'ALTER' ( ColumnKeywordOpt ColumnName ( 'SET' 'DEFAULT' ( SignedLiteral | '(' Expression ')' ) | 'DROP' 'DEFAULT' ) | 'CHECK' Identifier EnforcedOrNot | 'INDEX' Identifier IndexInvisible ) -| 'RENAME' ( ( 'COLUMN' | KeyOrIndex ) Identifier 'TO' Identifier | ( 'TO' | '='? | 'AS' ) TableName ) -| LockClause -| AlgorithmClause -| 'FORCE' -| ( 'WITH' | 'WITHOUT' ) 'VALIDATION' -| 'SECONDARY_LOAD' -| 'SECONDARY_UNLOAD' - -IndexInvisible ::= - 'VISIBLE' -| 'INVISIBLE' -``` - -## Examples - -You can modify the visibility of an index using the `ALTER TABLE ... ALTER INDEX ...` statement. - -{{< copyable "sql" >}} - -```sql -CREATE TABLE t1 (c1 INT, UNIQUE(c1)); -ALTER TABLE t1 ALTER INDEX c1 INVISIBLE; -``` - -```sql -Query OK, 0 rows affected (0.02 sec) -``` - -{{< copyable "sql" >}} - -```sql -SHOW CREATE TABLE t1; -``` - -```sql -+-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Table | Create Table - | -+-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| t1 | CREATE TABLE `t1` ( - `c1` int(11) DEFAULT NULL, - UNIQUE KEY `c1` (`c1`) /*!80000 INVISIBLE */ -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin | -+-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -1 row in set (0.00 sec) -``` - -The optimizer cannot use the **invisible index** of `c1`. - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT c1 FROM t1 ORDER BY c1; -``` - -```sql -+-------------------------+----------+-----------+---------------+--------------------------------+ -| id | estRows | task | access object | operator info | -+-------------------------+----------+-----------+---------------+--------------------------------+ -| Sort_4 | 10000.00 | root | | test.t1.c1:asc | -| └─TableReader_8 | 10000.00 | root | | data:TableFullScan_7 | -| └─TableFullScan_7 | 10000.00 | cop[tikv] | table:t1 | keep order:false, stats:pseudo | -+-------------------------+----------+-----------+---------------+--------------------------------+ -3 rows in set (0.00 sec) -``` - -By comparison, `c2` is a **visible index** and can be used by the optimizer. - -{{< copyable "sql" >}} - -```sql -EXPLAIN SELECT c2 FROM t1 ORDER BY c2; -``` - -```sql -+------------------------+----------+-----------+------------------------+-------------------------------+ -| id | estRows | task | access object | operator info | -+------------------------+----------+-----------+------------------------+-------------------------------+ -| IndexReader_13 | 10000.00 | root | | index:IndexFullScan_12 | -| └─IndexFullScan_12 | 10000.00 | cop[tikv] | table:t1, index:c2(c2) | keep order:true, stats:pseudo | -+------------------------+----------+-----------+------------------------+-------------------------------+ -2 rows in set (0.00 sec) -``` - -Even if you use the `USE INDEX` SQL hint to forcibly use indexes, the optimizer still cannot use invisible indexes; otherwise, an error is returned. - -{{< copyable "sql" >}} - -```sql -SELECT * FROM t1 USE INDEX(c1); -``` - -```sql -ERROR 1176 (42000): Key 'c1' doesn't exist in table 't1' -``` - -> **Note:** -> -> "Invisible" here means invisible only to the optimizer. You can still modify or delete invisible indexes. - -{{< copyable "sql" >}} - -```sql -ALTER TABLE t1 DROP INDEX c1; -``` - -```sql -Query OK, 0 rows affected (0.02 sec) -``` - -## MySQL compatibility - -* Invisible indexes in TiDB are modeled on the equivalent feature from MySQL 8.0. -* Similiar to MySQL, TiDB does not permit `PRIMARY KEY` indexes to be made invisible. -* MySQL provides an optimizer switch `use_invisible_indexes=on` to make all invisible indexes _visible_ again. This functionality is not available in TiDB. - -## See also - -* [CREATE TABLE](/sql-statements/sql-statement-create-table.md) -* [CREATE INDEX](/sql-statements/sql-statement-create-index.md) -* [ADD INDEX](/sql-statements/sql-statement-add-index.md) -* [DROP INDEX](/sql-statements/sql-statement-drop-index.md) -* [RENAME INDEX](/sql-statements/sql-statement-rename-index.md) diff --git a/sql-statements/sql-statement-alter-instance.md b/sql-statements/sql-statement-alter-instance.md deleted file mode 100644 index a71c46ef53b77..0000000000000 --- a/sql-statements/sql-statement-alter-instance.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: ALTER INSTANCE -summary: Learn the overview of the `ALTER INSTANCE` usage in TiDB. -aliases: ['/docs/dev/sql-statements/sql-statement-alter-instance/','/docs/dev/reference/sql/statements/alter-instance/'] ---- - -# ALTER INSTANCE - -The `ALTER INSTANCE` statement is used to make changes to a single TiDB instance. Currently, TiDB only supports the `RELOAD TLS` clause. - -## RELOAD TLS - -You can execute the `ALTER INSTANCE RELOAD TLS` statement to reload the certificate ([`ssl-cert`](/tidb-configuration-file.md#ssl-cert)), the key ([`ssl-key`](/tidb-configuration-file.md#ssl-key)), and the CA ([`ssl-ca`](/tidb-configuration-file.md#ssl-ca)) from the original configuration path. - -The newly loaded certificate, key, and CA take effect on the connection that is established after the statement is successfully executed. The connection established before this statement execution is not affected. - -When an error occurs during reloading, by default, this error message is returned and the previous key and certificate continue to be used. However, if you have added the optional `NO ROLLBACK ON ERROR`, when an error occurs during reloading, the error is not returned, and the subsequent requests are handled with the TLS security connection disabled. - -## Syntax diagram - -**AlterInstanceStmt:** - -```ebnf+diagram -AlterInstanceStmt ::= - 'ALTER' 'INSTANCE' InstanceOption - -InstanceOption ::= - 'RELOAD' 'TLS' ('NO' 'ROLLBACK' 'ON' 'ERROR')? -``` - -## Example - -{{< copyable "sql" >}} - -```sql -ALTER INSTANCE RELOAD TLS; -``` - -## MySQL compatibility - -The `ALTER INSTANCE RELOAD TLS` statement only supports reloading from the original configuration path. It does not support dynamically modifying the loading path or dynamically enabling the TLS encrypted connection feature when TiDB is started. This feature is disabled by default when you restart TiDB. - -## See also - -[Enable TLS Between TiDB Clients and Servers](/enable-tls-between-clients-and-servers.md). diff --git a/sql-statements/sql-statement-alter-user.md b/sql-statements/sql-statement-alter-user.md index 6da0612b0490b..f624da8ee7529 100644 --- a/sql-statements/sql-statement-alter-user.md +++ b/sql-statements/sql-statement-alter-user.md @@ -19,19 +19,7 @@ UserSpecList ::= UserSpec ::= Username AuthOption - -Username ::= - StringName ('@' StringName | singleAtIdentifier)? | 'CURRENT_USER' OptionalBraces - -<<<<<<< HEAD -**UserSpec:** - -![UserSpec](/media/sqlgram/UserSpec.png) -======= -AuthOption ::= - ( 'IDENTIFIED' ( 'BY' ( AuthString | 'PASSWORD' HashString ) | 'WITH' StringName ( 'BY' AuthString | 'AS' HashString )? ) )? ``` ->>>>>>> 4c603f53... sql-statements: use EBNF to render syntax diagrams for ADD, ALTER and ANALYZE statements (#4722) ## Examples