Move the docs folder

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/1.about-dml-statements/1.dml-statement-overview.md

@@ -0,0 +1,13 @@
+DML 语句概述 
+=============================
+
+
+
+DML（Data Manipulation Language，数据操作语言）语句可以操作表中的数据，如增加、修改、删除等。
+**说明**
+
+
+
+在 obclient 命令行环境下，可以在"SQL提示符\>"后输入 DML 语句。
+
+DML 语句对数据的修改效果只有在提交事务时才永久生效。一个事务是一序列被 OceanBase 数据库当作整体的多个 SQL 语句，要么全部执行成功，要么全部不成功。单个 DML 语句也可以是一个事务。事务在没有提交之前，还可以回滚事务。

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/1.about-dml-statements/2.insert-statement.md

@@ -0,0 +1,145 @@
+关于 INSERT 语句 
+=================================
+
+
+
+INSERT 语句用来向表中插入行记录。
+
+最简单的 INSERT 语句语法格式如下：
+
+```javascript
+INSERT INTO table_name (list_of_columns) VALUES (list_of_values);
+```
+
+
+
+其中，list_of_columns 指定表的 table_name 列，list_of_values 是 list_of_columns 提到的列的对应值，必须一一对应。因此，在向一个表插入记录之前，需要了解这个表所有的列信息，以及列类型和有效值、是否允许为空等。在 obclient 命令行环境下，可以直接用 DESC 命令查看列属性，如下所示：
+
+```javascript
+obclient> desc ordl;
++----------------+-------------+------+-----+---------+-------+
+| FIELD          | TYPE        | NULL | KEY | DEFAULT | EXTRA |
++----------------+-------------+------+-----+---------+-------+
+| OL_W_ID        | NUMBER(38)  | NO   | PRI | NULL    | NULL  |
+| OL_D_ID        | NUMBER(38)  | NO   | PRI | NULL    | NULL  |
+| OL_O_ID        | NUMBER(38)  | NO   | PRI | NULL    | NULL  |
+| OL_NUMBER      | NUMBER(38)  | NO   | PRI | NULL    | NULL  |
+| OL_DELIVERY_D  | DATE        | YES  | NULL | NULL    | NULL  |
+| OL_AMOUNT      | NUMBER(6,2) | YES  | NULL | NULL    | NULL  |
+| OL_I_ID        | NUMBER(38)  | YES  | NULL | NULL    | NULL  |
+| OL_SUPPLY_W_ID | NUMBER(38)  | YES  | NULL | NULL    | NULL  |
+| OL_QUANTITY    | NUMBER(38)  | YES  | NULL | NULL    | NULL  |
+| OL_DIST_INFO   | CHAR(24)    | YES  | NULL | NULL    | NULL  |
++----------------+-------------+------+-----+---------+-------+
+10 rows in set (0.01 sec)
+```
+
+
+
+在 INSERT 语句中，您不需要知道表的所有列的值，但需要知道所有列属性为 
+
+*NOT* *NULL 的列的值。如果列属性为 NOT NULL 有默认值时，您可以不指定该列的值；如果列为* 
+
+*NULL，您也可以不指定该列的值，OceanBase 会在该列上插入一个 NULL 值。* 
+
+当插入多条件记录时，可以分多条 INSERT 语句，也可以用一个 INSERT 多个 VALUES 语句。
+
+示例：当所有列信息都知道时，使用INSERT语句 
+---------------------------------
+
+如下示例创建有默认值列的表，SQL 插入两笔记录，所有字段信息都有值。
+
+```javascript
+obclient> CREATE TABLE t_insert(
+     id number NOT NULL PRIMARY KEY
+     , name varchar(10) NOT NULL, value number
+     , gmt_create DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+ );
+Query OK, 0 rows affected (0.07 sec)
+
+obclient> INSERT INTO t_insert(id, name, value, gmt_create)
+ values(1,'CN',10001, current_timestamp);
+Query OK, 1 row affected (0.01 sec)
+```
+
+
+
+示例：当不是所有列信息都知道时，使用INSERT语句 
+-----------------------------------
+
+下面 SQL 插入两笔记录，gmt_create 字段没有提供。两笔记录使用一个 INSERT 多个 VALUES 子句。
+
+```javascript
+obclient> INSERT INTO t_insert(id, name, value) 
+VALUES (2,'US', 10002) ,(3,'EN', 10003);
+Query OK, 2 rows affected (0.00 sec)
+Records: 2  Duplicates: 0  Warnings: 0
+```
+
+
+
+示例：使用INSERT语句违反唯一约束冲突 
+------------------------------
+
+当表上有唯一性约束的时候，插入相同的记录，数据库会报错。
+
+```javascript
+obclient> INSERT INTO t_insert(id, name, value) 
+VALUES (3,'UK', 10003)
+     ,(4, 'JP', 10004);
+ERROR 1062 (23000): Duplicate entry '3' for key 'PRIMARY'
+```
+
+
+
+这个报错可以通过 INSERT IGNORE INTO、MERGE INTO、INSERT INTO ON DUPLICATE KEY UPDATE 避免。
+
+#### 关于INSERT IGNORE INTO 语句 
+
+下面示例是 MySQL 租户下使用 INSERT IGNORE INTO 避免约束冲突，IGNORE 关键字可以忽略由于约束冲突导致的 INSERT 失败的影响。
+
+```javascript
+obclient> INSERT IGNORE INTO t_insert(id, name, value) 
+VALUES (3,'UK', 10003) ,(4, 'JP', 10004);
+Query OK, 1 row affected (0.00 sec)
+
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| id | name | value | gmt_create          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-03 16:05:45 |
+|  2 | US   | 10002 | 2020-04-03 16:05:54 |
+|  3 | EN   | 10003 | 2020-04-03 16:05:54 |
+|  4 | JP   | 10004 | 2020-04-03 16:06:08 |
++----+------+-------+---------------------+
+4 rows in set (0.00 sec)
+```
+
+
+
+示例：使用查询语句充当 INSERT 的 values 子句 
+---------------------------------------
+
+当需要备份一个表的备份或者全部记录时，可以使用 `INSERT INTO ... SELECT ... FROM` 语句。
+
+```javascript
+obclient> create table ware_bak(
+    w_id int
+    , w_ytd decimal(12,2)
+    , w_tax decimal(4,4)
+    , w_name varchar(10)
+    , w_street_1 varchar(20)
+    , w_street_2 varchar(20)
+    , w_city varchar(20)
+    , w_state char(2)
+    , w_zip char(9)
+    , primary key(w_id)
+);
+Query OK, 0 rows affected (0.17 sec)
+
+obclient> insert into ware_bak select * from ware;
+Query OK, 2 rows affected (0.02 sec)
+Records: 2  Duplicates: 0  Warnings: 0
+```
+
+

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/1.about-dml-statements/3.about-update-statements.md

