腾讯云数据库TDSQL MySQL版开发指南（三）

版本日期：2024.03（最新版本以腾讯云官网产品文档为准，本链接为2024年3月版）

版权声明

本文档著作权归腾讯云计算（北京）有限责任公司（以下简称“腾讯云”）单独所有，未经腾讯云事先书面许可，任何主体不得以任何方式或理由使用本文档，包括但不限于复制、修改、传播、公开、剽窃全部或部分本文档内容。

本文档及其所含内容均属腾讯云内部资料，并且仅供腾讯云指定的主体查看。如果您非经腾讯云授权而获得本文档的全部或部分内容，敬请予以删除，切勿以复制、披露、传播等任何方式使用本文档或其任何内容，亦请切勿依本文档或其任何内容而采取任何行动。

免责声明

本文档旨在向客户介绍本文档撰写时，腾讯云相关产品、服务的当时的整体概况，部分产品或服务在后续可能因技术调整或项目设计等任何原因，导致其服务内容、标准等有所调整。因此，本文档仅供参考，腾讯云不对其准确性、适用性或完整性等做任何保证。您所购买、使用的腾讯云产品、服务的种类、内容、服务标准等，应以您和腾讯云之间签署的合同约定为准，除非双方另有约定，否则，腾讯云对本文档内容不做任何明示或默示的承诺或保证。

常用 DML

select

建议带上 shardkey 字段，proxy 根据该字段的 hash 值直接将 SQL 请求路由至对应的数据库实例进行处理；否则就需要发送给集群中所有的数据库实例执行，然后 proxy 根据数据库返回的结果集进行聚合，影响执行效率：

mysql> select * from test1 where a=2;

+------+------+---------+

| a | b | c |

+------+------+---------+

| 2 | 3 | record2 |

| 2 | 4 | record3 |

+------+------+---------+

2 rows in set (0.00 sec)

insert/replace

字段必须包含 shardkey，否则会拒绝执行该 SQL，因为 proxy 不知道将该 SQL 发往哪个后端数据库：

mysql> insert into test1 (b,c) values(4,"record3");

ERROR 810 (HY000): Proxy ERROR:sql is too complex,need to send to only noshard table.

Shard table insert must has field spec

mysql> insert into test1 (a,c) values(4,"record3");

Query OK, 1 row affected (0.01 sec)

delete/update

使用分表时，为安全考虑，执行该类 SQL 时，必须带有 where 条件，否则拒绝执行该 SQL 命令：

mysql> delete from test1;

ERROR 810 (HY000): Proxy ERROR:sql is too complex,need to send to only noshard table.

Shard table delete/update must have a where clause

mysql> delete from test1 where a=1;

Query OK, 1 row affected (0.01 sec)

读写分离

TDSQL MySQL版 实例支持下列几种模式的读写分离：

• 通过增加 slave 注释标记，即在 SQL 中添加 /*slave*/ 这样的标记，并且 mysql 后面增加 -c 参数来解析注释 mysql -c -e "/*slave*/sql"，该 SQL 会发送给备机。

支持 /*slave:slaveonly*/、 /*slave:20*/、 /*slave:slaveonly,20*/这几种形式，数值表示 slave 应该满足的延迟，slaveonly 表示在没有符合条件的 slave 时，不会将查询发送给主节点。

//主机读//

select * from emp order by sal，deptno desc；

//从机读//

/*slave*/ select * from emp order by sal，deptno desc；

• 由只读账号发送的请求会根据配置的属性发给备机。 

分布式事务

由于事务操作的数据通常跨多个物理节点，在分布式数据库中，类似方案即称为分布式事务。 TDSQL MySQL版 支持普通分布式事务协议和 XA 分布式事务协议。TDSQL MySQL版（内核5.7或以上版本）默认支持分布式事务，且对客户端透明，像使用单机事务一样方便。 TDSQL MySQL版 分布式事务采用两阶段提交算法（2PC）保证事务的原子性（Atomicity）和一致性（Consistency），隔离级别配置为 Read committed、Repeatable read 或 Serializable。

普通分布式事务

begin; # 开启事务

... # 跨 set 的增删改查等非 DDL 操作

commit; # 提交事务

XA 分布式事务

XA 分布式事务是指跨实例的事务：

xa begin ''; # 开启 XA 事务，事务标识由系统内部生成，因此传入空字符串