@@ -0,0 +1,107 @@
+关于 UPDATE 语句 
+=================================
+
+
+
+UPDATE语句用来更新表的行记录。
+
+简单的UPDATE语句语法格式如下：
+
+```javascript
+UPDATE table_name
+SET column_name = value [, column_name = value]...
+[ WHERE condition ];
+```
+
+
+
+其中，column_name 是要更新的列，等号后面的 value 是要更新的目标值，必须符合列的类型定义。WHERE 条件子句指定要更新的行记录必须满足的条件，没有 WHERE 条件子句就是更新表对应列的所有记录。
+
+示例：更新所有记录 
+------------------
+
+```javascript
+obclient> update t_insert set value=value+1 ;
+Query OK, 4 rows affected (0.00 sec)
+Rows matched: 4  Changed: 4  Warnings: 0
+
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| id | name | value | gmt_create          |
++----+------+-------+---------------------+
+|  1 | CN   | 10002 | 2020-04-03 17:18:06 |
+|  2 | US   | 10003 | 2020-04-03 17:18:47 |
+|  3 | EN   | 10004 | 2020-04-03 17:18:47 |
+|  4 | JP   | 10005 | 2020-04-03 17:28:21 |
++----+------+-------+---------------------+
+4 rows in set (0.00 sec)
+```
+
+
+
+不带条件更新的时候，如果记录数达到几十万或者几百万，会有大事务产生，可能会失败。所以 UPDATE 要注意控制事务不要太大。
+
+示例：更新部分记录，违反约束报错 
+-------------------------
+
+```javascript
+obclient> create unique index uk_name on t_insert(name);
+Query OK, 0 rows affected (1.99 sec)
+
+obclient> update t_insert set name='US' where id=3;
+ERROR 1062 (23000): Duplicate entry 'US' for key 'uk_name'
+```
+
+
+
+除了显式的 UPDATE 语句外，还有几类语句也可以更新数据。比如说 INSERT 因为约束冲突失败的时候，可以使用 ON DUPCLICATE KEY UPDATE 子句转变为 UPDATE 语句更新相关字段。
+
+#### 关于 INSERT ON DUPLICATE KEY UPDATE 子句 
+
+使用 ON DUPLICATE KEY UPDATE 子句时，要求表上面要有主键或唯一约束（索引）。
+
+**示例：使用** **INSERT ON DUPLICATE KEY UPDATE** **避免数据插入冲突** 
+
+```javascript
+obclient> INSERT INTO t_insert(id, name, value) VALUES (3,'UK', 10003);
+ERROR 1062 (23000): Duplicate entry '3' for key 'PRIMARY'
+
+obclient> INSERT INTO t_insert(id, name, value) VALUES (3,'UK', 10003)
+  ON DUPLICATE KEY UPDATE name='UK', value=10003 ;
+Query OK, 2 rows affected (0.01 sec)
+
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| id | name | value | gmt_create          |
++----+------+-------+---------------------+
+|  1 | CN   | 10002 | 2020-04-03 18:05:45 |
+|  2 | US   | 10003 | 2020-04-03 18:05:54 |
+|  3 | UK   | 10003 | 2020-04-03 18:05:54 |
+|  4 | JP   | 10005 | 2020-04-03 18:06:08 |
++----+------+-------+---------------------+
+4 rows in set (0.00 sec)
+```
+
+
+
+#### 关于 SELECT ... FOR UPDATE 子句 
+
+使用 SELECT ... FOR UPDATE 可以在读取记录的时候就对记录加锁，避免其他 DML 语句对该笔记录进行同时修改，这种设计通常也称为"悲观锁策略"。
+
+**示例：使用** **SELECT ... FOR UPDATE 先锁定记录后修改** 
+
+```javascript
+obclient> select id,name,value from t_insert where id=2 for update;
++----+------+-------+
+| id | name | value |
++----+------+-------+
+|  2 | US   | 10003 |
++----+------+-------+
+1 row in set (0.01 sec)
+
+obclient> update t_insert set value=value+100 where id=2;
+Query OK, 1 row affected (0.00 sec)
+Rows matched: 1  Changed: 1  Warnings: 0
+```
+
+

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/1.about-dml-statements/4.about-the-delete-statement.md

@@ -0,0 +1,29 @@
+关于 DELETE 语句 
+=================================
+
+
+
+DELETE 语句用来删除表中的记录。
+
+简单的 DELETE 语句格式如下：
+
+```javascript
+DELETE FROM table_name [ WHERE condition ] ;
+```
+
+
+
+其中，WHERE 条件子句是可选的，如果没有提供就全表删除。如果表记录数多达几百万以上，会形成大事务，可能会有性能问题。建议带上 WHERE 条件分批删除；或者使用 TRUNCATE TABLE 语句。
+
+示例：删除表中数据 
+------------------
+
+```javascript
+delete from ordr where o_w_id=2;
+
+delete from ordr ;
+```
+
+
+
+除了 DELETE 语句外，REPLACE INTO 语句也可能会删除数据。

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/1.about-dml-statements/5.replace-into-statements.md

@@ -0,0 +1,43 @@
+关于 REPLACE INTO 语句 
+=======================================
+
+
+
+REPLACE INTO 语句会判断行记录是否存在（根据主键索引或唯一索引判断）。如果不存在，则插入记录；如果存在，则删除已有记录，并插入新行记录。目标表建议有主键或者唯一索引，否则容易插入重复的记录。
+
+示例如下：
+
+```javascript
+obclient> CREATE TABLE t_replace(
+     id number NOT NULL PRIMARY KEY
+     , name varchar(10) NOT NULL
+     , value number
+     ,gmt_create timestamp NOT NULL DEFAULT current_timestamp
+ );
+Query OK, 0 rows affected (0.06 sec)
+
+obclient> REPLACE INTO t_replace values(1,'CN',2001, current_timestamp ());
+Query OK, 1 row affected (0.00 sec)
+
+obclient> REPLACE INTO t_replace
+     SELECT id,name,value,gmt_create  FROM t_insert;
+Query OK, 5 rows affected (0.00 sec)
+Records: 4  Duplicates: 1  Warnings: 0
+
+obclient> REPLACE INTO t_replace(id, name, value)  values(6,'DE',20006);
+Query OK, 1 row affected (0.01 sec)
+
+obclient> select * from t_replace;
++----+------+-------+---------------------+
+| id | name | value | gmt_create          |
++----+------+-------+---------------------+
+|  1 | CN   | 10002 | 2020-04-03 18:05:45 |
+|  2 | US   | 10103 | 2020-04-03 18:05:54 |
+|  3 | UK   | 10003 | 2020-04-03 18:05:54 |
+|  4 | JP   | 10005 | 2020-04-03 18:06:08 |
+|  6 | DE   | 20006 | 2020-04-03 18:09:19 |
++----+------+-------+---------------------+
+5 rows in set (0.01 sec)
+```
+
+

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/2.about-transactional-control-statements.md