... # 跨 set 的增删改查等非 DDL 操作

select gtid(); # 获取当前 XA 事务的标识，下面假定为'xid'

xa prepare 'xid'; # 准备事务

xa commit/rollback 'xid'; # 提交或回滚事务

新增事务接口

• select gtid() ：获取当前分布式事务的全局唯一标识。如果为空，则该事务不是分布式事务。
• 普通分布式事务标识的格式为：‘网关id’-‘proxy随机值’-‘序列号’-‘时间戳’-‘分区号’，例如 c46535fe-b6-dd-595db6b8-25。
• XA 分布式事务标识的格式为：‘ex’-‘网关id’-‘proxy随机值’-‘序列号’-‘时间戳’-‘分区号’，例如 ex-c46535fe-b6-dd-595db6b8-25。
• select gtid_state(“当前分布式事务的全局唯一标识”)：在事务提交异常之后（默认3秒后）用来获取事务的状态。可能的结果有：
• COMMIT：标识该事务已经或者最终会被提交。
• ABORT：标识该事务最终会被回滚。
• 空：由于事务的状态会在一个小时之后清除，因此有以下两种可能：
  • 一个小时之后查询，标识事务状态已经清除,
  • 一个小时以内查询，标识事务最终会被回滚。
• xa boost ‘当前分布式事务的全局唯一标识’ ：普通事务提交（commit）发送异常之后，事务在一段时间内（默认30秒）由后台组件自动提交或者回滚掉。如果用户不愿意等待这么长的时间，可以反复调用该接口，促使系统及时地提交或回滚掉事务。该接口会返回事务的状态，即提交或者回滚。
• xa lockwait：显示当前分布式事务的等待关系。用户可以通过 dot 工具，将其转化为图片。 
• xa show：显示当前 proxy 上处于活跃状态的事务。

建表

建分表

分表创建时必须在最后面指定分表键（shardkey）的值，该值为表中的一个字段名字，会用于后续 SQL 的路由选择：

mysql> create table test1 ( a int, b int, c char(20),primary key (a,b),unique key u_1(a,c) ) shardkey=a;

Query OK, 0 rows affected (0.07 sec)

在分布式实例中，shardkey 对应后端数据库的分区字段，因此每一个唯一索引和主键都必须要包含这个 shardkey，否则无法创建表。 场景：存在多个唯一索引时报错。

mysql> create table test1 ( a int, b int, c char(20),primary key (a,b),unique key u_1(a,c),unique key u_2(b,c) ) shardkey=a;

此时有一个唯一索引u_2不包含 shardkey，无法创建表，会报如下错误：

ERROR 1105 (HY000): A UNIQUE INDEX must include all columns in the table's partitioning function

因为主键索引或者 unique key 索引意味着需要全局唯一，而要实现全局唯一索引，则必须包含 shardkey 字段。

除上面的限制外，shardkey 字段还有如下要求：

• shardkey 字段的类型必须是 int、bigint、smallint、char、varchar。
• shardkey 字段类型为 char、varchar 时需定义字段长度。
• shardkey 字段的值不能有中文，proxy 不会转换字符集，因此不同字符集可能会路由到不同的分区。
• 不能 update shardkey 字段的值。
• shardkey=a 放在 SQL 的最后面。
• 访问数据尽量都带上 shardkey 字段，非强制要求，但是不带 shardkey 的 SQL 会路由到所有节点，消耗较多资源。

另外，创建表的时候，可以使用自增序列作为某一列的默认值，并把这一列设置为主键。

CREATE TABLE test2(column1 INT,column2 INT,column3 INT AUTO_INCREMENT,PRIMARY KEY(column3)) AUTO_INCREMENT=5 shardkey=column3;

插入数据时，设置为自增序列的列插入Null值。

INSERT INTO test2(column1,column2,column3) VALUES(0,0,NULL);

建广播表

支持建小表（广播表），此时该表在所有 set 中都是全量数据，主要方便于跨 set 的 join 操作，同时通过分布式事务保证修改操作的原子性，使得所有 set 的数据完全一致。

mysql> create table global_table ( a int, b int key) shardkey=noshardkey_allset;

Query OK, 0 rows affected (0.06 sec)

建单表

支持建立普通的表，语法和 MySQL 完全一致，此时该表的数据全量存在第一个 set 中，所有该类型的表都放在第一个 set 中：

mysql> create table noshard_table ( a int, b int key);

Query OK, 0 rows affected (0.02 sec)

连接保护

连接保护用于 proxy 与后端数据库连接断开时（如后端数据库发生了异常，但异常未影响 proxy），保持客户端和 proxy 之间的连接不断开。

proxy 正在执行 SQL 时，如果与数据库的连接断开，则 proxy 断开与该 SQL 相关的所有连接（除 proxy 与客户端之间的连接），并告知用户错误：

ER_PROXY_TRANSACTION_ERROR // 在事务中

ER_PROXY_CONN_BROKEN_ERROR // 非事务中

处理方式

• 如果 proxy 与后端数据库连接断开时，用户 session 处于普通事务中，处理如下（图中错误码均为 ER_PROXY_TRANSACTION_ERROR）： 
• 如果 proxy 与后端数据库连接断开时，用户正处于XA 事务中，处理如下（图中错误码均为 ER_PROXY_TRANSACTION_ERROR）： 

超时配置

用户在事务中 proxy 与后端数据库发生连接断开事件，如果用户在超时之前还没有回滚事务，则 proxy 断开与用户的连接。

超时参数在 proxy 配置文件中为：

<server_close timeout="60"/>

保留关键字

此文章将列出 TDSQL MySQL 版当前所涉及的保留关键字，在SQL中使用时需添加 ‘’ 才能被 Proxy 解析。

主要保留关键字变更记录

更早的保留关键字列表

&&, <, <=, <>, !=, =, >, >=, <<, >>, <=>, ACCESSIBLE, ACTION, ADD, ADMIN, AFTER, AGAINST, AGGREGATE, ALL, ALGORITHM, ALTER, ALWAYS, ANALYZE, AND, ANY, AS, ASC, ASCII, ASENSITIVE, AT, AUTHORS, AUTO_INCREMENT,

AUTOEXTEND_SIZE, AUTO, AVG, AVG_ROW_LENGTH, BACKUP, BEFORE, BEGIN, BETWEEN, BIGINT, BINARY, BINLOG, BIT, BLOB, BLOCK, BODY, BOOL, BOOLEAN, BOTH, BTREE, BY, BYTE, CACHE, CALL, CASCADE, CASCADED, CASE,

CATALOG_NAME, CHAIN, CHANGE, CHANGED, CHAR, CHARACTER, CHARSET, CHECK, CHECKPOINT, CHECKSUM, CIPHER, CLASS_ORIGIN, CLIENT, CLIENT_STATISTICS, CLOSE, COALESCE, CODE, COLLATE, COLLATION, COLUMN, COLUMN_NAME,

COLUMNS, COLUMN_ADD, COLUMN_CHECK, COLUMN_CREATE, COLUMN_DELETE, COLUMN_GET, COMMENT, COMMIT, COMMITTED, COMPACT, COMPLETION, COMPRESSED, CONCURRENT, CONDITION, CONNECTION, CONSISTENT, CONSTRAINT, 

CONSTRAINT_CATALOG, CONSTRAINT_NAME, CONSTRAINT_SCHEMA, CONTAINS, CONTEXT, CONTINUE, CONTRIBUTORS, CONVERT, CPU, CREATE, CROSS, CUBE, CURRENT, CURRENT_DATE, CURRENT_POS, CURRENT_ROLE, CURRENT_TIME, 

CURRENT_TIMESTAMP, CURRENT_USER, CURSOR, CURSOR_NAME, CYCLE, DATA, DATABASE, DATABASES, DATAFILE, DATE, DATETIME, DAY, DAY_HOUR, DAY_MICROSECOND, DAY_MINUTE, DAY_SECOND, DEALLOCATE, DEC, DECIMAL, DECLARE, 

DEFAULT, DEFINER, DELAYED, DELAY_KEY_WRITE, DELETE, DESC, DESCRIBE, DES_KEY_FILE, DETERMINISTIC, DIAGNOSTICS, DIRECTORY, DISABLE, DISCARD, DISK, DISTINCT, DISTINCTROW, DIV, DO, DOUBLE, DROP, DUAL, DUMPFILE, 

DUPLICATE, DYNAMIC, EACH, ELSE, ELSEIF, ENABLE, ENCLOSED, END, ENDS, ENGINE, ENGINES, ENUM, ERROR, ERRORS, ESCAPE, ESCAPED, EVENT, EVENTS, EVERY, EXAMINED, EXCHANGE, EXECUTE, EXISTS, EXIT, EXPANSION, 