@@ -0,0 +1,41 @@
+关于事务控制语句 
+=============================
+
+
+
+事务指的是一序列 SQL 语句，OceanBase 将这组 SQL 语句当作一个整体，要么全部执行成功，要么全部不成功；不存在部分 SQL 语句执行成功，或者部分 SQL 没有执行成功的情形。
+
+举个例子，当一个客户下单购买了一批商品时，订单表会新增几行记录购买信息和金额，库存表会更新这批商品的库存数量（扣减库存）。应用程序中为这个业务做设计时，就需要把 INSERT 和 UPDATE 语句放到一个事务里。
+
+通常事务中的 SQL 会包含 DML 语句，也会包含查询语句。如果一个事务中的 SQL 只有查询语句，这个事务通常称为只读事务。
+
+基本的事务控制语句有：
+
+* BEGIN，显式开启一个事务。这个命令是可选的，如果租户会话的参数 autocommit 值是 off (关闭自动提交)，就不需要显式发出这个命令；如果参数值是 on (开启自动提交)，那每条 SQL 就是一个独立的事务；如果要多个 SQL 组成一个事务，需要显式发起 BEGIN 命令。
+
+  
+
+* SAVEPOINT，在事务过程中标记一个"保存点"，事务可以事后选择回滚到这个点。保存点是可选的，一个事务过程中也可以有多个保存点。
+
+  
+
+* COMMIT，结束当前事务，让事务所有修改持久化并生效，清除所有保存点和释放事务持有的锁。
+
+  
+
+* ROLLBACK，回滚整个事务已做的修改或者只回滚某个保存点之后事务已做的修改，清除回滚部分包含的所有保存点和释放事务持有的锁。
+
+  
+
+
+
+
+在 obclient 命令环境下，可以在 SQL 提示符后发起事务控制命令，也可以修改会话级别的 autocommit 参数。如果是修改租户级别的 autocommit 参数，需要断开会话重新连接才会生效。
+**说明**
+
+
+
+如果会话的 autocommit 参数值是 off 时，并且没有显式的提交事务，程序异常中断时，OceanBase 数据库会自动回滚最后一个未提交的事务。
+
+建议显式的提交事务或者回滚事务。
+

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/3.submit-transaction-3.md