EXPORT, EXPLAIN, EXTENDED, EXTENT_SIZE, FALSE, FAST, FAULTS, FETCH, FIELDS, FILE, FIRST, FIXED, FLOAT, FLOAT4, FLOAT8, FLUSH, FOR, FORCE, FOREIGN, FOUND, FROM, FULL, FULLTEXT, FUNCTION, GENERAL, GENERATED, 

GEOMETRY, GEOMETRYCOLLECTION, GET_FORMAT, GET, GLOBAL, GRANT, GRANTS, GROUP, HANDLER, HARD, HASH, HAVING, HELP, HIGH_PRIORITY, HOST, HOSTS, HOUR, HOUR_MICROSECOND, HOUR_MINUTE, HOUR_SECOND, ID, IDENTIFIED, 

IF, IGNORE, IGNORE_SERVER_IDS, IMPORT, IN, INCREMENT, INDEX, INDEXES, INDEX_STATISTICS, INFILE, INITIAL_SIZE, INNER, INOUT, INSENSITIVE, INSERT, INSERT_METHOD, INSTALL, INT, INT1, INT2, INT3, INT4, INT8, 

INTEGER, INTERVAL, INTO, IO, IO_THREAD, IPC, IS, ISOLATION, ISSUER, ITERATE, INVOKER, JOIN, JSON, KEY, KEYS, KEY_BLOCK_SIZE, KILL, LANGUAGE, LAST, LAST_VALUE, LASTVAL, LEADING, LEAVE, LEAVES, LEFT, LESS, 

LEVEL, LIKE, LIMIT, LINEAR, LINES, LINESTRING, LIST, LOAD, LOCAL, LOCALTIME, LOCALTIMESTAMP, LOCK, LOCKS, LOGFILE, LOGS, LONG, LONGBLOB, LONGTEXT, LOOP, LOW_PRIORITY, MASTER, MASTER_CONNECT_RETRY,

MASTER_GTID_POS, MASTER_HOST, MASTER_LOG_FILE, MASTER_LOG_POS, MASTER_PASSWORD, MASTER_PORT, MASTER_SERVER_ID, MASTER_SSL, MASTER_SSL_CA, MASTER_SSL_CAPATH, MASTER_SSL_CERT, MASTER_SSL_CIPHER,

MASTER_SSL_CRL, MASTER_SSL_CRLPATH, MASTER_SSL_KEY, MASTER_SSL_VERIFY_SERVER_CERT, MASTER_USER, MASTER_USE_GTID, MASTER_HEARTBEAT_PERIOD, MATCH, MAX_CONNECTIONS_PER_HOUR, MAX_QUERIES_PER_HOUR, MAX_ROWS, 

MAX_SIZE, MAX_UPDATES_PER_HOUR, MAX_USER_CONNECTIONS, MAXVALUE, MEDIUM, MEDIUMBLOB, MEDIUMINT, MEDIUMTEXT, MEMORY, MERGE, MESSAGE_TEXT, MICROSECOND, MIDDLEINT, MIGRATE, MINUTE, MINUTE_MICROSECOND,

MINUTE_SECOND, MINVALUE, MIN_ROWS, MOD, MODE, MODIFIES, MODIFY, MONTH, MULTILINESTRING, MULTIPOINT, MULTIPOLYGON, MUTEX, MYSQL_ERRNO, NAME, NAMES, NATIONAL, NATURAL, NDB, NDBCLUSTER, NCHAR, NEW, NEXT, 

NEXTVAL, NO, NOMAXVALUE, NOMINVALUE, NOCACHE, NOCYCLE, NO_WAIT, NODEGROUP, NONE, NOT, NO_WRITE_TO_BINLOG, NULL, NUMBER, NUMERIC, NVARCHAR, OFFSET, OLD_PASSWORD, ON, ONE, ONLINE, ONLY, OPEN, OPTIMIZE, 

OPTIONS, OPTION, OPTIONALLY, OR, ORDER, OUT, OUTER, OUTFILE, OWNER, PACK_KEYS, PAGE, PAGE_CHECKSUM, PARSER, PARSE_VCOL_EXPR, PARTIAL, PARTITION, PARTITIONING, PARTITIONS, PASSWORD, PERSISTENT, PHASE, PLUGIN,