@@ -0,0 +1,79 @@
+提交事务 
+=========================
+
+
+
+提交一个事务会让事务的修改持久化生效，清除保存点并释放事务所持有的所有锁。
+
+要显式的提交事务，使用 COMMIT 语句或者使用提交按钮（在图形化客户端工具中）。
+**说明**
+
+
+
+OceanBase 会在 DDL 语句前和后隐式的发起一个 COMMIT 语句，这个也会提交事务。
+
+* 如果使用 BEGIN 开启一个事务，执行 DML 语句后需要使用 COMMIT 提交事务。
+
+  在您提交事务之前：
+  * 您的修改只对当前会话可见，对其他数据库会话是不可见的。
+
+    
+  
+  * 您的修改没有持久化，所以不是最终的，可以用 ROLLBACK 语句回滚这些修改。
+
+    
+  
+
+  
+
+  在您提交事务之后：
+  * 您的修改对所有数据库会话可见。
+
+    
+  
+  * 您的修改持久化成功，不可以用 ROLLBACK 语句回滚这些修改。
+
+    
+  
+
+  
+
+* 如果不显示地使用 BEGIN 开启事务，则一条 SQL 就是一个事务，不再需要提交事务。SQL 执行后您的修改即持久化成功，不可以用 ROLLBACK 语句回滚这些修改。
+
+  
+
+
+
+
+示例：提交事务 
+----------------
+
+```javascript
+obclient> begin;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> insert into t_insert(id,name) values(4,'JP');
+Query OK, 1 row affected (0.01 sec)
+
+obclient> commit;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> ^Bye
+
+[qing.meiq@h07g12088.sqa.eu95 /home/qing.meiq/bmsql]
+$obclient -h192.168.1.101 -utpcc@obbmsql#obdemo -P2883 -p123456  TPCC
+Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| ID | NAME | VALUE | GMT_CREATE          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-02 17:52:31 |
+|  2 | US   | 10002 | 2020-04-02 17:52:38 |
+|  3 | EN   | 10003 | 2020-04-02 17:52:38 |
+|  4 | JP   |  NULL | 2020-04-02 17:53:34 |
++----+------+-------+---------------------+
+4 rows in set (0.00 sec)
+```
+
+

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/4.roll-back-transactions-3.md

@@ -0,0 +1,103 @@
+回滚事务 
+=========================
+
+
+
+回滚一个事务指将事务的修改全部撤销。可以回滚当前整个未提交事务，也可以回滚到事务中任意一个保存点。如果要回滚到某个保存点，必须结合使用 ROLLBACK 和 TO SAVEPOINT 语句。
+
+如果回滚整个事务：
+
+* 事务会结束。
+
+  
+
+* 所有的修改会被丢弃。
+
+  
+
+* 清除所有保存点。
+
+  
+
+* 释放事务持有的所有锁。
+
+  
+
+
+
+
+如果回滚到某个保存点：
+
+* 事务不会结束。
+
+  
+
+* 保存点之前的修改被保留，保存点之后的修改被丢弃。
+
+  
+
+* 清除保存点之后的保存点（不包括保存点自身）。
+
+  
+
+* 释放保存点之后事务持有的所有锁。
+
+  
+
+
+
+
+
+
+示例：ROLLBACK 回滚事务的全部修改 
+------------------------------
+
+```javascript
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| ID | NAME | VALUE | GMT_CREATE          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-02 17:52:31 |
+|  2 | US   | 10002 | 2020-04-02 17:52:38 |
+|  3 | EN   | 10003 | 2020-04-02 17:52:38 |
++----+------+-------+---------------------+
+3 rows in set (0.00 sec)
+
+obclient> begin;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> insert into t_insert(id, name, value) values(4,'JP',10004);
+Query OK, 1 row affected (0.00 sec)
+
+obclient> insert into t_insert(id, name, value) values(5,'FR',10005),(6,'RU',10006);
+Query OK, 2 rows affected (0.00 sec)
+Records: 2  Duplicates: 0  Warnings: 0
+
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| ID | NAME | VALUE | GMT_CREATE          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-02 17:52:31 |
+|  2 | US   | 10002 | 2020-04-02 17:52:38 |
+|  3 | EN   | 10003 | 2020-04-02 17:52:38 |
+|  4 | JP   |  NULL | 2020-04-02 17:53:34 |
+|  5 | FR   | 10005 | 2020-04-02 17:54:53 |
+|  6 | RU   | 10006 | 2020-04-02 17:54:53 |
++----+------+-------+---------------------+
+6 rows in set (0.00 sec)
+
+obclient> rollback;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| ID | NAME | VALUE | GMT_CREATE          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-02 17:52:31 |
+|  2 | US   | 10002 | 2020-04-02 17:52:38 |
+|  3 | EN   | 10003 | 2020-04-02 17:52:38 |
++----+------+-------+---------------------+
+3 rows in set (0.00 sec)
+```
+
+

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/5.transaction-savepoints.md

@@ -0,0 +1,145 @@
+事务保存点 
+==========================
+
+
+
+SAVEPOINT 语句可以在事务过程中标记一个"保存点"，事务可以选择回滚到这个点。保存点是可选的，一个事务过程中也可以有多个保存点。
+
+示例：将一个事务回滚到一个保存点 
+-------------------------
+
+下面示例展示了一个事务中包含多个 DML 语句和多个保存点，然后回滚到其中一个保存点，只丢弃了保存点后面的那部份修改。
+
+* 查看表当前记录
+
+  
+
+
+
+
+```javascript
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| id | name | value | gmt_create          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-03 16:05:45 |
+|  2 | US   | 10002 | 2020-04-03 16:05:54 |
+|  3 | UK   | 10003 | 2020-04-03 16:05:54 |
++----+------+-------+---------------------+
+3 rows in set (0.00 sec)
+```
+
+
+
+* 开启一个事务，设置多个保存点信息。
+
+  
+
+
+
+
+```javascript
+obclient> set session autocommit=off;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> begin;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> insert into t_insert(id, name) values(6,'FR');
+Query OK, 1 row affected (0.00 sec)
+
+obclient> savepoint fr;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> insert into t_insert(id, name) values(7,'RU');
+Query OK, 1 row affected (0.00 sec)
+
+obclient> savepoint ru;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> insert into t_insert(id, name) values(8,'CA');
+Query OK, 1 row affected (0.00 sec)
+
+obclient> savepoint ca;
+Query OK, 0 rows affected (0.00 sec)
+```
+
+
+
+* 当前会话能看到事务未提交的所有修改。
+
+  
+
+
+
+
+```javascript
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| id | name | value | gmt_create          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-03 16:05:45 |
+|  2 | US   | 10002 | 2020-04-03 16:05:54 |
+|  3 | UK   | 10003 | 2020-04-03 16:05:54 |
+|  6 | FR   |  NULL | 2020-04-03 16:26:22 |
+|  7 | RU   |  NULL | 2020-04-03 16:26:32 |
+|  8 | CA   |  NULL | 2020-04-03 16:26:42 |
++----+------+-------+---------------------+
+6 rows in set (0.00 sec)
+```
+
+
+
+* 回滚事务到其中一个保存点。
+
+  
+
+
+
+
+```javascript
+obclient> rollback to savepoint ru;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| id | name | value | gmt_create          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-03 16:05:45 |
+|  2 | US   | 10002 | 2020-04-03 16:05:54 |
+|  3 | UK   | 10003 | 2020-04-03 16:05:54 |
+|  6 | FR   |  NULL | 2020-04-03 16:26:22 |
+|  7 | RU   |  NULL | 2020-04-03 16:26:32 |
++----+------+-------+---------------------+
+5 rows in set (0.01 sec)
+```
+
+
+
+* 提交事务，确认表最新修改包含保存点之前的修改。
+
+  
+
+
+
+
+```javascript
+obclient> commit;
+Query OK, 0 rows affected (0.00 sec)
+obclient> select * from t_insert;
++----+------+-------+---------------------+
+| id | name | value | gmt_create          |
++----+------+-------+---------------------+
+|  1 | CN   | 10001 | 2020-04-03 16:05:45 |
+|  2 | US   | 10002 | 2020-04-03 16:05:54 |
+|  3 | UK   | 10003 | 2020-04-03 16:05:54 |
+|  6 | FR   |  NULL | 2020-04-03 16:26:22 |
+|  7 | RU   |  NULL | 2020-04-03 16:26:32 |
++----+------+-------+---------------------+
+5 rows in set (0.00 sec)
+
+obclient>
+```
+
+
+