PLUGINS, POINT, POLYGON, PORT, PRECISION, PREPARE, PRESERVE, PREV, PREVIOUS, PRIMARY, PRIVILEGES, PROCEDURE, PROCESS, PROCESSLIST, PROFILE, PROFILES, PROXY, PURGE, QUARTER, QUERY, QUICK, RANGE, READ, 

READ_ONLY, READ_WRITE, READS, REAL, REBUILD, RECOVER, REDO_BUFFER_SIZE, REDOFILE, REDUNDANT, REFERENCES, REGEXP, RELAY, RELAYLOG, RELAY_LOG_FILE, RELAY_LOG_POS, RELAY_THREAD, RELEASE, RELOAD, REMOVE, RENAME, 

REORGANIZE, REPAIR, REPEATABLE, REPLACE, REPLICATION, REPEAT, REQUIRE, RESET, RESIGNAL, RESTART, RESTORE, RESTRICT, RESUME, RETURNED_SQLSTATE, RETURN, RETURNING, RETURNS, REUSE, REVERSE, REVOKE, RIGHT, RLIKE,

ROLE, ROLLBACK, ROLLUP, ROUTINE, ROW, ROW_COUNT, ROWS, ROW_FORMAT, RTREE, SAVEPOINT, SCHEDULE, SCHEMA, SCHEMA_NAME, SCHEMAS, SECOND,SECOND_MICROSECOND,SECURITY, SELECT, SENSITIVE, SEPARATOR, SEQUENCE, SERIAL,

SERIALIZABLE, SESSION, SERVER, SET, SETVAL, SHARDKEY, SHARE, SHOW, SHUTDOWN, SIGNAL, SIGNED, SIMPLE, SLAVE, SLAVES, SLAVE_POS, SLOW, SNAPSHOT, SMALLINT, SOCKET, SOFT, SOME, SONAME, SOUNDS, SOURCE, SPATIAL, 

SPECIFIC, SQL, SQLEXCEPTION, SQLSTATE, SQLWARNING, SQL_BIG_RESULT, SQL_BUFFER_RESULT, SQL_CACHE, SQL_CALC_FOUND_ROWS, SQL_NO_CACHE, SQL_SMALL_RESULT, SQL_THREAD, SQL_TSI_SECOND, SQL_TSI_MINUTE, SQL_TSI_HOUR,

SQL_TSI_DAY, SQL_TSI_WEEK, SQL_TSI_MONTH, SQL_TSI_QUARTER, SQL_TSI_YEAR, SSL, START, STARTING, STARTS, STATS_AUTO_RECALC, STATS_PERSISTENT, STATS_SAMPLE_PAGES, STATUS, STOP, STORAGE, STORED, STRAIGHT_JOIN, 

STRING, SUBCLASS_ORIGIN, SUBJECT, SUBPARTITION, SUBPARTITIONS, SUPER, SUSPEND, SWAPS, SWITCHES, TABLE, TABLE_NAME, TABLES, TABLESPACE, TABLE_STATISTICS, TABLE_CHECKSUM, TEMPORARY, TEMPTABLE, TERMINATED, TEXT,

THAN, THEN, TIME, TIMESTAMP, TIMESTAMPADD, TIMESTAMPDIFF, TINYBLOB, TINYINT, TINYTEXT, TO, TRAILING, TRANSACTION, TRANSACTIONAL, TRIGGER, TRIGGERS, TRUE, TRUNCATE, TYPE, TYPES, UNCOMMITTED, UNDEFINED, 

UNDO_BUFFER_SIZE, UNDOFILE, UNDO, UNICODE, UNION, UNIQUE, UNKNOWN, UNLOCK, UNINSTALL, UNSIGNED, UNTIL, UPDATE, UPGRADE, USAGE, USE, USER, USER_RESOURCES, USER_STATISTICS, USE_FRM, USING, UTC_DATE, UTC_TIME, 

UTC_TIMESTAMP, VALUE, VALUES, VARBINARY, VARCHAR, VARCHARACTER, VARIABLES, VARYING, VIA, VIEW, VIRTUAL, WAIT, WARNINGS, WEEK, WEIGHT_STRING, WHEN, WHERE, WHILE, WITH, WORK, WRAPPER, WRITE, X509, XOR, XA, XML, 

YEAR, YEAR_MONTH, ZEROFILL, ||, BOOST