docs/docs-cn/7.developer-guide-1/3.about-dml-statements-and-transactions/6.about-transaction-timeout.md

@@ -0,0 +1,173 @@
+关于事务超时 
+===========================
+
+
+
+OceanBase 为了避免事务长时间不提交持有锁影响其他会话，设计了两个超时逻辑。一个是事务空闲超时，一个是事务未提交超时。分别由租户变量 ob_trx_idle_timeout 和 ob_trx_timeout 控制，默认值分别是 120 秒和 100 秒。通常只会有一个超时机制被触发。
+**说明**
+
+
+
+建议变量 ob_trx_idle_timeout 使用默认值。
+
+```javascript
+obclient> show variables where variable_name in ('ob_trx_idle_timeout','ob_trx_timeout');
++---------------------+-----------+
+| VARIABLE_NAME       | VALUE     |
++---------------------+-----------+
+| ob_trx_idle_timeout | 120000000 |
+| ob_trx_timeout      | 100000000 |
++---------------------+-----------+
+2 rows in set (0.00 sec)
+```
+
+
+
+
+
+关于事务空闲超时 
+-----------------
+
+OceanBase 的事务空闲时间超过一段时间还没有提交时，会自动断开连接并回滚事务，此时会话需要重新连接。
+
+会话事务空闲超时时间阈值由租户变量 ob_trx_idle_timeout 控制，这个参数值建议使用默认值 120 秒，实际空闲会话断开的时间会是在 \[100s, 100s + ob_trx_idle_timeout \] 之间。
+
+#### 示例：事务空闲超时报错 
+
+下面示例先设置事务空闲超时时间为 120 秒，事务未提交超时时间为 1000 秒。当事务空闲时间超过 120 秒后，连接会被自动断开，事务也自动被 ROLLBACK 了。
+
+```javascript
+obclient> DROP TABLE IF EXISTS t_insert; 
+Query OK, 0 rows affected (0.01 sec)
+
+obclient> CREATE TABLE t_insert(
+    id bigint NOT NULL PRIMARY KEY auto_increment
+    , name varchar(10) NOT NULL
+    , value bigint
+    ,gmt_create timestamp NOT NULL DEFAULT current_timestamp
+);
+Query OK, 0 rows affected (0.05 sec)
+
+obclient> INSERT INTO t_insert(name, value) values('CN',NULL),('UK',NULL),('US',NULL);
+Query OK, 3 rows affected (0.00 sec)
+Records: 3  Duplicates: 0  Warnings: 0
+
+obclient> select now(), * from t_insert t;
++---------------------+----+------+-------+---------------------+
+| now()               | id | name | value | gmt_create          |
++---------------------+----+------+-------+---------------------+
+| 2020-04-03 16:54:51 |  1 | CN   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 16:54:51 |  2 | UK   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 16:54:51 |  3 | US   |  NULL | 2020-04-03 16:54:49 |
++---------------------+----+------+-------+---------------------+
+3 rows in set (0.00 sec)
+
+obclient> set session ob_trx_timeout=1000000000;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> set session ob_trx_idle_timeout=120000000;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> begin;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> update t_insert set gmt_create=now() where id=3;
+Query OK, 1 row affected (0.00 sec)
+Rows matched: 1  Changed: 1  Warnings: 0
+
+obclient> select now(), t.* from t_insert t;
++---------------------+----+------+-------+---------------------+
+| now()               | id | name | value | gmt_create          |
++---------------------+----+------+-------+---------------------+
+| 2020-04-03 16:55:30 |  1 | CN   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 16:55:30 |  2 | UK   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 16:55:30 |  3 | US   |  NULL | 2020-04-03 16:55:25 |
++---------------------+----+------+-------+---------------------+
+3 rows in set (0.00 sec)
+
+<<等 100 秒不操作>>
+
+obclient> select now(), t.* from t_insert t;
+ERROR-02013: Lost connection to MySQL server during query
+obclient> select now(), * from t_insert t;
+ERROR-02006: MySQL server has gone away
+No connection. Trying to reconnect...
+Connection id:    53246
+Current database: TPCC
+
++---------------------+----+------+-------+---------------------+
+| now()               | id | name | value | gmt_create          |
++---------------------+----+------+-------+---------------------+
+| 2020-04-03 16:57:41 |  1 | CN   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 16:57:41 |  2 | UK   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 16:57:41 |  3 | US   |  NULL | 2020-04-03 16:54:49 |
++---------------------+----+------+-------+---------------------+
+3 rows in set (0.00 sec)
+```
+
+
+
+
+
+关于事务未提交超时 
+------------------
+
+OceanBase 的事务持续时间超过一段时间还没有提交，会报超时错误。此时会话需要明确发出 ROLLBACK 命令才可以继续在会话里执行 SQL。
+
+会话事务的未提交超时时间阈值是由租户变量 ob_trx_timeout 控制。
+
+#### 示例：事务未提交超时报错 
+
+下面示例先设置事务空闲超时时间为 120 秒，事务超时时间为 100 秒。当一个事务未提交时间持续到 100 秒时，事务内部状态就变为超时状态，同时锁会释放。此后会话需要显式发出 ROLLBACK 语句。
+
+```javascript
+obclient> set session ob_trx_timeout=100000000;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> set session ob_trx_idle_timeout=120000000;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> begin;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> update t_insert set gmt_create=sysdate() where id=3;
+Query OK, 1 row affected (0.00 sec)
+Rows matched: 1  Changed: 1  Warnings: 0
+
+obclient> select now(), t.* from t_insert t ;
++---------------------+----+------+-------+---------------------+
+| now()               | id | name | value | gmt_create          |
++---------------------+----+------+-------+---------------------+
+| 2020-04-03 16:59:56 |  1 | CN   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 16:59:56 |  2 | UK   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 16:59:56 |  3 | US   |  NULL | 2020-04-03 16:59:51 |
++---------------------+----+------+-------+---------------------+
+3 rows in set (0.00 sec)
+
+<<等 120 秒不操作>>
+
+obclient> select now(), t.* from t_insert t ;
+ERROR-00600: internal error code, arguments: -6210, Transaction is timeout
+obclient> commit;
+ERROR-00600: internal error code, arguments: -6210, Transaction is timeout
+obclient> rollback;
+Query OK, 0 rows affected (0.00 sec)
+
+obclient> select now(), t.* from t_insert t ;
++---------------------+----+------+-------+---------------------+
+| now()               | id | name | value | gmt_create          |
++---------------------+----+------+-------+---------------------+
+| 2020-04-03 17:04:13 |  1 | CN   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 17:04:13 |  2 | UK   |  NULL | 2020-04-03 16:54:49 |
+| 2020-04-03 17:04:13 |  3 | US   |  NULL | 2020-04-03 16:54:49 |
++---------------------+----+------+-------+---------------------+
+3 rows in set (0.00 sec)
+```
+
+
+**说明**
+
+
+
+建议不要将事务未提交超时参数设置小于 1 秒。
+